@terreno/api 58.0.0-beta.1 → 58.0.0-beta.2
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 +46 -0
- package/dist/sync/entityIds.d.ts +14 -0
- package/dist/sync/entityIds.js +17 -0
- package/dist/sync/models.d.ts +1 -0
- package/dist/sync/models.js +4 -0
- package/dist/sync/mutationHandler.js +51 -2
- package/dist/sync/routes.js +12 -17
- package/dist/sync/types.d.ts +8 -0
- package/package.json +10 -3
- package/src/sync/entityIds.ts +18 -0
- package/src/sync/models.ts +6 -0
- package/src/sync/mutationHandler.test.ts +84 -0
- package/src/sync/mutationHandler.ts +57 -2
- package/src/sync/routes.ts +12 -17
- package/src/sync/syncRoutes.test.ts +8 -4
- package/src/sync/types.ts +9 -0
- package/biome.jsonc +0 -22
- package/bunfig.toml +0 -10
- package/bunfig.unit.toml +0 -3
- package/e2e/smoke.ts +0 -193
- package/tsconfig.json +0 -19
- package/tsconfig.typecheck.json +0 -14
- package/tsconfig.typedoc.json +0 -13
package/CHANGELOG.md
CHANGED
|
@@ -20,6 +20,52 @@ Upgrade notes for consumer action live in [`mcp-server/src/docs/upgrades/`](mcp-
|
|
|
20
20
|
|
|
21
21
|
Unreleased changes live in [`changelog/unreleased/`](changelog/unreleased/). Add one Markdown file per feature (see that directory's README) instead of editing this section.
|
|
22
22
|
|
|
23
|
+
## [58.0.0-beta.2] - 2026-11-03
|
|
24
|
+
|
|
25
|
+
Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.2.md`](mcp-server/src/docs/upgrades/58.0.0-beta.2.md).
|
|
26
|
+
|
|
27
|
+
### Breaking
|
|
28
|
+
|
|
29
|
+
- Terreno 58 targets Expo SDK 58 (`~58.0.14`), React Native `0.88.0`, and React `19.3.0`. `@terreno/ui` peers `react-native` `0.88.0`. Native catalog moves with the SDK: `react-native-gesture-handler` `~3.3.0`, `react-native-reanimated` `4.7.1` + `react-native-worklets` `0.13.0`, `react-native-screens` `~4.30.0`, `react-native-webview` `14.0.1`, `@sentry/react-native` `~8.28.0`, `@shopify/flash-list` `2.3.2`, `@shopify/react-native-skia` `2.14.0`. Rebuild dev clients and store binaries.
|
|
30
|
+
- Expo Router 58: set `export const unstable_settings = {initialRouteName}` on the layout instead of passing `initialRouteName` to `<Slot>` / navigators. `SidebarNavigation` ignores the prop.
|
|
31
|
+
- Expo Router 58 static rendering: a custom `app/+html.tsx` must render `headNodes` and `bodyNodes` from `useServerDocumentContext()` (`expo-router/html`), or exported pages ship without their JavaScript. `example-frontend` is updated.
|
|
32
|
+
- React Native 0.88 generated types: type refs as `ViewInstance`, `TextInstance`, `ScrollViewInstance`, and `TextInputInstance` (`Box.scrollRef`, `TextField.inputRef`, `Text` `ref`).
|
|
33
|
+
- `create-terreno-app` scaffolds Expo `~58.0.14`, React Native `0.88.0`, and React `19.3.0`.
|
|
34
|
+
- The Terreno 58 native module baseline lands in `example-frontend` and `demo`: `@stripe/stripe-react-native` 0.81.0, `react-native-purchases` and `react-native-purchases-ui` 10.12.2, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, and `expo-build-properties` (Android Kotlin 2.2.21 and `compileSdkVersion` 37 pins). Rebuild every dev client and store binary. `react-native-otp-verify` is left out because it does not support the New Architecture. The demo has a hidden **Native Modules** page that shows each module's version and whether the running binary links it. See the 58.0.0 upgrade note.
|
|
35
|
+
- `TerrenoApp` turns HTTP rate limiting on by default. Omitting `rateLimit` now mounts the limiter with the memory store (auth 20 / 15 min, api 600 / 15 min). Pass `rateLimit: false` to turn it off. On Cloud Run pass `rateLimit: {trustProxy: 1}` so unauthenticated traffic keys by client IP. See the 58.0.0 upgrade note.
|
|
36
|
+
- `@terreno/admin-frontend` no longer takes an RTK `api`. The `api` prop is removed from every admin component (`AdminProvider`, `AdminShellLayout`, `AdminHome`, `AdminModelList`, `AdminModelTable`, `AdminModelForm`, `AdminScreenRouter`, `ConfigurationScreen`, `DocumentStorageBrowser`, `ConsentHistory`, comms, jobs, org, consent, and announcement screens, and widget props), and admin hooks drop their `api` argument (`useAdminConfig(apiBase)`, `useAdminScripts(apiBase)`, `useAdminRoles(apiBase)`, `useConfigurationApi({basePath})`, `useDocumentStorageApi(basePath)`, `useConsentHistory(baseUrl)`, `useOrganizationsApi(basePath)`, `useCommsDashboardApi()`, `useJobsDashboardApi()`, and the `useAiObservability*Api()` hooks).
|
|
37
|
+
- `useAdminApi(api, routePath, modelName)` is removed. Use `useAdminModelApi(routePath, modelName)`, which keeps the same hook names and calls the same `/admin/{routePath}` URLs through the admin fetch client. `AdminApi`, `EndpointBuilder`, and admin `injectEndpoints` are gone; `@reduxjs/toolkit` and `react-redux` are no longer peers of admin-frontend.
|
|
38
|
+
- `AdminProvider` is now the required auth binding for every admin request, including ObjectId and API-only model CRUD. Cookie SPAs pass `credentials="same-origin"`; embedded apps pass `apiOrigin` and `getAuthHeaders`. Product screens that reuse admin components wrap them in `AdminProvider`. See the 58.0.0 upgrade guide.
|
|
39
|
+
- Removed the legacy RTK realtime path. Use `sync` on `modelRouter` with `@terreno/syncdb` for live collection updates. `RealtimeApp`, `SyncApp`, socket auth, `sync:delta`, and admin `admin:model.changed` events are unchanged. See the 58.0.0 upgrade note.
|
|
40
|
+
- `@terreno/api`: `modelRouter` no longer accepts `realtime` (now a TypeScript error), and the change stream no longer emits the `sync` websocket event. Removed `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, `registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`, the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. Sockets no longer handle `subscribe:model`, `subscribe:document`, or `subscribe:query`.
|
|
41
|
+
- `@terreno/rtk`: removed `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `useSyncConnection`, and the `RealtimeEvent` type. The rest of `@terreno/rtk` (including `useSocketConnection` and `useRealtimeDebug`) is removed in the same release; see `remove-rtk.md`.
|
|
42
|
+
- Removed `@terreno/rtk` and every Redux dependency (`@reduxjs/toolkit`, `react-redux`, `redux-persist`, `@rtk-query/codegen-openapi`). `@terreno/rtk` is not published for 58. `@terreno/syncdb` is the only frontend data, request, and session layer. Follow `docs/how-to/migrate-rtk-to-syncdb.md`, which maps every removed export to its replacement, and the 58.0.0 upgrade note.
|
|
43
|
+
- `@terreno/syncdb` adds `@terreno/syncdb/api` (`createApiClient`, `ApiError`), request hooks in `@terreno/syncdb/react` (`ApiClientProvider`, `useApiQuery`, `useLazyApiQuery`, `useApiMutation`, `useSocketEvent`), `@terreno/syncdb/config` (`baseUrl`, `baseWebsocketsUrl`, `appHeaders`), `@terreno/syncdb/auth` (`createBetterAuthClient`, `SessionProvider`, `useSession`, `jwtAuthAdapter`, `useJwtAuth`, token-expiry helpers), `@terreno/syncdb/flags` (`useFeatureFlags`, `useTerrenoFeatureFlags` on the sync socket), `@terreno/syncdb/app` (`useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools`), and `@terreno/syncdb/buildNumber`.
|
|
44
|
+
- `terreno-syncdb-codegen --api-out` generates typed hooks for every non-synced OpenAPI operation (same names as the RTK codegen), replacing `@rtk-query/codegen-openapi`. `bun run sdk` writes `store/apiSdk.ts`.
|
|
45
|
+
- `@terreno/ui` `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, and `useAcknowledgeAnnouncement` take a request `client` instead of an RTK `api`.
|
|
46
|
+
- `GptHistory` (`gpt/histories`) is a synced collection and keeps its ObjectId `_id` (no migration). `McpServiceToken` (`mcp/service-tokens`, read-only) is a synced collection with String ids; run `mcpServiceTokenStringIdsMigration` (`@terreno/api`) before deploying 58 frontends.
|
|
47
|
+
- `create-terreno-app`, the `terreno_bootstrap` prompt, and the `terreno_generate_screen` tool scaffold apps without Redux or `@terreno/rtk`. The terreno-mcp-local `get_rtk_state` tool, the MCP resource `terreno://docs/rtk`, and `terreno state --slice rtk` are removed; use `get_syncdb_state` and `terreno state`.
|
|
48
|
+
|
|
49
|
+
### Added
|
|
50
|
+
|
|
51
|
+
- `DataTable` columns size themselves when `width` is omitted. Each auto column starts at the wider of its header and its content (sampled from at most 50 rows, measured with a canvas on web and estimated on native), clamped to 80–360px, and auto columns grow to fill the table's container. Columns that set `width` keep it. `DataTableColumn.width` is now optional.
|
|
52
|
+
- `@terreno/syncdb` `createSyncDb({idFormats})` mints 24-hex ObjectIds for a collection set to `"objectId"`, so a model that keeps Mongoose's default ObjectId `_id` can sync without migrating its ids. `mutate()` throws on an explicit non-hex id for such a collection. `generateObjectId` and the `SyncIdFormat` type are exported.
|
|
53
|
+
- Sync `validation` nacks carry an optional `reason`: `invalid_id` when an ObjectId-keyed collection gets a non-hex id (rejected before the mutation is claimed), and `id_collision` when a create names an `_id` another document holds. A collision never touches the existing document and its message never names the holder. The ledger records the reason (`SyncMutation.nackReason`) so a redelivery replays it.
|
|
54
|
+
- `GET /sync/entities` leaves out non-hex ids for an ObjectId-keyed model instead of answering 400, so a rejected create queued for repair cannot fail the rest of the repair batch.
|
|
55
|
+
|
|
56
|
+
### Changed
|
|
57
|
+
|
|
58
|
+
- The repository's agent rules now generate with rulesync 17 (up from 9). The root rule `.rulesync/rules/00-root.md` now generates `AGENTS.md`, which Devin and other AGENTS.md readers load, in place of `.devin/rules/00-root.md`. Never edit `AGENTS.md` by hand: edit the root rule and run `bun run rules`. The examples that existed only in the old hand-edited `AGENTS.md` (syncdb and RTK SDK usage) moved into the root rule, so `CLAUDE.md`, the Cursor root rule, and Copilot instructions get them too. Links in the root rule now resolve from the repository root. Generated Copilot hooks use the portable `command` field. Generated Copilot subagents no longer list `agent/runSubagent` as their only tool, so they get every default tool. Generated skills carry their `license`, `disable-model-invocation`, and Devin `triggers` frontmatter.
|
|
59
|
+
- `@terreno/syncdb/auth` `SessionProvider`: `logout()` no longer clears the session before the server answers. The session stays in the state until `authClient.signOut()` finishes (`signOutTimeoutMs`, default 10 seconds), and then it is cleared. Meanwhile the new `isSigningOut` state (`useSession().isSigningOut`) is true; `isLoading` is left alone, so a navigator gated on it keeps its screen. Before, a login screen that opened at once could find the still-live session and sign the user straight back in. A sign-out that fails or times out checks the session first. A session that is still live, or a cookie or native session the server cannot be asked about, stays signed in, and `error` is set to `SIGN_OUT_FAILED_MESSAGE` ("Couldn't sign out. Check your connection and try again."). A web bearer client, which drops its token before the request leaves, ends signed out. The global `auth/logout` action (a refused session) now ends signed out even when the sign-out request fails. With `apisToReset` (57.17.0), `logout()` purges the cache when the session clears, not when it is dispatched: a purge at dispatch refetched every mounted screen mid-sign-out, and a refetch that could not reach the server answered 401 and signed the user out even though the sign-out failed. A failed sign-out keeps both the session and the cache. The global `auth/logout` action still purges at once (only the first of several in flight) and again when the session clears. A sign-in for another user that lands while a sign-out is in flight is kept; a sign-out that started signed out asks `getSession` first, so a restore of the session it revoked is cleared. Show `selectBetterAuthIsSigningOut` on the sign-out control and `selectBetterAuthError` after a failed sign-out.
|
|
60
|
+
|
|
61
|
+
### Removed
|
|
62
|
+
|
|
63
|
+
- `@terreno/ui` no longer exports the `Filter` and `FilterProps` aliases deprecated in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps` instead. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names.
|
|
64
|
+
|
|
65
|
+
### Fixed
|
|
66
|
+
|
|
67
|
+
- `@terreno/syncdb`: logging out while `syncDb.start()` is still running no longer loses local writes or logs errors. `start()` now resolves the web encryption key from `GET /sync/key` before it loads the store, so the flush in `stop()` never needs the network after the session has ended. A `stop()` or `signOut()` call now cancels a `start()` that is running or queued ahead of it, so the transport never connects without a session. A failed key fetch is now retried on the next save instead of failing every save for the rest of the session.
|
|
68
|
+
|
|
23
69
|
## [58.0.0-beta.1] - 2026-11-02
|
|
24
70
|
|
|
25
71
|
Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.1.md`](mcp-server/src/docs/upgrades/58.0.0-beta.1.md).
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type mongoose from "mongoose";
|
|
2
|
+
/**
|
|
3
|
+
* True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
|
|
4
|
+
* accepts any 12-character string as raw ObjectId bytes.
|
|
5
|
+
*/
|
|
6
|
+
export declare const isObjectIdHex: (id: unknown) => id is string;
|
|
7
|
+
/**
|
|
8
|
+
* True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
|
|
9
|
+
* ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
|
|
10
|
+
* any id shape (syncdb's UUID default).
|
|
11
|
+
*/
|
|
12
|
+
export declare const isObjectIdKeyed: (model: {
|
|
13
|
+
schema?: mongoose.Schema;
|
|
14
|
+
}) => boolean;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.isObjectIdKeyed = exports.isObjectIdHex = void 0;
|
|
4
|
+
const OBJECT_ID_HEX = /^[0-9a-fA-F]{24}$/;
|
|
5
|
+
/**
|
|
6
|
+
* True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
|
|
7
|
+
* accepts any 12-character string as raw ObjectId bytes.
|
|
8
|
+
*/
|
|
9
|
+
const isObjectIdHex = (id) => typeof id === "string" && OBJECT_ID_HEX.test(id);
|
|
10
|
+
exports.isObjectIdHex = isObjectIdHex;
|
|
11
|
+
/**
|
|
12
|
+
* True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
|
|
13
|
+
* ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
|
|
14
|
+
* any id shape (syncdb's UUID default).
|
|
15
|
+
*/
|
|
16
|
+
const isObjectIdKeyed = (model) => model.schema?.path("_id")?.instance === "ObjectId";
|
|
17
|
+
exports.isObjectIdKeyed = isObjectIdKeyed;
|
package/dist/sync/models.d.ts
CHANGED
package/dist/sync/models.js
CHANGED
|
@@ -362,6 +362,10 @@ const syncMutationSchema = new mongoose_1.Schema({
|
|
|
362
362
|
description: "Nack code recorded for rejected mutations (conflict/unauthorized/validation/error)",
|
|
363
363
|
type: String,
|
|
364
364
|
},
|
|
365
|
+
nackReason: {
|
|
366
|
+
description: "Why a validation nack rejected the mutation's entity id (id_collision/invalid_id)",
|
|
367
|
+
type: String,
|
|
368
|
+
},
|
|
365
369
|
resultId: {
|
|
366
370
|
description: "The affected document id, recorded when the mutation is applied or conflicts; a " +
|
|
367
371
|
"duplicate delivery of a conflict re-serializes the live document from this id",
|
|
@@ -13,6 +13,7 @@ const permissions_1 = require("../permissions");
|
|
|
13
13
|
const plugins_1 = require("../plugins");
|
|
14
14
|
const adminBroadcastScope_1 = require("./adminBroadcastScope");
|
|
15
15
|
const adminWindowMutation_1 = require("./adminWindowMutation");
|
|
16
|
+
const entityIds_1 = require("./entityIds");
|
|
16
17
|
const executors_1 = require("./executors");
|
|
17
18
|
const models_1 = require("./models");
|
|
18
19
|
const registry_1 = require("./registry");
|
|
@@ -191,6 +192,7 @@ const outcomeFromLedgerRow = async ({ entry, mutation, request, row, scopeResolv
|
|
|
191
192
|
code: row.nackCode ?? "error",
|
|
192
193
|
message: row.error,
|
|
193
194
|
mutationId: row.mutationId,
|
|
195
|
+
...(row.nackReason ? { reason: row.nackReason } : {}),
|
|
194
196
|
});
|
|
195
197
|
}
|
|
196
198
|
return undefined;
|
|
@@ -281,6 +283,21 @@ const isE11000Error = (error) => {
|
|
|
281
283
|
const wrapped = candidate?.error;
|
|
282
284
|
return wrapped?.code === 11000;
|
|
283
285
|
};
|
|
286
|
+
/** The `APIError.code` a create gets when its client-minted `_id` already exists. */
|
|
287
|
+
const ID_COLLISION_CODE = "sync-id-collision";
|
|
288
|
+
/**
|
|
289
|
+
* True when an E11000 (raw, or wrapped by the executor) is on the `_id` index rather than
|
|
290
|
+
* some other unique index the model declares.
|
|
291
|
+
*/
|
|
292
|
+
const isIdDuplicateKeyError = (error) => {
|
|
293
|
+
if (!isE11000Error(error)) {
|
|
294
|
+
return false;
|
|
295
|
+
}
|
|
296
|
+
const candidate = error;
|
|
297
|
+
const raw = [candidate, candidate.error, candidate.cause].find((value) => value?.code === 11000);
|
|
298
|
+
const keys = Object.keys(raw?.keyPattern ?? raw?.keyValue ?? {});
|
|
299
|
+
return keys.length === 1 && keys[0] === "_id";
|
|
300
|
+
};
|
|
284
301
|
/**
|
|
285
302
|
* C5 (FIX 6): true when every key/value in `data` (the mutation's own
|
|
286
303
|
* intended write) is already present on `doc` — used alongside the
|
|
@@ -364,6 +381,7 @@ const finalizeNack = async ({ claimedId, entry, error, mutation, request, }) =>
|
|
|
364
381
|
}
|
|
365
382
|
const code = nackCodeForError(error);
|
|
366
383
|
const message = (0, errors_1.isAPIError)(error) ? error.title : String(error);
|
|
384
|
+
const reason = (0, errors_1.isAPIError)(error) && error.code === ID_COLLISION_CODE ? "id_collision" : undefined;
|
|
367
385
|
if (code === "error") {
|
|
368
386
|
logger_1.logger.warn("[sync] Mutation failed unexpectedly", {
|
|
369
387
|
collection: mutation.collection,
|
|
@@ -380,8 +398,15 @@ const finalizeNack = async ({ claimedId, entry, error, mutation, request, }) =>
|
|
|
380
398
|
await models_1.SyncMutation.deleteOne({ _id: claimedId });
|
|
381
399
|
return makeNack({ code, message, mutationId: mutation.mutationId });
|
|
382
400
|
}
|
|
383
|
-
await models_1.SyncMutation.updateOne({ _id: claimedId }, {
|
|
384
|
-
|
|
401
|
+
await models_1.SyncMutation.updateOne({ _id: claimedId }, {
|
|
402
|
+
$set: {
|
|
403
|
+
error: message,
|
|
404
|
+
nackCode: code,
|
|
405
|
+
status: "failed",
|
|
406
|
+
...(reason ? { nackReason: reason } : {}),
|
|
407
|
+
},
|
|
408
|
+
});
|
|
409
|
+
return makeNack({ code, message, mutationId: mutation.mutationId, ...(reason ? { reason } : {}) });
|
|
385
410
|
};
|
|
386
411
|
/**
|
|
387
412
|
* C5 (FIX 6): read the doc back and report it as the ack for an ALREADY-APPLIED write —
|
|
@@ -541,6 +566,18 @@ const applyClaimedMutationInContext = async ({ claimed, entry, mutation, request
|
|
|
541
566
|
return { ack: { id: resultId, mutationId, seq: resultSeq }, type: "ack" };
|
|
542
567
|
}
|
|
543
568
|
}
|
|
569
|
+
// Another document already holds the client-minted `_id`. The unique index kept it
|
|
570
|
+
// from being overwritten; reject the create for good (validation is terminal on the
|
|
571
|
+
// client) without naming the holder, which may belong to another user.
|
|
572
|
+
if (isIdDuplicateKeyError(createError)) {
|
|
573
|
+
throw new errors_1.APIError({
|
|
574
|
+
cause: createError,
|
|
575
|
+
code: ID_COLLISION_CODE,
|
|
576
|
+
disableExternalErrorTracking: true,
|
|
577
|
+
status: 400,
|
|
578
|
+
title: "Entity id already exists",
|
|
579
|
+
});
|
|
580
|
+
}
|
|
544
581
|
throw createError;
|
|
545
582
|
}
|
|
546
583
|
}
|
|
@@ -688,6 +725,18 @@ const applySyncMutation = async ({ user, mutation, req, scopeResolver, syncOptio
|
|
|
688
725
|
if (!entry) {
|
|
689
726
|
return validationNack(`Unknown sync collection: ${mutation.collection}`);
|
|
690
727
|
}
|
|
728
|
+
// An ObjectId-keyed collection can only hold 24-hex ids. Rejecting anything else here
|
|
729
|
+
// keeps a client-minted UUID from reaching Mongoose as a CastError, which would nack as a
|
|
730
|
+
// retryable `error` and replay forever.
|
|
731
|
+
const model = mongoose_1.default.models[entry.modelName];
|
|
732
|
+
if (mutation.id && model && (0, entityIds_1.isObjectIdKeyed)(model) && !(0, entityIds_1.isObjectIdHex)(mutation.id)) {
|
|
733
|
+
return makeNack({
|
|
734
|
+
code: "validation",
|
|
735
|
+
message: `${mutation.collection} ids must be 24-character hex ObjectIds`,
|
|
736
|
+
mutationId,
|
|
737
|
+
reason: "invalid_id",
|
|
738
|
+
});
|
|
739
|
+
}
|
|
691
740
|
const request = req ?? { user };
|
|
692
741
|
// Atomic claim: inserting the pending row first means exactly one delivery applies.
|
|
693
742
|
let claimed;
|
package/dist/sync/routes.js
CHANGED
|
@@ -14,6 +14,7 @@ const permissions_1 = require("../permissions");
|
|
|
14
14
|
const plugins_1 = require("../plugins");
|
|
15
15
|
const adminBroadcastScope_1 = require("./adminBroadcastScope");
|
|
16
16
|
const adminWindowAccess_1 = require("./adminWindowAccess");
|
|
17
|
+
const entityIds_1 = require("./entityIds");
|
|
17
18
|
const models_1 = require("./models");
|
|
18
19
|
const registry_1 = require("./registry");
|
|
19
20
|
const serialize_1 = require("./serialize");
|
|
@@ -162,18 +163,17 @@ const parseNonNegativeInt = (raw, name, fallback) => {
|
|
|
162
163
|
};
|
|
163
164
|
/**
|
|
164
165
|
* Task 9.14: the legacy cursor is a raw `_id` string, so it must be compared in the
|
|
165
|
-
* model's OWN `_id` BSON type. Synced models
|
|
166
|
+
* model's OWN `_id` BSON type. Synced models default to client-minted string
|
|
166
167
|
* `_id`s: casting those to `ObjectId` either throws (non-hex ids) or — worse — silently
|
|
167
168
|
* compares across BSON types and matches nothing, so the legacy stratum reported itself
|
|
168
169
|
* exhausted after one page and the remaining documents were never bootstrapped.
|
|
169
170
|
* Only ObjectId-keyed models get the cast; a malformed cursor for one is a 400, not a 500.
|
|
170
171
|
*/
|
|
171
172
|
const legacyCursorClause = ({ model, legacyCursorIn, }) => {
|
|
172
|
-
|
|
173
|
-
if (idInstance !== "ObjectId") {
|
|
173
|
+
if (!(0, entityIds_1.isObjectIdKeyed)(model)) {
|
|
174
174
|
return { _id: { $gt: legacyCursorIn } };
|
|
175
175
|
}
|
|
176
|
-
if (!
|
|
176
|
+
if (!(0, entityIds_1.isObjectIdHex)(legacyCursorIn)) {
|
|
177
177
|
throw new errors_1.APIError({ status: 400, title: `Invalid legacyCursor: ${legacyCursorIn}` });
|
|
178
178
|
}
|
|
179
179
|
return { _id: { $gt: new mongoose_1.default.Types.ObjectId(legacyCursorIn) } };
|
|
@@ -322,23 +322,18 @@ const pageSeqStratum = async ({ model, scopeFilter, cursor, limit, frontierSeq,
|
|
|
322
322
|
exports.MAX_ENTITY_FETCH = 100;
|
|
323
323
|
/**
|
|
324
324
|
* Task 9.27: `_id: {$in: ids}` leaves the cast to Mongoose, so one non-hex id against an
|
|
325
|
-
* ObjectId-keyed model threw a CastError that surfaced as a 500
|
|
326
|
-
*
|
|
327
|
-
*
|
|
325
|
+
* ObjectId-keyed model threw a CastError that surfaced as a 500. A non-hex id cannot name a
|
|
326
|
+
* document of such a model, so it is dropped and comes back absent, which is the true answer.
|
|
327
|
+
* Failing the whole request instead would wedge a client's repair batch: a create the server
|
|
328
|
+
* rejected for a bad id is queued for repair under that id, and every other id in the batch
|
|
329
|
+
* would never load. Models with client-minted string `_id`s (see `legacyCursorClause`) take
|
|
330
|
+
* any shape.
|
|
328
331
|
*/
|
|
329
332
|
const castEntityIds = ({ model, ids, }) => {
|
|
330
|
-
|
|
331
|
-
if (idInstance !== "ObjectId") {
|
|
333
|
+
if (!(0, entityIds_1.isObjectIdKeyed)(model)) {
|
|
332
334
|
return ids;
|
|
333
335
|
}
|
|
334
|
-
|
|
335
|
-
if (invalid.length > 0) {
|
|
336
|
-
throw new errors_1.APIError({
|
|
337
|
-
status: 400,
|
|
338
|
-
title: `Invalid ids for ${model.modelName}: ${invalid.join(",")}`,
|
|
339
|
-
});
|
|
340
|
-
}
|
|
341
|
-
return ids.map((id) => new mongoose_1.default.Types.ObjectId(id));
|
|
336
|
+
return ids.filter(entityIds_1.isObjectIdHex).map((id) => new mongoose_1.default.Types.ObjectId(id));
|
|
342
337
|
};
|
|
343
338
|
/**
|
|
344
339
|
* Serve one snapshot page for one stream: membership/permission checks, frontier and
|
package/dist/sync/types.d.ts
CHANGED
|
@@ -178,6 +178,12 @@ export interface SyncAck {
|
|
|
178
178
|
warning?: string;
|
|
179
179
|
}
|
|
180
180
|
export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
|
|
181
|
+
/**
|
|
182
|
+
* Why a `validation` nack rejected a mutation, when the cause is the entity id itself.
|
|
183
|
+
* `id_collision`: a create named an `_id` that already exists. `invalid_id`: the id is not a
|
|
184
|
+
* 24-character hex ObjectId for an ObjectId-keyed collection.
|
|
185
|
+
*/
|
|
186
|
+
export type SyncNackReason = "id_collision" | "invalid_id";
|
|
181
187
|
/** Rejected mutation. Conflict nacks carry the canonical server document. */
|
|
182
188
|
export interface SyncNack {
|
|
183
189
|
mutationId: string;
|
|
@@ -187,6 +193,8 @@ export interface SyncNack {
|
|
|
187
193
|
/** The server document's current `_syncSeq` (conflict nacks). */
|
|
188
194
|
serverSeq?: number;
|
|
189
195
|
message?: string;
|
|
196
|
+
/** Set on `validation` nacks caused by the entity id (see {@link SyncNackReason}). */
|
|
197
|
+
reason?: SyncNackReason;
|
|
190
198
|
/**
|
|
191
199
|
* Minimum time (ms) the client should wait before retrying, filled by the
|
|
192
200
|
* server with the remaining rate-limit window (`rate_limited` nacks only).
|
package/package.json
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
"@modelcontextprotocol/node": "^2.0.0",
|
|
14
14
|
"@modelcontextprotocol/server": "^2.0.0",
|
|
15
15
|
"@sentry/bun": "^11.0.0",
|
|
16
|
-
"@terreno/test": "58.0.0-beta.
|
|
16
|
+
"@terreno/test": "58.0.0-beta.2",
|
|
17
17
|
"@thream/socketio-jwt": "^3.1.4",
|
|
18
18
|
"@types/qs": "^6.14.0",
|
|
19
19
|
"ajv": "8.20.0",
|
|
@@ -51,7 +51,7 @@
|
|
|
51
51
|
"devDependencies": {
|
|
52
52
|
"@biomejs/biome": "^2.3.6",
|
|
53
53
|
"@modelcontextprotocol/client": "^2.0.0",
|
|
54
|
-
"@terreno/syncdb": "58.0.0-beta.
|
|
54
|
+
"@terreno/syncdb": "58.0.0-beta.2",
|
|
55
55
|
"@types/bun": "^1.4.0",
|
|
56
56
|
"@types/cors": "^2.8.17",
|
|
57
57
|
"@types/express": "^5.0.6",
|
|
@@ -86,6 +86,13 @@
|
|
|
86
86
|
"types": "./dist/tests/openApiResponseSchema.d.ts"
|
|
87
87
|
}
|
|
88
88
|
},
|
|
89
|
+
"files": [
|
|
90
|
+
"LICENSE",
|
|
91
|
+
"CHANGELOG.md",
|
|
92
|
+
"dist/**/*",
|
|
93
|
+
"src/**/*",
|
|
94
|
+
".ai/**/*"
|
|
95
|
+
],
|
|
89
96
|
"homepage": "https://github.com/TerrenoLabs/terreno#readme",
|
|
90
97
|
"keywords": [
|
|
91
98
|
"rest",
|
|
@@ -141,5 +148,5 @@
|
|
|
141
148
|
"updateSnapshot": "bun test --update-snapshots"
|
|
142
149
|
},
|
|
143
150
|
"types": "dist/index.d.ts",
|
|
144
|
-
"version": "58.0.0-beta.
|
|
151
|
+
"version": "58.0.0-beta.2"
|
|
145
152
|
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type mongoose from "mongoose";
|
|
2
|
+
|
|
3
|
+
const OBJECT_ID_HEX = /^[0-9a-fA-F]{24}$/;
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
|
|
7
|
+
* accepts any 12-character string as raw ObjectId bytes.
|
|
8
|
+
*/
|
|
9
|
+
export const isObjectIdHex = (id: unknown): id is string =>
|
|
10
|
+
typeof id === "string" && OBJECT_ID_HEX.test(id);
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
|
|
14
|
+
* ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
|
|
15
|
+
* any id shape (syncdb's UUID default).
|
|
16
|
+
*/
|
|
17
|
+
export const isObjectIdKeyed = (model: {schema?: mongoose.Schema}): boolean =>
|
|
18
|
+
(model.schema?.path("_id") as {instance?: string} | undefined)?.instance === "ObjectId";
|
package/src/sync/models.ts
CHANGED
|
@@ -440,6 +440,7 @@ export interface SyncMutationDocument {
|
|
|
440
440
|
collectionTag?: string;
|
|
441
441
|
status: SyncMutationStatus;
|
|
442
442
|
nackCode?: string;
|
|
443
|
+
nackReason?: string;
|
|
443
444
|
resultId?: string;
|
|
444
445
|
resultSeq?: number;
|
|
445
446
|
error?: string;
|
|
@@ -493,6 +494,11 @@ const syncMutationSchema = new Schema<SyncMutationDocument>(
|
|
|
493
494
|
"Nack code recorded for rejected mutations (conflict/unauthorized/validation/error)",
|
|
494
495
|
type: String,
|
|
495
496
|
},
|
|
497
|
+
nackReason: {
|
|
498
|
+
description:
|
|
499
|
+
"Why a validation nack rejected the mutation's entity id (id_collision/invalid_id)",
|
|
500
|
+
type: String,
|
|
501
|
+
},
|
|
496
502
|
resultId: {
|
|
497
503
|
description:
|
|
498
504
|
"The affected document id, recorded when the mutation is applied or conflicts; a " +
|
|
@@ -908,6 +908,90 @@ describe("applySyncMutation", () => {
|
|
|
908
908
|
expect(nack.message).toContain("Unknown sync collection");
|
|
909
909
|
});
|
|
910
910
|
|
|
911
|
+
it("nacks invalid_id for a non-hex id on an ObjectId-keyed collection, for every operation", async () => {
|
|
912
|
+
const doc = await MutStuffModel.create({name: "keyed", ownerId: owner.id});
|
|
913
|
+
const badIds = [crypto.randomUUID(), "abcdefghijkl", `${String(doc._id)}0`];
|
|
914
|
+
for (const [index, id] of badIds.entries()) {
|
|
915
|
+
for (const operation of ["create", "update", "delete"] as const) {
|
|
916
|
+
const mutationId = `m-bad-id-${operation}-${index}`;
|
|
917
|
+
const nack = expectNack(
|
|
918
|
+
await applySyncMutation({
|
|
919
|
+
mutation: {
|
|
920
|
+
baseVersion: 1,
|
|
921
|
+
collection: "mutStuff",
|
|
922
|
+
data: {name: "bad id", ownerId: owner.id},
|
|
923
|
+
id,
|
|
924
|
+
mutationId,
|
|
925
|
+
operation,
|
|
926
|
+
},
|
|
927
|
+
user: owner,
|
|
928
|
+
})
|
|
929
|
+
);
|
|
930
|
+
assert.equal(nack.code, "validation");
|
|
931
|
+
assert.equal(nack.reason, "invalid_id");
|
|
932
|
+
// Rejected before the claim: nothing to replay, nothing written.
|
|
933
|
+
assert.equal(await SyncMutation.countDocuments({mutationId}), 0);
|
|
934
|
+
}
|
|
935
|
+
}
|
|
936
|
+
assert.equal(await MutStuffModel.countDocuments({}), 1);
|
|
937
|
+
});
|
|
938
|
+
|
|
939
|
+
it("accepts any id shape on a String-keyed collection", async () => {
|
|
940
|
+
clearSyncRegistry();
|
|
941
|
+
registerSync({
|
|
942
|
+
config: {scope: {type: "owner"}},
|
|
943
|
+
model: MutOtherModel,
|
|
944
|
+
options: ownerOptions,
|
|
945
|
+
routePath: "/mutOther",
|
|
946
|
+
});
|
|
947
|
+
const id = crypto.randomUUID();
|
|
948
|
+
const ack = expectAck(
|
|
949
|
+
await applySyncMutation({
|
|
950
|
+
mutation: {
|
|
951
|
+
collection: "mutOther",
|
|
952
|
+
data: {name: "uuid", ownerId: owner.id},
|
|
953
|
+
id,
|
|
954
|
+
mutationId: "m-uuid-ok",
|
|
955
|
+
operation: "create",
|
|
956
|
+
},
|
|
957
|
+
user: owner,
|
|
958
|
+
})
|
|
959
|
+
);
|
|
960
|
+
assert.equal(ack.id, id);
|
|
961
|
+
await MutOtherModel.collection.deleteMany({});
|
|
962
|
+
});
|
|
963
|
+
|
|
964
|
+
it("nacks id_collision when a create names an _id another document holds", async () => {
|
|
965
|
+
const taken = await MutStuffModel.create({name: "theirs", ownerId: stranger.id});
|
|
966
|
+
const create = (): Promise<SyncMutationOutcome> =>
|
|
967
|
+
applySyncMutation({
|
|
968
|
+
mutation: {
|
|
969
|
+
collection: "mutStuff",
|
|
970
|
+
data: {name: "mine", ownerId: owner.id},
|
|
971
|
+
id: String(taken._id),
|
|
972
|
+
mutationId: "m-collision",
|
|
973
|
+
operation: "create",
|
|
974
|
+
},
|
|
975
|
+
user: owner,
|
|
976
|
+
});
|
|
977
|
+
|
|
978
|
+
const nack = expectNack(await create());
|
|
979
|
+
assert.equal(nack.code, "validation");
|
|
980
|
+
assert.equal(nack.reason, "id_collision");
|
|
981
|
+
assert.equal(nack.message, "Entity id already exists");
|
|
982
|
+
assert.notInclude(JSON.stringify(nack), stranger.id);
|
|
983
|
+
const stored = await MutStuffModel.findById(taken._id);
|
|
984
|
+
assert.equal(stored?.name, "theirs");
|
|
985
|
+
assert.equal(stored?.ownerId, stranger.id);
|
|
986
|
+
|
|
987
|
+
// A duplicate delivery replays the recorded nack, reason included.
|
|
988
|
+
const replayed = expectNack(await create());
|
|
989
|
+
assert.equal(replayed.reason, "id_collision");
|
|
990
|
+
const row = await SyncMutation.findOne({mutationId: "m-collision"});
|
|
991
|
+
assert.equal(row?.status, "failed");
|
|
992
|
+
assert.equal(row?.nackReason, "id_collision");
|
|
993
|
+
});
|
|
994
|
+
|
|
911
995
|
it("nacks validation when an update omits baseVersion", async () => {
|
|
912
996
|
const doc = await MutStuffModel.create({name: "no base", ownerId: owner.id});
|
|
913
997
|
const nack = expectNack(
|
|
@@ -15,6 +15,7 @@ import {
|
|
|
15
15
|
prepareAdminWindowMutation,
|
|
16
16
|
withAdminWindowMutationRequestContext,
|
|
17
17
|
} from "./adminWindowMutation";
|
|
18
|
+
import {isObjectIdHex, isObjectIdKeyed} from "./entityIds";
|
|
18
19
|
import {
|
|
19
20
|
executeCreate,
|
|
20
21
|
executeDelete,
|
|
@@ -35,6 +36,7 @@ import type {
|
|
|
35
36
|
SyncMutateRequest,
|
|
36
37
|
SyncNack,
|
|
37
38
|
SyncNackCode,
|
|
39
|
+
SyncNackReason,
|
|
38
40
|
} from "./types";
|
|
39
41
|
|
|
40
42
|
export type SyncMutationScopeResolver = (
|
|
@@ -314,6 +316,7 @@ const outcomeFromLedgerRow = async ({
|
|
|
314
316
|
code: (row.nackCode as SyncNackCode) ?? "error",
|
|
315
317
|
message: row.error,
|
|
316
318
|
mutationId: row.mutationId,
|
|
319
|
+
...(row.nackReason ? {reason: row.nackReason as SyncNackReason} : {}),
|
|
317
320
|
});
|
|
318
321
|
}
|
|
319
322
|
return undefined;
|
|
@@ -431,6 +434,25 @@ const isE11000Error = (error: unknown): boolean => {
|
|
|
431
434
|
return wrapped?.code === 11000;
|
|
432
435
|
};
|
|
433
436
|
|
|
437
|
+
/** The `APIError.code` a create gets when its client-minted `_id` already exists. */
|
|
438
|
+
const ID_COLLISION_CODE = "sync-id-collision";
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* True when an E11000 (raw, or wrapped by the executor) is on the `_id` index rather than
|
|
442
|
+
* some other unique index the model declares.
|
|
443
|
+
*/
|
|
444
|
+
const isIdDuplicateKeyError = (error: unknown): boolean => {
|
|
445
|
+
if (!isE11000Error(error)) {
|
|
446
|
+
return false;
|
|
447
|
+
}
|
|
448
|
+
const candidate = error as {cause?: unknown; error?: unknown; keyPattern?: unknown};
|
|
449
|
+
const raw = [candidate, candidate.error, candidate.cause].find(
|
|
450
|
+
(value) => (value as {code?: number} | undefined)?.code === 11000
|
|
451
|
+
) as {keyPattern?: Record<string, unknown>; keyValue?: Record<string, unknown>} | undefined;
|
|
452
|
+
const keys = Object.keys(raw?.keyPattern ?? raw?.keyValue ?? {});
|
|
453
|
+
return keys.length === 1 && keys[0] === "_id";
|
|
454
|
+
};
|
|
455
|
+
|
|
434
456
|
/**
|
|
435
457
|
* C5 (FIX 6): true when every key/value in `data` (the mutation's own
|
|
436
458
|
* intended write) is already present on `doc` — used alongside the
|
|
@@ -535,6 +557,8 @@ const finalizeNack = async ({
|
|
|
535
557
|
|
|
536
558
|
const code = nackCodeForError(error);
|
|
537
559
|
const message = isAPIError(error) ? error.title : String(error);
|
|
560
|
+
const reason: SyncNackReason | undefined =
|
|
561
|
+
isAPIError(error) && error.code === ID_COLLISION_CODE ? "id_collision" : undefined;
|
|
538
562
|
if (code === "error") {
|
|
539
563
|
logger.warn("[sync] Mutation failed unexpectedly", {
|
|
540
564
|
collection: mutation.collection,
|
|
@@ -553,9 +577,16 @@ const finalizeNack = async ({
|
|
|
553
577
|
}
|
|
554
578
|
await SyncMutation.updateOne(
|
|
555
579
|
{_id: claimedId},
|
|
556
|
-
{
|
|
580
|
+
{
|
|
581
|
+
$set: {
|
|
582
|
+
error: message,
|
|
583
|
+
nackCode: code,
|
|
584
|
+
status: "failed",
|
|
585
|
+
...(reason ? {nackReason: reason} : {}),
|
|
586
|
+
},
|
|
587
|
+
}
|
|
557
588
|
);
|
|
558
|
-
return makeNack({code, message, mutationId: mutation.mutationId});
|
|
589
|
+
return makeNack({code, message, mutationId: mutation.mutationId, ...(reason ? {reason} : {})});
|
|
559
590
|
};
|
|
560
591
|
|
|
561
592
|
/**
|
|
@@ -777,6 +808,18 @@ const applyClaimedMutationInContext = async ({
|
|
|
777
808
|
return {ack: {id: resultId, mutationId, seq: resultSeq}, type: "ack"};
|
|
778
809
|
}
|
|
779
810
|
}
|
|
811
|
+
// Another document already holds the client-minted `_id`. The unique index kept it
|
|
812
|
+
// from being overwritten; reject the create for good (validation is terminal on the
|
|
813
|
+
// client) without naming the holder, which may belong to another user.
|
|
814
|
+
if (isIdDuplicateKeyError(createError)) {
|
|
815
|
+
throw new APIError({
|
|
816
|
+
cause: createError,
|
|
817
|
+
code: ID_COLLISION_CODE,
|
|
818
|
+
disableExternalErrorTracking: true,
|
|
819
|
+
status: 400,
|
|
820
|
+
title: "Entity id already exists",
|
|
821
|
+
});
|
|
822
|
+
}
|
|
780
823
|
throw createError;
|
|
781
824
|
}
|
|
782
825
|
} else if (effectiveMutation.operation === "update") {
|
|
@@ -946,6 +989,18 @@ export const applySyncMutation = async ({
|
|
|
946
989
|
if (!entry) {
|
|
947
990
|
return validationNack(`Unknown sync collection: ${mutation.collection}`);
|
|
948
991
|
}
|
|
992
|
+
// An ObjectId-keyed collection can only hold 24-hex ids. Rejecting anything else here
|
|
993
|
+
// keeps a client-minted UUID from reaching Mongoose as a CastError, which would nack as a
|
|
994
|
+
// retryable `error` and replay forever.
|
|
995
|
+
const model = mongoose.models[entry.modelName];
|
|
996
|
+
if (mutation.id && model && isObjectIdKeyed(model) && !isObjectIdHex(mutation.id)) {
|
|
997
|
+
return makeNack({
|
|
998
|
+
code: "validation",
|
|
999
|
+
message: `${mutation.collection} ids must be 24-character hex ObjectIds`,
|
|
1000
|
+
mutationId,
|
|
1001
|
+
reason: "invalid_id",
|
|
1002
|
+
});
|
|
1003
|
+
}
|
|
949
1004
|
|
|
950
1005
|
const request = req ?? ({user} as unknown as express.Request);
|
|
951
1006
|
|
package/src/sync/routes.ts
CHANGED
|
@@ -13,6 +13,7 @@ import {
|
|
|
13
13
|
resolveAdminBroadcastQueryFilter,
|
|
14
14
|
} from "./adminBroadcastScope";
|
|
15
15
|
import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
|
|
16
|
+
import {isObjectIdHex, isObjectIdKeyed} from "./entityIds";
|
|
16
17
|
import {
|
|
17
18
|
computeStableFrontier,
|
|
18
19
|
getCompactedThroughSeq,
|
|
@@ -256,7 +257,7 @@ const parseNonNegativeInt = (raw: unknown, name: string, fallback: number): numb
|
|
|
256
257
|
|
|
257
258
|
/**
|
|
258
259
|
* Task 9.14: the legacy cursor is a raw `_id` string, so it must be compared in the
|
|
259
|
-
* model's OWN `_id` BSON type. Synced models
|
|
260
|
+
* model's OWN `_id` BSON type. Synced models default to client-minted string
|
|
260
261
|
* `_id`s: casting those to `ObjectId` either throws (non-hex ids) or — worse — silently
|
|
261
262
|
* compares across BSON types and matches nothing, so the legacy stratum reported itself
|
|
262
263
|
* exhausted after one page and the remaining documents were never bootstrapped.
|
|
@@ -269,11 +270,10 @@ const legacyCursorClause = ({
|
|
|
269
270
|
model: SyncedModel;
|
|
270
271
|
legacyCursorIn: string;
|
|
271
272
|
}): Record<string, unknown> => {
|
|
272
|
-
|
|
273
|
-
if (idInstance !== "ObjectId") {
|
|
273
|
+
if (!isObjectIdKeyed(model)) {
|
|
274
274
|
return {_id: {$gt: legacyCursorIn}};
|
|
275
275
|
}
|
|
276
|
-
if (!
|
|
276
|
+
if (!isObjectIdHex(legacyCursorIn)) {
|
|
277
277
|
throw new APIError({status: 400, title: `Invalid legacyCursor: ${legacyCursorIn}`});
|
|
278
278
|
}
|
|
279
279
|
return {_id: {$gt: new mongoose.Types.ObjectId(legacyCursorIn)}};
|
|
@@ -473,9 +473,12 @@ export const MAX_ENTITY_FETCH = 100;
|
|
|
473
473
|
|
|
474
474
|
/**
|
|
475
475
|
* Task 9.27: `_id: {$in: ids}` leaves the cast to Mongoose, so one non-hex id against an
|
|
476
|
-
* ObjectId-keyed model threw a CastError that surfaced as a 500
|
|
477
|
-
*
|
|
478
|
-
*
|
|
476
|
+
* ObjectId-keyed model threw a CastError that surfaced as a 500. A non-hex id cannot name a
|
|
477
|
+
* document of such a model, so it is dropped and comes back absent, which is the true answer.
|
|
478
|
+
* Failing the whole request instead would wedge a client's repair batch: a create the server
|
|
479
|
+
* rejected for a bad id is queued for repair under that id, and every other id in the batch
|
|
480
|
+
* would never load. Models with client-minted string `_id`s (see `legacyCursorClause`) take
|
|
481
|
+
* any shape.
|
|
479
482
|
*/
|
|
480
483
|
const castEntityIds = ({
|
|
481
484
|
model,
|
|
@@ -484,18 +487,10 @@ const castEntityIds = ({
|
|
|
484
487
|
ids: string[];
|
|
485
488
|
model: SyncedModel;
|
|
486
489
|
}): (string | mongoose.Types.ObjectId)[] => {
|
|
487
|
-
|
|
488
|
-
if (idInstance !== "ObjectId") {
|
|
490
|
+
if (!isObjectIdKeyed(model)) {
|
|
489
491
|
return ids;
|
|
490
492
|
}
|
|
491
|
-
|
|
492
|
-
if (invalid.length > 0) {
|
|
493
|
-
throw new APIError({
|
|
494
|
-
status: 400,
|
|
495
|
-
title: `Invalid ids for ${model.modelName}: ${invalid.join(",")}`,
|
|
496
|
-
});
|
|
497
|
-
}
|
|
498
|
-
return ids.map((id) => new mongoose.Types.ObjectId(id));
|
|
493
|
+
return ids.filter(isObjectIdHex).map((id) => new mongoose.Types.ObjectId(id));
|
|
499
494
|
};
|
|
500
495
|
|
|
501
496
|
/**
|
|
@@ -1021,12 +1021,16 @@ describe("sync routes", () => {
|
|
|
1021
1021
|
// Task 9.27(b): bad caller input on the repair-fetch endpoint used to come back as a 500
|
|
1022
1022
|
// (CastError) or, worse, a truncated 200 the client read as "those entities are gone".
|
|
1023
1023
|
describe("GET /sync/entities input validation (Task 9.27)", () => {
|
|
1024
|
-
it("
|
|
1024
|
+
it("returns ids that cannot be cast to the model's _id type as absent (not a 500)", async () => {
|
|
1025
1025
|
const doc = await RouteStuffModel.create({name: "real", ownerId: notAdminId});
|
|
1026
|
+
// A rejected client-minted UUID create is queued for repair under that id; it must not
|
|
1027
|
+
// fail the rest of the repair batch.
|
|
1026
1028
|
const res = await agent
|
|
1027
|
-
.get(
|
|
1028
|
-
|
|
1029
|
-
|
|
1029
|
+
.get(
|
|
1030
|
+
`/sync/entities?collection=routeStuff&ids=${doc._id},not-an-object-id,${crypto.randomUUID()},abcdefghijkl`
|
|
1031
|
+
)
|
|
1032
|
+
.expect(200);
|
|
1033
|
+
expect(res.body.entities.map((e: SnapshotEntity) => e.id)).toEqual([String(doc._id)]);
|
|
1030
1034
|
});
|
|
1031
1035
|
|
|
1032
1036
|
it("400s instead of silently truncating an over-cap id list", async () => {
|
package/src/sync/types.ts
CHANGED
|
@@ -199,6 +199,13 @@ export interface SyncAck {
|
|
|
199
199
|
|
|
200
200
|
export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
|
|
201
201
|
|
|
202
|
+
/**
|
|
203
|
+
* Why a `validation` nack rejected a mutation, when the cause is the entity id itself.
|
|
204
|
+
* `id_collision`: a create named an `_id` that already exists. `invalid_id`: the id is not a
|
|
205
|
+
* 24-character hex ObjectId for an ObjectId-keyed collection.
|
|
206
|
+
*/
|
|
207
|
+
export type SyncNackReason = "id_collision" | "invalid_id";
|
|
208
|
+
|
|
202
209
|
/** Rejected mutation. Conflict nacks carry the canonical server document. */
|
|
203
210
|
export interface SyncNack {
|
|
204
211
|
mutationId: string;
|
|
@@ -208,6 +215,8 @@ export interface SyncNack {
|
|
|
208
215
|
/** The server document's current `_syncSeq` (conflict nacks). */
|
|
209
216
|
serverSeq?: number;
|
|
210
217
|
message?: string;
|
|
218
|
+
/** Set on `validation` nacks caused by the entity id (see {@link SyncNackReason}). */
|
|
219
|
+
reason?: SyncNackReason;
|
|
211
220
|
/**
|
|
212
221
|
* Minimum time (ms) the client should wait before retrying, filled by the
|
|
213
222
|
* server with the remaining rate-limit window (`rate_limited` nacks only).
|
package/biome.jsonc
DELETED
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
|
|
3
|
-
"extends": ["../biome.jsonc"],
|
|
4
|
-
"files": {
|
|
5
|
-
"includes": [
|
|
6
|
-
"package.json",
|
|
7
|
-
"src/**/*.ts",
|
|
8
|
-
"src/**/*.tsx",
|
|
9
|
-
"e2e/**/*.ts",
|
|
10
|
-
"!!src/populate.ts",
|
|
11
|
-
"!!**/node_modules",
|
|
12
|
-
"!!node_modules",
|
|
13
|
-
"!!**/dist",
|
|
14
|
-
"!!dist",
|
|
15
|
-
"!!**/build",
|
|
16
|
-
"!!build",
|
|
17
|
-
"!!**/coverage",
|
|
18
|
-
"!!coverage"
|
|
19
|
-
]
|
|
20
|
-
},
|
|
21
|
-
"root": true
|
|
22
|
-
}
|
package/bunfig.toml
DELETED
|
@@ -1,10 +0,0 @@
|
|
|
1
|
-
[test]
|
|
2
|
-
preload = ["./src/tests/testEnv.ts", "./src/tests/bunSetup.ts"]
|
|
3
|
-
root = "./src"
|
|
4
|
-
coverage = true
|
|
5
|
-
coveragePathIgnorePatterns = ["dist/**", "**/*.test.ts", "**/*.isolated.ts", "**/isolated/**", "**/tests/**", "**/vendor/**", "../**"]
|
|
6
|
-
# Enforced by scripts/check-coverage.ts; Bun parses this key but does not
|
|
7
|
-
# fail the run when coverage is below threshold. See
|
|
8
|
-
# https://github.com/oven-sh/bun/issues/7367 and https://github.com/oven-sh/bun/pull/27933.
|
|
9
|
-
coverageThreshold = { line = 95, function = 95 }
|
|
10
|
-
|
package/bunfig.unit.toml
DELETED
package/e2e/smoke.ts
DELETED
|
@@ -1,193 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Real-process smoke for @terreno/api. Run `bun e2e/smoke.ts` after `bun run compile`.
|
|
3
|
-
*
|
|
4
|
-
* The smoke re-runs this file with `serve` as a child process: a minimal TerrenoApp built from
|
|
5
|
-
* the compiled package with one modelRouter model, on a free port, against `smokeMongoUri()`.
|
|
6
|
-
* The parent then checks over real HTTP that `/health` answers, a user can sign up, and that
|
|
7
|
-
* user can create and list a document. Exits non-zero on the first failed check.
|
|
8
|
-
*/
|
|
9
|
-
import {
|
|
10
|
-
freePort,
|
|
11
|
-
type SpawnedProcess,
|
|
12
|
-
smokeMongoUri,
|
|
13
|
-
spawnUntilReady,
|
|
14
|
-
stopSmokeMongo,
|
|
15
|
-
} from "@terreno/test";
|
|
16
|
-
import type express from "express";
|
|
17
|
-
import {DateTime} from "luxon";
|
|
18
|
-
import type {Schema} from "mongoose";
|
|
19
|
-
|
|
20
|
-
const SERVE_ARG = "serve";
|
|
21
|
-
|
|
22
|
-
interface SmokeWidget {
|
|
23
|
-
_id: string;
|
|
24
|
-
name: string;
|
|
25
|
-
ownerId: string;
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
/**
|
|
29
|
-
* Child: the compiled API with auth, one owner-scoped model, and a health plugin. The API is
|
|
30
|
-
* imported here, not at the top, so the parent process never loads it.
|
|
31
|
-
*/
|
|
32
|
-
const serve = async (): Promise<void> => {
|
|
33
|
-
const {createdUpdatedPlugin, logger, modelRouter, OwnerQueryFilter, Permissions, TerrenoApp} =
|
|
34
|
-
await import("@terreno/api");
|
|
35
|
-
const {default: mongoose} = await import("mongoose");
|
|
36
|
-
const {default: passportLocalMongoose} = await import("passport-local-mongoose");
|
|
37
|
-
|
|
38
|
-
const userSchema = new mongoose.Schema({
|
|
39
|
-
admin: {default: false, description: "Whether the user is an admin", type: Boolean},
|
|
40
|
-
email: {description: "Sign-in email", type: String},
|
|
41
|
-
name: {description: "Display name", type: String},
|
|
42
|
-
});
|
|
43
|
-
userSchema.plugin(passportLocalMongoose as unknown as (schema: Schema, options: object) => void, {
|
|
44
|
-
usernameCaseInsensitive: true,
|
|
45
|
-
usernameField: "email",
|
|
46
|
-
});
|
|
47
|
-
userSchema.plugin(createdUpdatedPlugin);
|
|
48
|
-
const User = mongoose.model("User", userSchema);
|
|
49
|
-
|
|
50
|
-
const widgetSchema = new mongoose.Schema({
|
|
51
|
-
name: {description: "Widget name", required: true, type: String},
|
|
52
|
-
ownerId: {description: "User who owns the widget", ref: "User", type: String},
|
|
53
|
-
});
|
|
54
|
-
widgetSchema.plugin(createdUpdatedPlugin);
|
|
55
|
-
const Widget = mongoose.model("Widget", widgetSchema);
|
|
56
|
-
|
|
57
|
-
const widgetRouter = modelRouter("/widgets", Widget, {
|
|
58
|
-
permissions: {
|
|
59
|
-
create: [Permissions.IsAuthenticated],
|
|
60
|
-
delete: [],
|
|
61
|
-
list: [Permissions.IsAuthenticated],
|
|
62
|
-
read: [Permissions.IsOwner],
|
|
63
|
-
update: [],
|
|
64
|
-
},
|
|
65
|
-
preCreate: (body, req) => {
|
|
66
|
-
const user = req.user as unknown as {_id: string};
|
|
67
|
-
return {...(body as {name: string}), ownerId: String(user._id)};
|
|
68
|
-
},
|
|
69
|
-
queryFilter: OwnerQueryFilter,
|
|
70
|
-
});
|
|
71
|
-
|
|
72
|
-
const healthPlugin = {
|
|
73
|
-
register: (app: express.Application): void => {
|
|
74
|
-
app.get("/health", (_req, res) => {
|
|
75
|
-
res.json({healthy: mongoose.connection.readyState === 1});
|
|
76
|
-
});
|
|
77
|
-
},
|
|
78
|
-
};
|
|
79
|
-
|
|
80
|
-
await mongoose.connect(process.env.MONGO_URI as string);
|
|
81
|
-
const app = new TerrenoApp({
|
|
82
|
-
loggingOptions: {logRequests: false},
|
|
83
|
-
userModel: User as unknown as ConstructorParameters<typeof TerrenoApp>[0]["userModel"],
|
|
84
|
-
})
|
|
85
|
-
.register(widgetRouter)
|
|
86
|
-
.register(healthPlugin);
|
|
87
|
-
app.start();
|
|
88
|
-
await app.whenReady();
|
|
89
|
-
logger.info(`[apiSmoke] serving on port ${process.env.PORT}`);
|
|
90
|
-
};
|
|
91
|
-
|
|
92
|
-
const expectStatus = async (res: Response, status: number, step: string): Promise<unknown> => {
|
|
93
|
-
const body = await res.text();
|
|
94
|
-
if (res.status !== status) {
|
|
95
|
-
throw new Error(`${step}: expected ${status}, got ${res.status}: ${body}`);
|
|
96
|
-
}
|
|
97
|
-
return body ? JSON.parse(body) : undefined;
|
|
98
|
-
};
|
|
99
|
-
|
|
100
|
-
/** Parent: boots the child and walks the happy path over HTTP. */
|
|
101
|
-
const run = async (): Promise<void> => {
|
|
102
|
-
const startedAt = DateTime.now();
|
|
103
|
-
const port = await freePort();
|
|
104
|
-
const baseUrl = `http://127.0.0.1:${port}`;
|
|
105
|
-
let server: SpawnedProcess | undefined;
|
|
106
|
-
|
|
107
|
-
try {
|
|
108
|
-
server = await spawnUntilReady({
|
|
109
|
-
cmd: [process.execPath, __filename, SERVE_ARG],
|
|
110
|
-
env: {
|
|
111
|
-
MONGO_URI: await smokeMongoUri({databaseName: "apiSmoke"}),
|
|
112
|
-
PORT: String(port),
|
|
113
|
-
REFRESH_TOKEN_SECRET: "api-smoke-refresh-secret",
|
|
114
|
-
SESSION_SECRET: "api-smoke-session-secret",
|
|
115
|
-
TOKEN_ISSUER: "api-smoke",
|
|
116
|
-
TOKEN_SECRET: "api-smoke-token-secret",
|
|
117
|
-
},
|
|
118
|
-
timeoutMs: 20000,
|
|
119
|
-
url: `${baseUrl}/health`,
|
|
120
|
-
});
|
|
121
|
-
|
|
122
|
-
const health = (await expectStatus(await fetch(`${baseUrl}/health`), 200, "GET /health")) as {
|
|
123
|
-
healthy: boolean;
|
|
124
|
-
};
|
|
125
|
-
if (!health.healthy) {
|
|
126
|
-
throw new Error("GET /health: server reports unhealthy");
|
|
127
|
-
}
|
|
128
|
-
console.info("✅ GET /health is healthy");
|
|
129
|
-
|
|
130
|
-
const email = `api-smoke-${startedAt.toMillis()}@example.com`;
|
|
131
|
-
const signup = (await expectStatus(
|
|
132
|
-
await fetch(`${baseUrl}/auth/signup`, {
|
|
133
|
-
body: JSON.stringify({email, password: "api-smoke-password-1"}),
|
|
134
|
-
headers: {"Content-Type": "application/json"},
|
|
135
|
-
method: "POST",
|
|
136
|
-
}),
|
|
137
|
-
200,
|
|
138
|
-
"POST /auth/signup"
|
|
139
|
-
)) as {data: {token: string; userId: string}};
|
|
140
|
-
const headers = {
|
|
141
|
-
Authorization: `Bearer ${signup.data.token}`,
|
|
142
|
-
"Content-Type": "application/json",
|
|
143
|
-
};
|
|
144
|
-
console.info("✅ POST /auth/signup returns a token");
|
|
145
|
-
|
|
146
|
-
const created = (await expectStatus(
|
|
147
|
-
await fetch(`${baseUrl}/widgets`, {
|
|
148
|
-
body: JSON.stringify({name: "Smoke widget"}),
|
|
149
|
-
headers,
|
|
150
|
-
method: "POST",
|
|
151
|
-
}),
|
|
152
|
-
201,
|
|
153
|
-
"POST /widgets"
|
|
154
|
-
)) as {data: SmokeWidget};
|
|
155
|
-
if (created.data.ownerId !== String(signup.data.userId)) {
|
|
156
|
-
throw new Error(`POST /widgets: ownerId ${created.data.ownerId} is not the new user`);
|
|
157
|
-
}
|
|
158
|
-
console.info("✅ POST /widgets creates an owned widget");
|
|
159
|
-
|
|
160
|
-
const listed = (await expectStatus(
|
|
161
|
-
await fetch(`${baseUrl}/widgets`, {headers}),
|
|
162
|
-
200,
|
|
163
|
-
"GET /widgets"
|
|
164
|
-
)) as {data: SmokeWidget[]};
|
|
165
|
-
if (!listed.data.some((widget) => widget._id === created.data._id)) {
|
|
166
|
-
throw new Error("GET /widgets: the created widget is missing from the list");
|
|
167
|
-
}
|
|
168
|
-
console.info("✅ GET /widgets lists it");
|
|
169
|
-
} catch (error: unknown) {
|
|
170
|
-
if (server) {
|
|
171
|
-
console.error(`--- server output ---\n${server.output()}`);
|
|
172
|
-
}
|
|
173
|
-
throw error;
|
|
174
|
-
} finally {
|
|
175
|
-
await server?.stop();
|
|
176
|
-
await stopSmokeMongo();
|
|
177
|
-
}
|
|
178
|
-
|
|
179
|
-
console.info(`api smoke passed in ${DateTime.now().diff(startedAt).toMillis()} ms`);
|
|
180
|
-
};
|
|
181
|
-
|
|
182
|
-
const main = process.argv[2] === SERVE_ARG ? serve : run;
|
|
183
|
-
main().then(
|
|
184
|
-
() => {
|
|
185
|
-
if (main === run) {
|
|
186
|
-
process.exit(0);
|
|
187
|
-
}
|
|
188
|
-
},
|
|
189
|
-
(error: unknown) => {
|
|
190
|
-
console.error(`❌ ${error instanceof Error ? error.message : String(error)}`);
|
|
191
|
-
process.exit(1);
|
|
192
|
-
}
|
|
193
|
-
);
|
package/tsconfig.json
DELETED
|
@@ -1,19 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"compilerOptions": {
|
|
3
|
-
"allowJs": true,
|
|
4
|
-
"declaration": true,
|
|
5
|
-
"isolatedModules": true,
|
|
6
|
-
"lib": ["es2023"],
|
|
7
|
-
"module": "nodenext",
|
|
8
|
-
"noImplicitAny": false,
|
|
9
|
-
"noImplicitReturns": true,
|
|
10
|
-
"outDir": "./dist",
|
|
11
|
-
"rootDir": "./src",
|
|
12
|
-
"skipLibCheck": true,
|
|
13
|
-
"strict": true,
|
|
14
|
-
"target": "es2023",
|
|
15
|
-
"types": ["bun", "node"]
|
|
16
|
-
},
|
|
17
|
-
"exclude": ["node_modules", "**/*.test.ts", "**/*.isolated.ts", "src/isolated", "src/tests", "src/migrations/cli.ts"],
|
|
18
|
-
"include": ["src"]
|
|
19
|
-
}
|
package/tsconfig.typecheck.json
DELETED
package/tsconfig.typedoc.json
DELETED