@terreno/api 58.0.5 → 58.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +58 -0
- package/dist/actions.d.ts +6 -0
- package/dist/api.d.ts +21 -0
- package/dist/api.js +57 -32
- package/dist/bulk.d.ts +79 -0
- package/dist/bulk.js +449 -0
- package/dist/bulkOpenApi.d.ts +15 -0
- package/dist/bulkOpenApi.js +103 -0
- package/dist/bulkTransaction.d.ts +33 -0
- package/dist/bulkTransaction.js +126 -0
- package/dist/errors.d.ts +2 -0
- package/dist/errors.js +8 -6
- package/dist/index.d.ts +3 -2
- package/dist/index.js +6 -3
- package/dist/mcp/actionTools.js +2 -0
- package/dist/mcp/grantAccess.d.ts +27 -0
- package/dist/mcp/grantAccess.js +29 -0
- package/dist/mcp/oauth.js +86 -5
- package/dist/mcp/oauthMetadata.d.ts +32 -1
- package/dist/mcp/oauthMetadata.js +53 -2
- package/dist/mcp/registry.d.ts +8 -1
- package/dist/mcp/server.js +6 -1
- package/dist/mcp/toolGenerator.d.ts +5 -1
- package/dist/mcp/toolGenerator.js +11 -0
- package/dist/mcp/types.d.ts +11 -0
- package/dist/modelRouterWrites.d.ts +23 -0
- package/dist/modelRouterWrites.js +54 -0
- package/dist/openApi.d.ts +7 -0
- package/dist/openApi.js +6 -6
- package/dist/permissions.js +5 -4
- package/dist/rbac/access.js +2 -0
- package/dist/rbac/routes.js +1 -0
- package/dist/rbac/statements.d.ts +12 -1
- package/dist/rbac/statements.js +89 -1
- package/dist/rbac/types.d.ts +9 -2
- package/dist/sync/executors.d.ts +6 -4
- package/dist/sync/executors.js +6 -2
- package/package.json +6 -6
- package/src/actions.ts +6 -0
- package/src/api.ts +95 -33
- package/src/bulk.test.ts +1256 -0
- package/src/bulk.ts +680 -0
- package/src/bulkOpenApi.test.ts +172 -0
- package/src/bulkOpenApi.ts +126 -0
- package/src/bulkTransaction.test.ts +197 -0
- package/src/bulkTransaction.ts +149 -0
- package/src/errors.ts +2 -2
- package/src/index.ts +6 -0
- package/src/isolated/bulkAtomic.isolated.ts +630 -0
- package/src/isolated/bulkStandalone.isolated.ts +133 -0
- package/src/isolated/mongoTopology.isolated.ts +29 -0
- package/src/mcp/actionTools.ts +2 -0
- package/src/mcp/grantAccess.test.ts +107 -0
- package/src/mcp/grantAccess.ts +49 -0
- package/src/mcp/oauth.test.ts +327 -0
- package/src/mcp/oauth.ts +113 -5
- package/src/mcp/oauthMetadata.test.ts +125 -1
- package/src/mcp/oauthMetadata.ts +99 -2
- package/src/mcp/registry.ts +8 -1
- package/src/mcp/server.test.ts +419 -2
- package/src/mcp/server.ts +8 -1
- package/src/mcp/toolGenerator.ts +17 -0
- package/src/mcp/types.ts +12 -0
- package/src/modelRouterWrites.ts +72 -0
- package/src/openApi.ts +1 -1
- package/src/permissions.ts +5 -5
- package/src/rbac/access.ts +3 -1
- package/src/rbac/routes.test.ts +15 -0
- package/src/rbac/routes.ts +1 -0
- package/src/rbac/statements.test.ts +23 -0
- package/src/rbac/statements.ts +100 -1
- package/src/rbac/types.ts +9 -2
- package/src/sync/executors.test.ts +27 -0
- package/src/sync/executors.ts +12 -4
- package/src/tests/mongoTopology.ts +53 -0
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
import {beforeEach, describe, expect, it} from "bun:test";
|
|
2
|
+
import type express from "express";
|
|
3
|
+
import supertest from "supertest";
|
|
4
|
+
import {type ModelRouterOptions, modelRouter} from "./api";
|
|
5
|
+
import type {UserModel as AuthUserModel} from "./auth";
|
|
6
|
+
import {Permissions} from "./permissions";
|
|
7
|
+
import {TerrenoApp} from "./terrenoApp";
|
|
8
|
+
import {type Food, FoodModel, UserModel} from "./tests";
|
|
9
|
+
|
|
10
|
+
// OpenAPI documents are read as plain JSON; `at` walks a path of keys and yields unknown.
|
|
11
|
+
type Json = unknown;
|
|
12
|
+
|
|
13
|
+
const at = (node: Json, ...path: string[]): Json =>
|
|
14
|
+
path.reduce<Json>(
|
|
15
|
+
(acc, key) =>
|
|
16
|
+
acc !== null && typeof acc === "object" ? (acc as Record<string, Json>)[key] : undefined,
|
|
17
|
+
node
|
|
18
|
+
);
|
|
19
|
+
|
|
20
|
+
const keysOf = (node: Json): string[] =>
|
|
21
|
+
node !== null && typeof node === "object" ? Object.keys(node) : [];
|
|
22
|
+
|
|
23
|
+
const allowAll = {
|
|
24
|
+
create: [Permissions.IsAny],
|
|
25
|
+
delete: [Permissions.IsAny],
|
|
26
|
+
list: [Permissions.IsAny],
|
|
27
|
+
read: [Permissions.IsAny],
|
|
28
|
+
update: [Permissions.IsAny],
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const buildSpec = async (bulk?: ModelRouterOptions<Food>["bulk"]): Promise<Json> => {
|
|
32
|
+
process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
|
|
33
|
+
process.env.ENABLE_SWAGGER = "true";
|
|
34
|
+
const app = new TerrenoApp({
|
|
35
|
+
configureApp: (router, appOptions) => {
|
|
36
|
+
router.use(
|
|
37
|
+
"/food",
|
|
38
|
+
modelRouter(FoodModel, {
|
|
39
|
+
...(appOptions as Partial<ModelRouterOptions<Food>>),
|
|
40
|
+
allowAnonymous: true,
|
|
41
|
+
...(bulk === undefined ? {} : {bulk}),
|
|
42
|
+
permissions: allowAll,
|
|
43
|
+
} as Partial<ModelRouterOptions<Food>> as ModelRouterOptions<Food>)
|
|
44
|
+
);
|
|
45
|
+
},
|
|
46
|
+
skipListen: true,
|
|
47
|
+
userModel: UserModel as unknown as AuthUserModel,
|
|
48
|
+
}).build() as express.Application;
|
|
49
|
+
const res = await supertest(app).get("/openapi.json").expect(200);
|
|
50
|
+
return res.body;
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
// Resolves local $refs so assertions do not depend on whether a schema is inlined or shared.
|
|
54
|
+
const resolve = (spec: Json, node: Json, depth = 0): Json => {
|
|
55
|
+
if (depth > 12 || node === null || typeof node !== "object") {
|
|
56
|
+
return node;
|
|
57
|
+
}
|
|
58
|
+
if (Array.isArray(node)) {
|
|
59
|
+
return node.map((item) => resolve(spec, item, depth + 1));
|
|
60
|
+
}
|
|
61
|
+
const ref = at(node, "$ref");
|
|
62
|
+
if (typeof ref === "string") {
|
|
63
|
+
return resolve(spec, at(spec, ...ref.replace(/^#\//, "").split("/")), depth + 1);
|
|
64
|
+
}
|
|
65
|
+
return Object.fromEntries(
|
|
66
|
+
Object.entries(node).map(([key, value]) => [key, resolve(spec, value, depth + 1)])
|
|
67
|
+
);
|
|
68
|
+
};
|
|
69
|
+
|
|
70
|
+
const bulkPost = (spec: Json): Json => at(spec, "paths", "/food/bulk", "post");
|
|
71
|
+
const requestSchema = (spec: Json): Json =>
|
|
72
|
+
resolve(spec, at(bulkPost(spec), "requestBody", "content", "application/json", "schema"));
|
|
73
|
+
const okSchema = (spec: Json): Json =>
|
|
74
|
+
resolve(spec, at(bulkPost(spec), "responses", "200", "content", "application/json", "schema"));
|
|
75
|
+
const operationsItem = (spec: Json): Json =>
|
|
76
|
+
at(requestSchema(spec), "properties", "operations", "items");
|
|
77
|
+
|
|
78
|
+
describe("bulk OpenAPI", () => {
|
|
79
|
+
let spec: Json;
|
|
80
|
+
|
|
81
|
+
describe("bulk: true", () => {
|
|
82
|
+
beforeEach(async () => {
|
|
83
|
+
spec = await buildSpec(true);
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
it("documents POST /food/bulk with the {tag}_bulk operationId", () => {
|
|
87
|
+
expect(bulkPost(spec)).toBeDefined();
|
|
88
|
+
// Tag is the collection name ("foods"), as for actions (`${tag}_${actionName}`).
|
|
89
|
+
expect(at(bulkPost(spec), "tags")).toEqual(["foods"]);
|
|
90
|
+
expect(at(bulkPost(spec), "operationId")).toBe("foods_bulk");
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
it("lists create, update, delete in the method enum", () => {
|
|
94
|
+
expect(at(operationsItem(spec), "properties", "method", "enum")).toEqual([
|
|
95
|
+
"create",
|
|
96
|
+
"update",
|
|
97
|
+
"delete",
|
|
98
|
+
]);
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
it("documents the request envelope", () => {
|
|
102
|
+
const schema = requestSchema(spec);
|
|
103
|
+
expect(at(schema, "properties", "atomic", "type")).toBe("boolean");
|
|
104
|
+
expect(at(schema, "properties", "operations", "type")).toBe("array");
|
|
105
|
+
expect(at(schema, "required")).toContain("operations");
|
|
106
|
+
expect(at(schema, "required") ?? []).not.toContain("atomic");
|
|
107
|
+
const item = at(schema, "properties", "operations", "items");
|
|
108
|
+
expect(at(item, "required")).toContain("method");
|
|
109
|
+
expect(keysOf(at(item, "properties"))).toEqual(
|
|
110
|
+
expect.arrayContaining(["method", "id", "body"])
|
|
111
|
+
);
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
it("item body carries the model's writable fields", () => {
|
|
115
|
+
const body = at(operationsItem(spec), "properties", "body");
|
|
116
|
+
expect(JSON.stringify(body)).toContain('"calories"');
|
|
117
|
+
expect(JSON.stringify(body)).toContain('"name"');
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
it("documents maxItems as the default 100", () => {
|
|
121
|
+
expect(at(requestSchema(spec), "properties", "operations", "maxItems")).toBe(100);
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
it("200 is {data: result[]} with data typed as the model response", () => {
|
|
125
|
+
const schema = okSchema(spec);
|
|
126
|
+
expect(at(schema, "properties", "data", "type")).toBe("array");
|
|
127
|
+
const entry = at(schema, "properties", "data", "items");
|
|
128
|
+
expect(keysOf(at(entry, "properties"))).toEqual(
|
|
129
|
+
expect.arrayContaining(["index", "method", "id", "status", "data"])
|
|
130
|
+
);
|
|
131
|
+
expect(JSON.stringify(at(entry, "properties", "data"))).toContain('"calories"');
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
it("400 and 401 use the standard APIError schema", () => {
|
|
135
|
+
const responses = at(bulkPost(spec), "responses");
|
|
136
|
+
expect(at(responses, "400")).toBeDefined();
|
|
137
|
+
expect(at(responses, "401")).toBeDefined();
|
|
138
|
+
expect(at(responses, "400", "content", "application/json", "schema", "$ref")).toBe(
|
|
139
|
+
"#/components/schemas/APIError"
|
|
140
|
+
);
|
|
141
|
+
expect(at(responses, "401", "content", "application/json", "schema", "$ref")).toBe(
|
|
142
|
+
"#/components/schemas/APIError"
|
|
143
|
+
);
|
|
144
|
+
});
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
it("bulk: {methods: ['update']} narrows the enum to update", async () => {
|
|
148
|
+
spec = await buildSpec({methods: ["update"]});
|
|
149
|
+
expect(at(operationsItem(spec), "properties", "method", "enum")).toEqual(["update"]);
|
|
150
|
+
});
|
|
151
|
+
|
|
152
|
+
it("bulk: {methods: ['create','delete']} omits update", async () => {
|
|
153
|
+
spec = await buildSpec({methods: ["create", "delete"]});
|
|
154
|
+
expect(at(operationsItem(spec), "properties", "method", "enum")).toEqual(["create", "delete"]);
|
|
155
|
+
});
|
|
156
|
+
|
|
157
|
+
it("bulk: {maxItems: 5} documents maxItems 5", async () => {
|
|
158
|
+
spec = await buildSpec({maxItems: 5});
|
|
159
|
+
expect(at(requestSchema(spec), "properties", "operations", "maxItems")).toBe(5);
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
it("without bulk there is no /food/bulk path", async () => {
|
|
163
|
+
spec = await buildSpec();
|
|
164
|
+
expect(at(spec, "paths", "/food/bulk")).toBeUndefined();
|
|
165
|
+
expect(JSON.stringify(spec)).not.toContain("_bulk");
|
|
166
|
+
});
|
|
167
|
+
|
|
168
|
+
it("bulk: false documents no /food/bulk path", async () => {
|
|
169
|
+
spec = await buildSpec(false);
|
|
170
|
+
expect(at(spec, "paths", "/food/bulk")).toBeUndefined();
|
|
171
|
+
});
|
|
172
|
+
});
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* OpenAPI documentation for a modelRouter's `POST /bulk` (see `bulk.ts`), so generated SDKs
|
|
3
|
+
* (syncdb `--api-out`) get a typed hook for it.
|
|
4
|
+
*/
|
|
5
|
+
import type express from "express";
|
|
6
|
+
import merge from "lodash/merge";
|
|
7
|
+
import type {Model} from "mongoose";
|
|
8
|
+
|
|
9
|
+
import type {ModelRouterOptions} from "./api";
|
|
10
|
+
import type {BulkMethod} from "./bulk";
|
|
11
|
+
import {apiErrorContent, defaultOpenApiErrorResponses} from "./openApi";
|
|
12
|
+
import {getOpenApiSpecForModel} from "./populate";
|
|
13
|
+
|
|
14
|
+
const passThrough: express.RequestHandler = (_req, _res, next) => next();
|
|
15
|
+
|
|
16
|
+
/** Builds the OpenAPI middleware for `POST /bulk`, or a pass-through when OpenAPI is off. */
|
|
17
|
+
export const bulkOpenApiMiddleware = <T>({
|
|
18
|
+
model,
|
|
19
|
+
options,
|
|
20
|
+
maxItems,
|
|
21
|
+
methods,
|
|
22
|
+
}: {
|
|
23
|
+
model: Model<T>;
|
|
24
|
+
options: Partial<ModelRouterOptions<T>>;
|
|
25
|
+
maxItems: number;
|
|
26
|
+
methods: BulkMethod[];
|
|
27
|
+
}): express.RequestHandler => {
|
|
28
|
+
if (!options.openApi?.path) {
|
|
29
|
+
return passThrough;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const tag = model.collection.collectionName;
|
|
33
|
+
const {properties, required} = getOpenApiSpecForModel(model, {
|
|
34
|
+
extraModelProperties: options.openApiExtraModelProperties,
|
|
35
|
+
populatePaths: options.populatePaths,
|
|
36
|
+
});
|
|
37
|
+
const modelResponse = {
|
|
38
|
+
properties,
|
|
39
|
+
required: [...required, "_id", "created", "updated"],
|
|
40
|
+
type: "object",
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
return options.openApi.path(
|
|
44
|
+
merge(
|
|
45
|
+
{
|
|
46
|
+
description:
|
|
47
|
+
"Run many create/update/delete operations through this router's permissions, hooks, " +
|
|
48
|
+
"and responseHandler. With atomic (default true) the batch commits or rolls back " +
|
|
49
|
+
"together; with atomic: false each item reports its own status.",
|
|
50
|
+
operationId: `${tag}_bulk`,
|
|
51
|
+
requestBody: {
|
|
52
|
+
content: {
|
|
53
|
+
"application/json": {
|
|
54
|
+
schema: {
|
|
55
|
+
properties: {
|
|
56
|
+
atomic: {
|
|
57
|
+
default: true,
|
|
58
|
+
description:
|
|
59
|
+
"Commit every operation in one transaction (requires a replica set)",
|
|
60
|
+
type: "boolean",
|
|
61
|
+
},
|
|
62
|
+
operations: {
|
|
63
|
+
items: {
|
|
64
|
+
properties: {
|
|
65
|
+
body: {
|
|
66
|
+
description: "Document fields for create and update",
|
|
67
|
+
properties,
|
|
68
|
+
type: "object",
|
|
69
|
+
},
|
|
70
|
+
id: {description: "Document id for update and delete", type: "string"},
|
|
71
|
+
method: {enum: methods, type: "string"},
|
|
72
|
+
},
|
|
73
|
+
required: ["method"],
|
|
74
|
+
type: "object",
|
|
75
|
+
},
|
|
76
|
+
maxItems,
|
|
77
|
+
minItems: 1,
|
|
78
|
+
type: "array",
|
|
79
|
+
},
|
|
80
|
+
},
|
|
81
|
+
required: ["operations"],
|
|
82
|
+
type: "object",
|
|
83
|
+
},
|
|
84
|
+
},
|
|
85
|
+
},
|
|
86
|
+
required: true,
|
|
87
|
+
},
|
|
88
|
+
responses: {
|
|
89
|
+
200: {
|
|
90
|
+
content: {
|
|
91
|
+
"application/json": {
|
|
92
|
+
schema: {
|
|
93
|
+
properties: {
|
|
94
|
+
data: {
|
|
95
|
+
items: {
|
|
96
|
+
properties: {
|
|
97
|
+
data: modelResponse,
|
|
98
|
+
error: {$ref: "#/components/schemas/APIError"},
|
|
99
|
+
id: {type: "string"},
|
|
100
|
+
index: {type: "number"},
|
|
101
|
+
method: {enum: methods, type: "string"},
|
|
102
|
+
status: {type: "number"},
|
|
103
|
+
},
|
|
104
|
+
required: ["index", "method", "status"],
|
|
105
|
+
type: "object",
|
|
106
|
+
},
|
|
107
|
+
type: "array",
|
|
108
|
+
},
|
|
109
|
+
},
|
|
110
|
+
required: ["data"],
|
|
111
|
+
type: "object",
|
|
112
|
+
},
|
|
113
|
+
},
|
|
114
|
+
},
|
|
115
|
+
description: "One result per operation, in input order",
|
|
116
|
+
},
|
|
117
|
+
...defaultOpenApiErrorResponses,
|
|
118
|
+
401: {content: apiErrorContent, description: "The user must be authenticated"},
|
|
119
|
+
},
|
|
120
|
+
summary: `Bulk write ${tag}`,
|
|
121
|
+
tags: [tag],
|
|
122
|
+
},
|
|
123
|
+
options.openApiOverwrite?.bulk ?? {}
|
|
124
|
+
)
|
|
125
|
+
);
|
|
126
|
+
};
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
import {describe, expect, it} from "bun:test";
|
|
2
|
+
import mongoose, {type ClientSession, type Connection} from "mongoose";
|
|
3
|
+
|
|
4
|
+
import {
|
|
5
|
+
enableTransactionAsyncLocalStorage,
|
|
6
|
+
isBulkCommitUnknownError,
|
|
7
|
+
isTransientTransactionError,
|
|
8
|
+
runInBulkTransaction,
|
|
9
|
+
supportsTransactions,
|
|
10
|
+
} from "./bulkTransaction";
|
|
11
|
+
|
|
12
|
+
const labelled = (label: string): Error => Object.assign(new Error(label), {errorLabels: [label]});
|
|
13
|
+
|
|
14
|
+
interface FakeSession {
|
|
15
|
+
calls: string[];
|
|
16
|
+
session: ClientSession;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
// A session whose commit fails with the given errors in order, then succeeds.
|
|
20
|
+
const fakeSession = (commitErrors: Error[] = []): FakeSession => {
|
|
21
|
+
const calls: string[] = [];
|
|
22
|
+
const session = {
|
|
23
|
+
abortTransaction: async (): Promise<void> => {
|
|
24
|
+
calls.push("abort");
|
|
25
|
+
},
|
|
26
|
+
commitTransaction: async (): Promise<void> => {
|
|
27
|
+
calls.push("commit");
|
|
28
|
+
const next = commitErrors.shift();
|
|
29
|
+
if (next) {
|
|
30
|
+
throw next;
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
endSession: async (): Promise<void> => {
|
|
34
|
+
calls.push("end");
|
|
35
|
+
},
|
|
36
|
+
startTransaction: (): void => {
|
|
37
|
+
calls.push("start");
|
|
38
|
+
},
|
|
39
|
+
} as unknown as ClientSession;
|
|
40
|
+
return {calls, session};
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
const connectionFor = (session: ClientSession): Connection =>
|
|
44
|
+
({startSession: async () => session}) as unknown as Connection;
|
|
45
|
+
|
|
46
|
+
const transactionBase = (): mongoose.Mongoose => {
|
|
47
|
+
const base = new mongoose.Mongoose();
|
|
48
|
+
enableTransactionAsyncLocalStorage(base);
|
|
49
|
+
return base;
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
describe("runInBulkTransaction", () => {
|
|
53
|
+
it("commits once and ends the session when fn resolves", async () => {
|
|
54
|
+
const {calls, session} = fakeSession();
|
|
55
|
+
const result = await runInBulkTransaction({
|
|
56
|
+
base: transactionBase(),
|
|
57
|
+
connection: connectionFor(session),
|
|
58
|
+
fn: async () => "done",
|
|
59
|
+
});
|
|
60
|
+
expect(result).toBe("done");
|
|
61
|
+
expect(calls).toEqual(["start", "commit", "end"]);
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
it("runs fn with the session in the transaction store", async () => {
|
|
65
|
+
const base = transactionBase();
|
|
66
|
+
const {session} = fakeSession();
|
|
67
|
+
const seen = await runInBulkTransaction({
|
|
68
|
+
base,
|
|
69
|
+
connection: connectionFor(session),
|
|
70
|
+
fn: async () =>
|
|
71
|
+
(
|
|
72
|
+
base as unknown as {
|
|
73
|
+
transactionAsyncLocalStorage: {getStore: () => {session: ClientSession}};
|
|
74
|
+
}
|
|
75
|
+
).transactionAsyncLocalStorage.getStore().session,
|
|
76
|
+
});
|
|
77
|
+
expect(seen).toBe(session);
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
it("aborts, ends the session, and rethrows when fn throws", async () => {
|
|
81
|
+
const {calls, session} = fakeSession();
|
|
82
|
+
const failure = new Error("item failed");
|
|
83
|
+
await expect(
|
|
84
|
+
runInBulkTransaction({
|
|
85
|
+
base: transactionBase(),
|
|
86
|
+
connection: connectionFor(session),
|
|
87
|
+
fn: async () => {
|
|
88
|
+
throw failure;
|
|
89
|
+
},
|
|
90
|
+
})
|
|
91
|
+
).rejects.toBe(failure);
|
|
92
|
+
expect(calls).toEqual(["start", "abort", "end"]);
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
it("retries the commit once on UnknownTransactionCommitResult and succeeds", async () => {
|
|
96
|
+
const {calls, session} = fakeSession([labelled("UnknownTransactionCommitResult")]);
|
|
97
|
+
const result = await runInBulkTransaction({
|
|
98
|
+
base: transactionBase(),
|
|
99
|
+
connection: connectionFor(session),
|
|
100
|
+
fn: async () => 1,
|
|
101
|
+
});
|
|
102
|
+
expect(result).toBe(1);
|
|
103
|
+
expect(calls).toEqual(["start", "commit", "commit", "end"]);
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
it("reports a second UnknownTransactionCommitResult as an unknown outcome, not a conflict", async () => {
|
|
107
|
+
const {calls, session} = fakeSession([
|
|
108
|
+
labelled("UnknownTransactionCommitResult"),
|
|
109
|
+
labelled("UnknownTransactionCommitResult"),
|
|
110
|
+
]);
|
|
111
|
+
let thrown: unknown;
|
|
112
|
+
try {
|
|
113
|
+
await runInBulkTransaction({
|
|
114
|
+
base: transactionBase(),
|
|
115
|
+
connection: connectionFor(session),
|
|
116
|
+
fn: async () => 1,
|
|
117
|
+
});
|
|
118
|
+
} catch (error: unknown) {
|
|
119
|
+
thrown = error;
|
|
120
|
+
}
|
|
121
|
+
expect(isBulkCommitUnknownError(thrown)).toBe(true);
|
|
122
|
+
expect(isTransientTransactionError(thrown)).toBe(false);
|
|
123
|
+
expect(calls).toEqual(["start", "commit", "commit", "end"]);
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
it("rethrows a TransientTransactionError from commit without retrying", async () => {
|
|
127
|
+
const conflict = labelled("TransientTransactionError");
|
|
128
|
+
const {calls, session} = fakeSession([conflict]);
|
|
129
|
+
await expect(
|
|
130
|
+
runInBulkTransaction({
|
|
131
|
+
base: transactionBase(),
|
|
132
|
+
connection: connectionFor(session),
|
|
133
|
+
fn: async () => 1,
|
|
134
|
+
})
|
|
135
|
+
).rejects.toBe(conflict);
|
|
136
|
+
expect(calls).toEqual(["start", "commit", "end"]);
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
it("refuses to run when transactionAsyncLocalStorage is off", async () => {
|
|
140
|
+
const {session} = fakeSession();
|
|
141
|
+
await expect(
|
|
142
|
+
runInBulkTransaction({
|
|
143
|
+
base: new mongoose.Mongoose(),
|
|
144
|
+
connection: connectionFor(session),
|
|
145
|
+
fn: async () => 1,
|
|
146
|
+
})
|
|
147
|
+
).rejects.toThrow("transactionAsyncLocalStorage is not enabled");
|
|
148
|
+
});
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
describe("isTransientTransactionError", () => {
|
|
152
|
+
it("finds the label on a wrapped cause", () => {
|
|
153
|
+
const wrapped = new Error("wrapped", {cause: labelled("TransientTransactionError")});
|
|
154
|
+
expect(isTransientTransactionError(wrapped)).toBe(true);
|
|
155
|
+
});
|
|
156
|
+
|
|
157
|
+
it("does not treat an unknown commit result or a plain error as transient", () => {
|
|
158
|
+
expect(isTransientTransactionError(labelled("UnknownTransactionCommitResult"))).toBe(false);
|
|
159
|
+
expect(isTransientTransactionError(new Error("plain"))).toBe(false);
|
|
160
|
+
});
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
describe("supportsTransactions", () => {
|
|
164
|
+
it("is false for a connection with no database, and probes again once it connects", async () => {
|
|
165
|
+
const connection = {db: undefined} as unknown as {db: unknown};
|
|
166
|
+
expect(await supportsTransactions(connection as unknown as Connection)).toBe(false);
|
|
167
|
+
connection.db = {admin: () => ({command: async () => ({setName: "rs0"})})};
|
|
168
|
+
expect(await supportsTransactions(connection as unknown as Connection)).toBe(true);
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
it("is true for a replica set and false for a standalone server", async () => {
|
|
172
|
+
const connectionWithHello = (hello: Record<string, unknown>): Connection =>
|
|
173
|
+
({db: {admin: () => ({command: async () => hello})}}) as unknown as Connection;
|
|
174
|
+
expect(await supportsTransactions(connectionWithHello({setName: "rs0"}))).toBe(true);
|
|
175
|
+
expect(await supportsTransactions(connectionWithHello({msg: "isdbgrid"}))).toBe(true);
|
|
176
|
+
expect(await supportsTransactions(connectionWithHello({}))).toBe(false);
|
|
177
|
+
});
|
|
178
|
+
|
|
179
|
+
it("does not cache a failed probe", async () => {
|
|
180
|
+
let attempts = 0;
|
|
181
|
+
const connection = {
|
|
182
|
+
db: {
|
|
183
|
+
admin: () => ({
|
|
184
|
+
command: async (): Promise<Record<string, unknown>> => {
|
|
185
|
+
attempts += 1;
|
|
186
|
+
if (attempts === 1) {
|
|
187
|
+
throw new Error("probe failed");
|
|
188
|
+
}
|
|
189
|
+
return {setName: "rs0"};
|
|
190
|
+
},
|
|
191
|
+
}),
|
|
192
|
+
},
|
|
193
|
+
} as unknown as Connection;
|
|
194
|
+
await expect(supportsTransactions(connection)).rejects.toThrow("probe failed");
|
|
195
|
+
expect(await supportsTransactions(connection)).toBe(true);
|
|
196
|
+
});
|
|
197
|
+
});
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Transaction plumbing for atomic `POST /bulk` (see `bulk.ts`).
|
|
3
|
+
*
|
|
4
|
+
* Atomic bulk runs every item inside one Mongo transaction joined through Mongoose's
|
|
5
|
+
* `transactionAsyncLocalStorage`: inside {@link runInBulkTransaction}, every Mongoose operation
|
|
6
|
+
* (including writes made by router hooks) picks up the session without passing it explicitly.
|
|
7
|
+
* There is no automatic retry, because a retry would run `pre*` hooks twice.
|
|
8
|
+
*/
|
|
9
|
+
import type {AsyncLocalStorage} from "node:async_hooks";
|
|
10
|
+
import type {ClientSession, Connection, Mongoose} from "mongoose";
|
|
11
|
+
|
|
12
|
+
import {APIError} from "./errors";
|
|
13
|
+
|
|
14
|
+
interface TransactionStore {
|
|
15
|
+
session: ClientSession;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
type MongooseWithTransactionStore = Mongoose & {
|
|
19
|
+
transactionAsyncLocalStorage?: AsyncLocalStorage<TransactionStore>;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
const transactionSupport = new WeakMap<Connection, Promise<boolean>>();
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Turns on `transactionAsyncLocalStorage` for a Mongoose instance. This is app-wide: from then on
|
|
26
|
+
* every Mongoose operation inside any transaction store joins that transaction, including stores
|
|
27
|
+
* opened by the app's own `connection.transaction()` calls. Operations outside a store are
|
|
28
|
+
* unaffected.
|
|
29
|
+
*/
|
|
30
|
+
export const enableTransactionAsyncLocalStorage = (base: Mongoose): void => {
|
|
31
|
+
if (!base.get("transactionAsyncLocalStorage")) {
|
|
32
|
+
base.set("transactionAsyncLocalStorage", true);
|
|
33
|
+
}
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
/** Whether the connection's deployment supports transactions (replica set or sharded). */
|
|
37
|
+
export const supportsTransactions = (connection: Connection): Promise<boolean> => {
|
|
38
|
+
const cached = transactionSupport.get(connection);
|
|
39
|
+
if (cached) {
|
|
40
|
+
return cached;
|
|
41
|
+
}
|
|
42
|
+
const db = connection.db;
|
|
43
|
+
if (!db) {
|
|
44
|
+
// Not connected yet: answer for now, but probe again once the connection opens.
|
|
45
|
+
return Promise.resolve(false);
|
|
46
|
+
}
|
|
47
|
+
const check = (async (): Promise<boolean> => {
|
|
48
|
+
const hello = await db.admin().command({hello: 1});
|
|
49
|
+
return Boolean(hello.setName) || hello.msg === "isdbgrid";
|
|
50
|
+
})();
|
|
51
|
+
// Do not cache a failed probe; the next request tries again.
|
|
52
|
+
check.catch(() => transactionSupport.delete(connection));
|
|
53
|
+
transactionSupport.set(connection, check);
|
|
54
|
+
return check;
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
const hasErrorLabel = (error: unknown, label: string): boolean => {
|
|
58
|
+
const labelled = error as {hasErrorLabel?: (name: string) => boolean; errorLabels?: string[]};
|
|
59
|
+
if (typeof labelled?.hasErrorLabel === "function" && labelled.hasErrorLabel(label)) {
|
|
60
|
+
return true;
|
|
61
|
+
}
|
|
62
|
+
return Array.isArray(labelled?.errorLabels) && labelled.errorLabels.includes(label);
|
|
63
|
+
};
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Whether an error (or any error in its `cause` chain, since executors wrap driver errors in
|
|
67
|
+
* APIErrors) is a transient transaction failure, such as a write conflict: the transaction was
|
|
68
|
+
* aborted and nothing it wrote is visible.
|
|
69
|
+
*/
|
|
70
|
+
export const isTransientTransactionError = (error: unknown): boolean => {
|
|
71
|
+
let current: unknown = error;
|
|
72
|
+
for (let depth = 0; current && depth < 5; depth += 1) {
|
|
73
|
+
if (hasErrorLabel(current, "TransientTransactionError")) {
|
|
74
|
+
return true;
|
|
75
|
+
}
|
|
76
|
+
current = (current as {cause?: unknown}).cause;
|
|
77
|
+
}
|
|
78
|
+
return false;
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
/** Thrown when a commit's outcome stays unknown after one retry: the writes may have landed. */
|
|
82
|
+
export class BulkCommitUnknownError extends Error {
|
|
83
|
+
readonly isBulkCommitUnknown = true;
|
|
84
|
+
|
|
85
|
+
constructor(readonly cause: unknown) {
|
|
86
|
+
super("Bulk transaction commit outcome is unknown");
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
export const isBulkCommitUnknownError = (error: unknown): error is BulkCommitUnknownError =>
|
|
91
|
+
Boolean((error as {isBulkCommitUnknown?: unknown} | undefined)?.isBulkCommitUnknown);
|
|
92
|
+
|
|
93
|
+
// The driver's guidance for UnknownTransactionCommitResult: retry the commit itself, which is
|
|
94
|
+
// safe and runs no hooks again. A second unknown result is reported, never guessed.
|
|
95
|
+
const commitWithOneRetry = async (session: ClientSession): Promise<void> => {
|
|
96
|
+
try {
|
|
97
|
+
await session.commitTransaction();
|
|
98
|
+
} catch (error: unknown) {
|
|
99
|
+
if (!hasErrorLabel(error, "UnknownTransactionCommitResult")) {
|
|
100
|
+
throw error;
|
|
101
|
+
}
|
|
102
|
+
try {
|
|
103
|
+
await session.commitTransaction();
|
|
104
|
+
} catch (retryError: unknown) {
|
|
105
|
+
if (hasErrorLabel(retryError, "UnknownTransactionCommitResult")) {
|
|
106
|
+
throw new BulkCommitUnknownError(retryError);
|
|
107
|
+
}
|
|
108
|
+
throw retryError;
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Runs `fn` inside one transaction on `connection`, with every Mongoose operation of `base`
|
|
115
|
+
* joined to it. Commits when `fn` resolves; aborts and rethrows when it throws. Work `fn` starts
|
|
116
|
+
* without awaiting keeps the session after the transaction ends, so it must leave the store.
|
|
117
|
+
*/
|
|
118
|
+
export const runInBulkTransaction = async <R>({
|
|
119
|
+
base,
|
|
120
|
+
connection,
|
|
121
|
+
fn,
|
|
122
|
+
}: {
|
|
123
|
+
base: Mongoose;
|
|
124
|
+
connection: Connection;
|
|
125
|
+
fn: () => Promise<R>;
|
|
126
|
+
}): Promise<R> => {
|
|
127
|
+
const storage = (base as MongooseWithTransactionStore).transactionAsyncLocalStorage;
|
|
128
|
+
if (!storage) {
|
|
129
|
+
throw new APIError({
|
|
130
|
+
status: 500,
|
|
131
|
+
title: "transactionAsyncLocalStorage is not enabled on this Mongoose instance",
|
|
132
|
+
});
|
|
133
|
+
}
|
|
134
|
+
const session = await connection.startSession();
|
|
135
|
+
try {
|
|
136
|
+
session.startTransaction();
|
|
137
|
+
let result: R;
|
|
138
|
+
try {
|
|
139
|
+
result = await storage.run({session}, fn);
|
|
140
|
+
} catch (error: unknown) {
|
|
141
|
+
await session.abortTransaction().catch(() => undefined);
|
|
142
|
+
throw error;
|
|
143
|
+
}
|
|
144
|
+
await commitWithOneRetry(session);
|
|
145
|
+
return result;
|
|
146
|
+
} finally {
|
|
147
|
+
await session.endSession();
|
|
148
|
+
}
|
|
149
|
+
};
|
package/src/errors.ts
CHANGED
|
@@ -378,7 +378,7 @@ export const getDisableExternalErrorTracking = (error: unknown): boolean | undef
|
|
|
378
378
|
|
|
379
379
|
// Builds the client-facing JSONAPI body from any APIError-shaped error, including instances from
|
|
380
380
|
// older/duplicate copies of @terreno/api that may not have toJSON.
|
|
381
|
-
const serializeAPIError = (error: APIError): APIErrorBody => {
|
|
381
|
+
export const serializeAPIError = (error: APIError): APIErrorBody => {
|
|
382
382
|
const indexable = error as unknown as Record<string, unknown>;
|
|
383
383
|
// Prefer an explicit title property for legacy/duplicate-package instances whose message was
|
|
384
384
|
// polluted with detail/cause stacks but still carry a clean title field.
|
|
@@ -562,7 +562,7 @@ export const passthroughOrWrapWrite = (error: unknown, wrapper: APIErrorOptions)
|
|
|
562
562
|
// Sentry unless external tracking is disabled. Fingerprints on the logical error type
|
|
563
563
|
// (name + code/title + status) so unrelated errors constructed at the same framework lines don't
|
|
564
564
|
// group together, while the `cause` chain preserves each occurrence's real origin stack.
|
|
565
|
-
const logAndCaptureAPIError = (err: APIError): void => {
|
|
565
|
+
export const logAndCaptureAPIError = (err: APIError): void => {
|
|
566
566
|
const cause = err.cause;
|
|
567
567
|
const causeStack = cause instanceof Error && cause.stack ? `\n${cause.stack}` : "";
|
|
568
568
|
const logMessage = `${err.name}(${err.status}): ${err.message}${
|
package/src/index.ts
CHANGED
|
@@ -92,11 +92,16 @@ export {
|
|
|
92
92
|
type MCPAuthContext,
|
|
93
93
|
type MCPAuthResult,
|
|
94
94
|
} from "./mcp/auth";
|
|
95
|
+
export {type CanUseMcpToolOptions, canUseMcpTool} from "./mcp/grantAccess";
|
|
95
96
|
export {addMcpOAuthRoutes, type McpOAuthRoutesOptions} from "./mcp/oauth";
|
|
96
97
|
export {
|
|
97
98
|
buildAuthorizationServerMetadata,
|
|
98
99
|
buildProtectedResourceMetadata,
|
|
100
|
+
MCP_OAUTH_GRANT_PRESETS,
|
|
99
101
|
type McpOAuthAppOption,
|
|
102
|
+
type McpOAuthGrant,
|
|
103
|
+
type McpOAuthGrantAccess,
|
|
104
|
+
type McpOAuthGrantPreset,
|
|
100
105
|
type McpOAuthOptions,
|
|
101
106
|
type ResolvedMcpOAuthOptions,
|
|
102
107
|
resolveMcpOAuthOption,
|
|
@@ -134,6 +139,7 @@ export type {
|
|
|
134
139
|
MCPMethod,
|
|
135
140
|
MCPRegistryEntry,
|
|
136
141
|
MCPRequest,
|
|
142
|
+
MCPToolAccess,
|
|
137
143
|
MCPToolArgs,
|
|
138
144
|
MCPToolResult,
|
|
139
145
|
} from "./mcp/types";
|