@terreno/api 0.31.0 → 56.0.0-beta.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 +122 -2
- package/LICENSE +202 -21
- package/dist/api.d.ts +12 -3
- package/dist/api.js +110 -361
- package/dist/auth.d.ts +26 -0
- package/dist/auth.js +100 -1
- package/dist/betterAuth.d.ts +5 -0
- package/dist/betterAuthSetup.d.ts +1 -15
- package/dist/betterAuthSetup.js +29 -8
- package/dist/configurationPlugin.js +2 -2
- package/dist/docLoader.js +12 -9
- package/dist/errors.d.ts +13 -0
- package/dist/errors.js +29 -1
- package/dist/expressServer.js +5 -11
- package/dist/githubAuth.js +4 -1
- package/dist/index.d.ts +17 -1
- package/dist/index.js +29 -1
- package/dist/middleware.d.ts +7 -0
- package/dist/middleware.js +16 -1
- package/dist/openApiCompat.d.ts +10 -1
- package/dist/openApiCompat.js +115 -47
- package/dist/permissions.d.ts +27 -0
- package/dist/permissions.js +42 -1
- package/dist/plugins.d.ts +15 -3
- package/dist/plugins.js +36 -6
- package/dist/realtime/changeStreamWatcher.d.ts +100 -3
- package/dist/realtime/changeStreamWatcher.js +542 -137
- package/dist/realtime/realtimeApp.d.ts +3 -1
- package/dist/realtime/realtimeApp.js +75 -27
- package/dist/realtime/sessionRevalidation.d.ts +90 -0
- package/dist/realtime/sessionRevalidation.js +438 -0
- package/dist/realtime/socketAuth.d.ts +97 -0
- package/dist/realtime/socketAuth.js +272 -0
- package/dist/realtime/socketUser.d.ts +54 -0
- package/dist/realtime/socketUser.js +75 -5
- package/dist/realtime/types.d.ts +40 -0
- package/dist/secretProviders.d.ts +23 -0
- package/dist/secretProviders.js +9 -3
- package/dist/sync/executors.d.ts +198 -0
- package/dist/sync/executors.js +670 -0
- package/dist/sync/loadHarness.js +807 -0
- package/dist/sync/models.d.ts +216 -0
- package/dist/sync/models.js +644 -0
- package/dist/sync/mutationHandler.d.ts +97 -0
- package/dist/sync/mutationHandler.js +886 -0
- package/dist/sync/registry.d.ts +73 -0
- package/dist/sync/registry.js +223 -0
- package/dist/sync/routes.d.ts +62 -0
- package/dist/sync/routes.js +936 -0
- package/dist/sync/scripts/compactTombstones.d.ts +47 -0
- package/dist/sync/scripts/compactTombstones.js +270 -0
- package/dist/sync/serialize.d.ts +20 -0
- package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
- package/dist/sync/socketHandlers.d.ts +54 -0
- package/dist/sync/socketHandlers.js +470 -0
- package/dist/sync/streams.d.ts +85 -0
- package/dist/sync/streams.js +221 -0
- package/dist/sync/syncApp.d.ts +29 -0
- package/dist/sync/syncApp.js +44 -0
- package/dist/sync/syncBatch.d.ts +71 -0
- package/dist/sync/syncBatch.js +252 -0
- package/dist/sync/syncSeqPlugin.d.ts +8 -0
- package/dist/sync/syncSeqPlugin.js +903 -0
- package/dist/sync/types.d.ts +254 -0
- package/dist/sync/types.js +9 -0
- package/dist/terrenoApp.js +90 -27
- package/dist/tests/models.d.ts +11 -27
- package/dist/tests/models.js +3 -5
- package/dist/tests/testHelper.d.ts +3 -9
- package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
- package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
- package/package.json +10 -8
- package/src/__tests__/openApiCompat.test.ts +20 -0
- package/src/actions.test.ts +12 -19
- package/src/actions.ts +2 -2
- package/src/api.coverage.test.ts +9 -7
- package/src/api.errorPaths.test.ts +1 -47
- package/src/api.test.ts +12 -0
- package/src/api.ts +98 -317
- package/src/auth.test.ts +128 -176
- package/src/auth.ts +109 -0
- package/src/betterAuth.ts +6 -0
- package/src/betterAuthSetup.test.ts +34 -0
- package/src/betterAuthSetup.ts +27 -8
- package/src/configurationPlugin.ts +2 -2
- package/src/consentApp.test.ts +12 -12
- package/src/docLoader.ts +3 -1
- package/src/errors.ts +33 -0
- package/src/expressServer.test.ts +7 -1
- package/src/expressServer.ts +5 -11
- package/src/githubAuth.ts +3 -1
- package/src/index.ts +42 -0
- package/src/middleware.test.ts +40 -1
- package/src/middleware.ts +15 -0
- package/src/models/versionConfig.ts +1 -1
- package/src/openApiBuilder.test.ts +9 -24
- package/src/openApiCompat.ts +99 -45
- package/src/openApiValidator.test.ts +0 -41
- package/src/permissions.test.ts +75 -1
- package/src/permissions.ts +49 -0
- package/src/plugins.test.ts +54 -14
- package/src/plugins.ts +47 -9
- package/src/populate.test.ts +16 -25
- package/src/realtime/changeStreamWatcher.ts +552 -114
- package/src/realtime/realtime.test.ts +157 -239
- package/src/realtime/realtimeApp.ts +80 -19
- package/src/realtime/sessionRevalidation.test.ts +423 -0
- package/src/realtime/sessionRevalidation.ts +273 -0
- package/src/realtime/socketAuth.test.ts +355 -0
- package/src/realtime/socketAuth.ts +228 -0
- package/src/realtime/socketUser.ts +69 -0
- package/src/realtime/types.ts +40 -0
- package/src/secretProviders.test.ts +7 -1
- package/src/secretProviders.ts +15 -3
- package/src/sync/ensureSyncIndexes.test.ts +144 -0
- package/src/sync/executors.test.ts +882 -0
- package/src/sync/executors.ts +703 -0
- package/src/sync/integration.test.ts +1160 -0
- package/src/sync/loadHarness.ts +618 -0
- package/src/sync/models.ts +640 -0
- package/src/sync/mutationHandler.test.ts +1252 -0
- package/src/sync/mutationHandler.ts +850 -0
- package/src/sync/registry.ts +232 -0
- package/src/sync/routes.ts +812 -0
- package/src/sync/scripts/compactTombstones.test.ts +249 -0
- package/src/sync/scripts/compactTombstones.ts +145 -0
- package/src/sync/serialize.ts +48 -0
- package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
- package/src/sync/socketHandlers.ts +320 -0
- package/src/sync/streams.ts +188 -0
- package/src/sync/sync.test.ts +582 -0
- package/src/sync/syncApp.ts +44 -0
- package/src/sync/syncBatch.ts +219 -0
- package/src/sync/syncFrontier.test.ts +494 -0
- package/src/sync/syncPhaseC.test.ts +718 -0
- package/src/sync/syncRoutes.test.ts +865 -0
- package/src/sync/syncSeqPlugin.ts +738 -0
- package/src/sync/syncSocket.test.ts +1440 -0
- package/src/sync/types.ts +270 -0
- package/src/terrenoApp.ts +37 -17
- package/src/tests/bunSetup.ts +8 -0
- package/src/tests/models.ts +6 -8
- package/tsconfig.json +4 -4
- package/tsconfig.typedoc.json +7 -1
- package/dist/__tests__/openApiCompat.test.js +0 -317
- package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
- package/dist/__tests__/versionCheckPlugin.test.js +0 -597
- package/dist/actions.openApi.test.d.ts +0 -1
- package/dist/actions.openApi.test.js +0 -253
- package/dist/actions.test.d.ts +0 -1
- package/dist/actions.test.js +0 -1087
- package/dist/api.arrayOperations.test.d.ts +0 -1
- package/dist/api.arrayOperations.test.js +0 -878
- package/dist/api.asyncHandler.test.d.ts +0 -1
- package/dist/api.asyncHandler.test.js +0 -236
- package/dist/api.coverage.test.d.ts +0 -1
- package/dist/api.coverage.test.js +0 -192
- package/dist/api.errorPaths.test.d.ts +0 -1
- package/dist/api.errorPaths.test.js +0 -887
- package/dist/api.errors.test.d.ts +0 -1
- package/dist/api.errors.test.js +0 -185
- package/dist/api.hooks.test.d.ts +0 -1
- package/dist/api.hooks.test.js +0 -950
- package/dist/api.query.test.d.ts +0 -1
- package/dist/api.query.test.js +0 -948
- package/dist/api.test.d.ts +0 -1
- package/dist/api.test.js +0 -2820
- package/dist/auth.compile.test.d.ts +0 -1
- package/dist/auth.compile.test.js +0 -201
- package/dist/auth.coverage.test.d.ts +0 -1
- package/dist/auth.coverage.test.js +0 -202
- package/dist/auth.test.d.ts +0 -1
- package/dist/auth.test.js +0 -2286
- package/dist/betterAuth.test.d.ts +0 -1
- package/dist/betterAuth.test.js +0 -181
- package/dist/betterAuthApp.test.d.ts +0 -1
- package/dist/betterAuthApp.test.js +0 -242
- package/dist/betterAuthSetup.test.d.ts +0 -1
- package/dist/betterAuthSetup.test.js +0 -762
- package/dist/config.test.d.ts +0 -1
- package/dist/config.test.js +0 -353
- package/dist/configuration.test.d.ts +0 -1
- package/dist/configuration.test.js +0 -980
- package/dist/configurationPlugin.test.d.ts +0 -1
- package/dist/configurationPlugin.test.js +0 -827
- package/dist/consentApp.test.d.ts +0 -1
- package/dist/consentApp.test.js +0 -1411
- package/dist/docLoader.test.d.ts +0 -1
- package/dist/docLoader.test.js +0 -137
- package/dist/envConfigurationPlugin.test.d.ts +0 -1
- package/dist/envConfigurationPlugin.test.js +0 -369
- package/dist/errors.test.d.ts +0 -1
- package/dist/errors.test.js +0 -607
- package/dist/expressServer.test.d.ts +0 -1
- package/dist/expressServer.test.js +0 -1249
- package/dist/githubAuth.test.d.ts +0 -1
- package/dist/githubAuth.test.js +0 -1142
- package/dist/httpClient.test.d.ts +0 -1
- package/dist/httpClient.test.js +0 -1471
- package/dist/logger.test.d.ts +0 -1
- package/dist/logger.test.js +0 -685
- package/dist/middleware.test.d.ts +0 -1
- package/dist/middleware.test.js +0 -241
- package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
- package/dist/notifiers/googleChatNotifier.test.js +0 -298
- package/dist/notifiers/slackNotifier.test.d.ts +0 -1
- package/dist/notifiers/slackNotifier.test.js +0 -297
- package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
- package/dist/notifiers/zoomNotifier.test.js +0 -373
- package/dist/openApi.test.d.ts +0 -1
- package/dist/openApi.test.js +0 -620
- package/dist/openApiBuilder.test.d.ts +0 -1
- package/dist/openApiBuilder.test.js +0 -599
- package/dist/openApiEtag.test.d.ts +0 -1
- package/dist/openApiEtag.test.js +0 -86
- package/dist/openApiValidator.test.d.ts +0 -1
- package/dist/openApiValidator.test.js +0 -795
- package/dist/permissions.middleware.test.d.ts +0 -1
- package/dist/permissions.middleware.test.js +0 -308
- package/dist/permissions.test.d.ts +0 -1
- package/dist/permissions.test.js +0 -439
- package/dist/plugins.test.d.ts +0 -1
- package/dist/plugins.test.js +0 -902
- package/dist/populate.test.d.ts +0 -1
- package/dist/populate.test.js +0 -370
- package/dist/realtime/realtime.test.d.ts +0 -10
- package/dist/realtime/realtime.test.js +0 -4213
- package/dist/realtime/realtimeAppSetup.test.d.ts +0 -1
- package/dist/realtime/realtimeAppSetup.test.js +0 -213
- package/dist/requestContext.test.d.ts +0 -1
- package/dist/requestContext.test.js +0 -412
- package/dist/scriptRunner.test.d.ts +0 -1
- package/dist/scriptRunner.test.js +0 -386
- package/dist/secretProviders.test.d.ts +0 -1
- package/dist/secretProviders.test.js +0 -726
- package/dist/syncConsents.test.d.ts +0 -1
- package/dist/syncConsents.test.js +0 -522
- package/dist/terrenoApp.test.d.ts +0 -1
- package/dist/terrenoApp.test.js +0 -489
- package/dist/tests/bunSetup.d.ts +0 -1
- package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
- package/dist/tests/fixtures/compileAuthEntry.js +0 -37
- package/dist/tests/testEnv.d.ts +0 -0
- package/dist/tests/testEnv.js +0 -6
- package/dist/transformers.test.d.ts +0 -1
- package/dist/transformers.test.js +0 -423
- package/dist/utils.test.d.ts +0 -1
- package/dist/utils.test.js +0 -242
- package/src/realtime/realtimeAppSetup.test.ts +0 -161
- /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared types for the SyncDB local-first sync protocol.
|
|
3
|
+
*
|
|
4
|
+
* These types are the contract between @terreno/api (server) and @terreno/syncdb (client):
|
|
5
|
+
* scope/stream configuration, snapshot payloads, mutation requests, and delta events.
|
|
6
|
+
* See docs/implementationPlans/syncdb-local-first.md.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** Scope a collection's streams by document owner (default field: `ownerId`). */
|
|
10
|
+
export interface SyncScopeOwner {
|
|
11
|
+
type: "owner";
|
|
12
|
+
/** Field holding the owning user's id. Defaults to "ownerId". */
|
|
13
|
+
field?: string;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Scope a collection's streams by a tenant/workspace field (e.g. `organizationId`). */
|
|
17
|
+
export interface SyncScopeTenant {
|
|
18
|
+
type: "tenant";
|
|
19
|
+
/** Field holding the tenant/workspace id. */
|
|
20
|
+
field: string;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** A single shared stream for the whole collection (all authenticated users). */
|
|
24
|
+
export interface SyncScopeBroadcast {
|
|
25
|
+
type: "broadcast";
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Custom scope resolver: given a document, return its scope value (e.g. a workspace id).
|
|
30
|
+
* The stream key becomes `{collection}|custom:{value}`.
|
|
31
|
+
*/
|
|
32
|
+
export type SyncScopeResolver = (doc: Record<string, unknown>) => string;
|
|
33
|
+
|
|
34
|
+
export type SyncScope = SyncScopeOwner | SyncScopeTenant | SyncScopeBroadcast | SyncScopeResolver;
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Configuration for local-first sync on a modelRouter, parallel to `realtime`.
|
|
38
|
+
* Requires the model schema to use `isDeletedPlugin` (soft delete) and `syncPlugin`
|
|
39
|
+
* (seq stamping) — validated at registration.
|
|
40
|
+
*/
|
|
41
|
+
export interface SyncConfig {
|
|
42
|
+
/** Which stream a document belongs to. Multi-tenant by default via the tenant scope. */
|
|
43
|
+
scope: SyncScope;
|
|
44
|
+
/**
|
|
45
|
+
* Custom serializer for sync payloads (snapshot entities and deltas).
|
|
46
|
+
* Falls back to the modelRouter responseHandler, then the document's toJSON.
|
|
47
|
+
*/
|
|
48
|
+
responseHandler?: (doc: Record<string, unknown>, method: SyncMutationOperation) => unknown;
|
|
49
|
+
/**
|
|
50
|
+
* Server-side query restricting snapshots to the caller's documents. Derived
|
|
51
|
+
* automatically for owner scopes ({field: user.id}) and tenant scopes
|
|
52
|
+
* ({field: {$in: getUserScopes(...)}}); REQUIRED for custom resolver scopes, whose
|
|
53
|
+
* stream function cannot be inverted into a Mongo query.
|
|
54
|
+
*/
|
|
55
|
+
snapshotFilter?: (user: {
|
|
56
|
+
id: string;
|
|
57
|
+
}) => Record<string, unknown> | Promise<Record<string, unknown>>;
|
|
58
|
+
/**
|
|
59
|
+
* C7: tombstone retention window in days (default 90). Tombstones older than this may
|
|
60
|
+
* be hard-deleted by the `compactTombstones` maintenance script; a client whose cursor
|
|
61
|
+
* predates the retained floor re-bootstraps (see `oldestRetainedSeq`).
|
|
62
|
+
*/
|
|
63
|
+
retentionDays?: number;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export type SyncMutationOperation = "create" | "update" | "delete";
|
|
67
|
+
|
|
68
|
+
/** A single entity in a snapshot response. */
|
|
69
|
+
export interface SyncEntityPayload {
|
|
70
|
+
/** Document id. */
|
|
71
|
+
id: string;
|
|
72
|
+
/** Serialized document data (present for tombstones too, so clients can render conflicts). */
|
|
73
|
+
data: unknown;
|
|
74
|
+
/** The document's `_syncSeq` — the client's per-entity version and cursor source. */
|
|
75
|
+
seq: number;
|
|
76
|
+
/** True when the entity is a soft-delete tombstone. */
|
|
77
|
+
deleted: boolean;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Response shape for `GET /sync/snapshot` (C2: one stream per request).
|
|
82
|
+
*/
|
|
83
|
+
export interface SyncSnapshotResponse {
|
|
84
|
+
/** The stream this page belongs to (echoed from the request). */
|
|
85
|
+
stream: string;
|
|
86
|
+
entities: SyncEntityPayload[];
|
|
87
|
+
/**
|
|
88
|
+
* Highest seq included in this page (C1: never above `frontierSeq`); pass back as
|
|
89
|
+
* `cursor` to continue.
|
|
90
|
+
*/
|
|
91
|
+
cursor: number;
|
|
92
|
+
/** True when more pages remain past `cursor` (more committed OR uncommitted seqs). */
|
|
93
|
+
hasMore: boolean;
|
|
94
|
+
/** C1: the stream's stable frontier — the client must not advance its cursor beyond this. */
|
|
95
|
+
frontierSeq: number;
|
|
96
|
+
/**
|
|
97
|
+
* C7: the lowest seq still retained for this stream after tombstone compaction. A
|
|
98
|
+
* client whose stored cursor is below this may have missed compacted tombstones and
|
|
99
|
+
* must re-bootstrap the stream from 0 (sanctioned wipe: retention gap, not auth).
|
|
100
|
+
*/
|
|
101
|
+
oldestRetainedSeq: number;
|
|
102
|
+
/**
|
|
103
|
+
* C3: opaque forward token for paging the legacy (seq-0) stratum by `_id`. Present
|
|
104
|
+
* while unstamped legacy documents remain; absent once the stratum is exhausted and
|
|
105
|
+
* paging proceeds by seq. The client echoes it back verbatim.
|
|
106
|
+
*/
|
|
107
|
+
legacyCursor?: string;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** Response shape for `GET /sync/entities` (point lookup for repair). */
|
|
111
|
+
export interface SyncEntitiesResponse {
|
|
112
|
+
entities: SyncEntityPayload[];
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** One stream a user currently belongs to, from `GET /sync/streams`. */
|
|
116
|
+
export interface SyncStreamInfo {
|
|
117
|
+
/** The stream key (e.g. "todos|owner:123"). */
|
|
118
|
+
stream: string;
|
|
119
|
+
/** The collection tag the stream belongs to. */
|
|
120
|
+
collection: string;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** Response shape for `GET /sync/streams`. */
|
|
124
|
+
export interface SyncStreamsResponse {
|
|
125
|
+
streams: SyncStreamInfo[];
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** A client mutation delivered via `sync:mutate` or `POST /sync/mutate`. */
|
|
129
|
+
export interface SyncMutateRequest {
|
|
130
|
+
/** Client-generated stable id; the idempotency key. */
|
|
131
|
+
mutationId: string;
|
|
132
|
+
/** Collection tag (e.g. "todos"). */
|
|
133
|
+
collection: string;
|
|
134
|
+
operation: SyncMutationOperation;
|
|
135
|
+
/** Target document id (required for update/delete; client-generated allowed for create). */
|
|
136
|
+
id?: string;
|
|
137
|
+
/** Fields to write (create/update). */
|
|
138
|
+
data?: Record<string, unknown>;
|
|
139
|
+
/** The `_syncSeq` the client last saw for this document; enables LWW conflict detection. */
|
|
140
|
+
baseVersion?: number;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** Successful mutation acknowledgement. */
|
|
144
|
+
export interface SyncAck {
|
|
145
|
+
mutationId: string;
|
|
146
|
+
/** The document id (server-assigned for creates). */
|
|
147
|
+
id: string;
|
|
148
|
+
/** The document's new `_syncSeq`. */
|
|
149
|
+
seq: number;
|
|
150
|
+
/**
|
|
151
|
+
* C5 (FIX 6): set when the document write succeeded and the ledger
|
|
152
|
+
* finalized `applied`, but the model's post-hook (`postCreate`/
|
|
153
|
+
* `postUpdate`/`postDelete`) threw. The mutation is still a full success —
|
|
154
|
+
* this is informational only, never a reason to retry or roll back.
|
|
155
|
+
*/
|
|
156
|
+
warning?: string;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
|
|
160
|
+
|
|
161
|
+
/** Rejected mutation. Conflict nacks carry the canonical server document. */
|
|
162
|
+
export interface SyncNack {
|
|
163
|
+
mutationId: string;
|
|
164
|
+
code: SyncNackCode;
|
|
165
|
+
/** Canonical serialized server document (conflict nacks). */
|
|
166
|
+
serverDoc?: unknown;
|
|
167
|
+
/** The server document's current `_syncSeq` (conflict nacks). */
|
|
168
|
+
serverSeq?: number;
|
|
169
|
+
message?: string;
|
|
170
|
+
/**
|
|
171
|
+
* Minimum time (ms) the client should wait before retrying, filled by the
|
|
172
|
+
* server with the remaining rate-limit window (`rate_limited` nacks only).
|
|
173
|
+
*/
|
|
174
|
+
retryAfterMs?: number;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* A batch of client mutations delivered via `sync:mutateBatch` or
|
|
179
|
+
* `POST /sync/mutate/batch`. The server MUST apply strictly in array order and
|
|
180
|
+
* stop at the first non-ack outcome (see `applySyncMutationBatch`).
|
|
181
|
+
*/
|
|
182
|
+
export interface SyncMutateBatchRequest {
|
|
183
|
+
/** Ordered mutations; each still carries its own mutationId. */
|
|
184
|
+
mutations: SyncMutateRequest[];
|
|
185
|
+
/**
|
|
186
|
+
* Client-generated correlation id, socket transport only (ignored over
|
|
187
|
+
* HTTP). Echoed back immediately via `sync:batchReceived {batchId}` before
|
|
188
|
+
* processing begins, so the client can distinguish "the server has no
|
|
189
|
+
* sync:mutateBatch handler" (silence past the grace period, batching
|
|
190
|
+
* unsupported) from "the server is just slow to finish this batch" (a
|
|
191
|
+
* receipt arrived; keep waiting up to the full batch timeout).
|
|
192
|
+
*/
|
|
193
|
+
batchId?: string;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** One result per PROCESSED mutation in a batch, in request order. */
|
|
197
|
+
export type SyncMutateBatchResult = {type: "ack"; ack: SyncAck} | {type: "nack"; nack: SyncNack};
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Response to a batch mutation request.
|
|
201
|
+
*
|
|
202
|
+
* `results.length < request.mutations.length` means the server halted at the
|
|
203
|
+
* first non-ack: `results[results.length - 1]` is that failing outcome, and
|
|
204
|
+
* every mutation after it was NOT attempted (not ledgered, not applied) —
|
|
205
|
+
* still safe to resend in a later batch (INV-3).
|
|
206
|
+
*/
|
|
207
|
+
export interface SyncMutateBatchResponse {
|
|
208
|
+
results: SyncMutateBatchResult[];
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* A change event delivered to subscribed clients via `sync:delta`.
|
|
213
|
+
*
|
|
214
|
+
* ## Per-entity ordering & the LWW-by-seq contract (C8)
|
|
215
|
+
*
|
|
216
|
+
* The server serializes delta dispatch PER entity (`{collection}:{id}`): two deltas for
|
|
217
|
+
* the same document are always emitted in change-stream (commit) order, so their `seq`
|
|
218
|
+
* values arrive monotonically for that entity. Deltas for DIFFERENT entities may arrive
|
|
219
|
+
* in any order (they dispatch concurrently). Clients therefore apply last-writer-wins
|
|
220
|
+
* BY SEQ within an entity: a delta whose `seq` is at or below the entity's applied seq is
|
|
221
|
+
* an idempotent no-op; only a strictly higher `seq` mutates local state. Combined with
|
|
222
|
+
* the C1 frontier (`frontierSeq`), a cursor never advances past an uncommitted seq, so no
|
|
223
|
+
* committed delta is ever permanently skipped.
|
|
224
|
+
*/
|
|
225
|
+
export interface SyncDelta {
|
|
226
|
+
/** Collection tag (e.g. "todos"). */
|
|
227
|
+
collection: string;
|
|
228
|
+
/** Document id. */
|
|
229
|
+
id: string;
|
|
230
|
+
method: SyncMutationOperation;
|
|
231
|
+
/** Serialized document data (omitted for tombstone deltas emitted to a previous stream). */
|
|
232
|
+
data?: unknown;
|
|
233
|
+
/** The document's `_syncSeq`. */
|
|
234
|
+
seq: number;
|
|
235
|
+
/** Stream key this delta belongs to (e.g. "todos|owner:123"). */
|
|
236
|
+
stream: string;
|
|
237
|
+
/**
|
|
238
|
+
* C1: the stream's stable frontier at emit time. The client advances its cursor to
|
|
239
|
+
* `min(seq, frontierSeq)` so a delta observed out of commit order never advances a
|
|
240
|
+
* cursor past an uncommitted hole.
|
|
241
|
+
*/
|
|
242
|
+
frontierSeq?: number;
|
|
243
|
+
/** True when the entity is soft-deleted. */
|
|
244
|
+
deleted?: boolean;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* Payload of the `sync:resync-required` socket event (Task 9.16).
|
|
249
|
+
*
|
|
250
|
+
* Emitted server-wide when the change stream could not be resumed — the oplog no longer
|
|
251
|
+
* contains the resume point, so the events in the gap can never be delivered. Any cursor a
|
|
252
|
+
* client holds may now sit below changes (including deletions) it will never be told about,
|
|
253
|
+
* so the only safe response is to re-bootstrap every stream. Clients that do not handle the
|
|
254
|
+
* event still converge on their next full bootstrap; handling it just makes that immediate.
|
|
255
|
+
*/
|
|
256
|
+
export interface SyncResyncHint {
|
|
257
|
+
/** Why the resync is needed. Only `history_lost` exists today. */
|
|
258
|
+
reason: "history_lost";
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** Fields added to synced documents by `syncPlugin`. */
|
|
262
|
+
export interface SyncedDocumentFields {
|
|
263
|
+
/** Monotonic per-stream sequence stamped on every synced write. */
|
|
264
|
+
_syncSeq?: number;
|
|
265
|
+
/**
|
|
266
|
+
* The document's previous stream key, set when a write moved the document between
|
|
267
|
+
* scopes (owner/tenant change); null when the last write did not move it.
|
|
268
|
+
*/
|
|
269
|
+
_syncPrevStream?: string | null;
|
|
270
|
+
}
|
package/src/terrenoApp.ts
CHANGED
|
@@ -24,6 +24,7 @@ import {
|
|
|
24
24
|
requestContextMiddleware,
|
|
25
25
|
updateRequestContextFromRequest,
|
|
26
26
|
} from "./requestContext";
|
|
27
|
+
import {ensureSyncIndexes} from "./sync/registry";
|
|
27
28
|
import type {TerrenoPlugin} from "./terrenoPlugin";
|
|
28
29
|
import openapi from "./vendor/wesleytodd-openapi/index";
|
|
29
30
|
|
|
@@ -419,7 +420,16 @@ export class TerrenoApp {
|
|
|
419
420
|
if (!hasRealtimePlugin) {
|
|
420
421
|
const realtimeConfig =
|
|
421
422
|
typeof this.options.realtime === "object" ? this.options.realtime : {};
|
|
422
|
-
this.register(
|
|
423
|
+
this.register(
|
|
424
|
+
new RealtimeApp({
|
|
425
|
+
...realtimeConfig,
|
|
426
|
+
// Task 9.21 (D2): default the socket full-user load to this app's own user
|
|
427
|
+
// model. Without it socket authorization falls back to the synthetic
|
|
428
|
+
// JWT-claim user, which trusts the token's `admin` over the database and
|
|
429
|
+
// carries no membership fields for tenant-scoped sync.
|
|
430
|
+
userModel: realtimeConfig.userModel ?? (this.options.userModel as never),
|
|
431
|
+
})
|
|
432
|
+
);
|
|
423
433
|
}
|
|
424
434
|
}
|
|
425
435
|
|
|
@@ -427,24 +437,34 @@ export class TerrenoApp {
|
|
|
427
437
|
|
|
428
438
|
if (!this.options.skipListen) {
|
|
429
439
|
const port = process.env.PORT || "9000";
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
440
|
+
// Await sync index creation before listening: the per-model snapshot indexes (a
|
|
441
|
+
// failed createIndex degrades the snapshot/catch-up query to a table scan) and the
|
|
442
|
+
// bookkeeping-model indexes enqueued by SyncApp (the unique mutationId index is what
|
|
443
|
+
// makes duplicate mutation deliveries idempotent, and the unique stream index is what
|
|
444
|
+
// keeps the counter upsert race from minting duplicate seqs). Either failure is a
|
|
445
|
+
// loud startup error rather than a silent correctness cliff. No-op when no sync
|
|
446
|
+
// models or SyncApp are registered. Detached because start() returns synchronously.
|
|
447
|
+
void (async (): Promise<void> => {
|
|
448
|
+
try {
|
|
449
|
+
await ensureSyncIndexes();
|
|
450
|
+
const server = createServer(app);
|
|
451
|
+
|
|
452
|
+
// Notify plugins that need access to the HTTP server (e.g. WebSocket plugins)
|
|
453
|
+
for (const reg of this.registrations) {
|
|
454
|
+
if (!this.isModelRouterRegistration(reg) && typeof reg.onServerCreated === "function") {
|
|
455
|
+
reg.onServerCreated(server);
|
|
456
|
+
}
|
|
437
457
|
}
|
|
438
|
-
}
|
|
439
458
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
459
|
+
server.listen(port, () => {
|
|
460
|
+
logger.info(`Listening on port ${port}`);
|
|
461
|
+
});
|
|
462
|
+
} catch (error) {
|
|
463
|
+
const stack = error instanceof Error ? error.stack : String(error);
|
|
464
|
+
logger.error(`Error trying to start HTTP server: ${error}\n${stack}`);
|
|
465
|
+
process.exit(1);
|
|
466
|
+
}
|
|
467
|
+
})();
|
|
448
468
|
}
|
|
449
469
|
|
|
450
470
|
return app;
|
package/src/tests/bunSetup.ts
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
import {registerBackendPreload, registerSimpleMongoPreload} from "@terreno/test";
|
|
2
2
|
|
|
3
|
+
import {winstonLogger} from "../logger";
|
|
4
|
+
|
|
3
5
|
const useFixtureCache = process.env.TERRENO_TEST_USE_FIXTURE_CACHE === "true";
|
|
4
6
|
|
|
7
|
+
// Hand @terreno/test this package's logger directly; letting it require("@terreno/api")
|
|
8
|
+
// would load the built dist next to the sources under test.
|
|
9
|
+
const silenceLogs = {additionalWinstonLoggers: [winstonLogger]};
|
|
10
|
+
|
|
5
11
|
if (useFixtureCache) {
|
|
6
12
|
registerBackendPreload({
|
|
7
13
|
connectMongoInBeforeAll: true,
|
|
@@ -13,6 +19,7 @@ if (useFixtureCache) {
|
|
|
13
19
|
baseDatabaseName: "terrenoTest_base",
|
|
14
20
|
useReplSet: true,
|
|
15
21
|
},
|
|
22
|
+
silenceLogs,
|
|
16
23
|
testEnv: {
|
|
17
24
|
tokenIssuer: "terreno-api.test",
|
|
18
25
|
},
|
|
@@ -20,6 +27,7 @@ if (useFixtureCache) {
|
|
|
20
27
|
});
|
|
21
28
|
} else {
|
|
22
29
|
registerSimpleMongoPreload({
|
|
30
|
+
silenceLogs,
|
|
23
31
|
testEnv: {
|
|
24
32
|
tokenIssuer: "terreno-api.test",
|
|
25
33
|
},
|
package/src/tests/models.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import mongoose, {type Model, model, Schema
|
|
1
|
+
import mongoose, {type Model, model, Schema} from "mongoose";
|
|
2
2
|
import passportLocalMongoose from "passport-local-mongoose";
|
|
3
3
|
|
|
4
4
|
import {createdUpdatedPlugin, DateOnly, isDisabledPlugin} from "../plugins";
|
|
@@ -41,11 +41,11 @@ export interface Food {
|
|
|
41
41
|
dateAdded?: string;
|
|
42
42
|
};
|
|
43
43
|
tags: string[];
|
|
44
|
-
eatenBy:
|
|
44
|
+
eatenBy: [Schema.Types.ObjectId | User];
|
|
45
45
|
lastEatenWith: {[name: string]: Date};
|
|
46
46
|
categories: FoodCategory[];
|
|
47
47
|
expiration: string;
|
|
48
|
-
likesIds: {userId:
|
|
48
|
+
likesIds: {userId: string; likes: boolean}[];
|
|
49
49
|
}
|
|
50
50
|
|
|
51
51
|
export interface RequiredField {
|
|
@@ -126,11 +126,9 @@ const foodSchema = new Schema<Food>(
|
|
|
126
126
|
type: Schema.Types.ObjectId,
|
|
127
127
|
},
|
|
128
128
|
],
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
type: DateOnly as unknown as StringSchemaDefinition,
|
|
133
|
-
},
|
|
129
|
+
// noExplicitAny: DateOnly is a custom SchemaType not recognized by Mongoose's built-in type definitions
|
|
130
|
+
// biome-ignore lint/suspicious/noExplicitAny: DateOnly is a custom SchemaType not recognized by Mongoose's built-in type definitions
|
|
131
|
+
expiration: {description: "Expiration date of the food", type: DateOnly as any},
|
|
134
132
|
hidden: {
|
|
135
133
|
default: false,
|
|
136
134
|
description: "Whether this food is hidden from listings",
|
package/tsconfig.json
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
// "lib": [], /* Specify library files to be included in the compilation. */
|
|
4
4
|
"allowJs": true /* Allow javascript files to be compiled. */,
|
|
5
5
|
"allowSyntheticDefaultImports": true /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */,
|
|
6
|
-
"declaration": true /* Generates corresponding '.d.ts' file. */,
|
|
7
6
|
"downlevelIteration": true,
|
|
7
|
+
"declaration": true /* Generates corresponding '.d.ts' file. */,
|
|
8
8
|
"esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
|
|
9
9
|
// "preserveSymlinks": true, /* Do not resolve the real path of symlinks. */
|
|
10
10
|
/* Source Map Options */
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
// "experimentalDecorators": true, /* Enables experimental support for ES7 decorators. */
|
|
17
17
|
// "emitDecoratorMetadata": true, /* Enables experimental support for emitting type metadata for decorators. */
|
|
18
18
|
"forceConsistentCasingInFileNames": true,
|
|
19
|
+
"ignoreDeprecations": "6.0",
|
|
19
20
|
// "checkJs": true, /* Report errors in .js files. */
|
|
20
21
|
"jsx": "react" /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */,
|
|
21
22
|
"lib": ["es2017", "dom", "es2017.object", "es2022.error"],
|
|
@@ -24,7 +25,6 @@
|
|
|
24
25
|
// "noFallthroughCasesInSwitch": true, /* Report errors for fallthrough cases in switch statement. */
|
|
25
26
|
/* Module Resolution Options */
|
|
26
27
|
"moduleResolution": "node" /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */,
|
|
27
|
-
// "rootDir": "./", /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
|
|
28
28
|
"rootDir": "./src",
|
|
29
29
|
// "removeComments": true, /* Do not emit comments to output. */
|
|
30
30
|
"noEmit": false /* Do not emit outputs. */,
|
|
@@ -55,6 +55,6 @@
|
|
|
55
55
|
/* Basic Options */
|
|
56
56
|
"target": "es5" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */
|
|
57
57
|
},
|
|
58
|
-
"exclude": ["node_modules"],
|
|
59
|
-
"include": ["src/**/*.ts*", "src/*.ts", "src/**/*.js"]
|
|
58
|
+
"exclude": ["node_modules", "**/*.test.ts", "src/tests"],
|
|
59
|
+
"include": ["src/**/*.ts*", "src/*.ts", "src/**/*.js", "src/**/*.d.ts"]
|
|
60
60
|
}
|
package/tsconfig.typedoc.json
CHANGED