@tapedb/tapedb 0.0.0-stage → 0.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/API.md +301 -0
- package/LICENSE +21 -0
- package/LIMITATIONS.md +34 -0
- package/PRIVACY.md +119 -0
- package/README.md +720 -2
- package/RELEASING.md +117 -0
- package/SECURITY.md +121 -0
- package/dist/chunk-3AL32Q4K.js +241 -0
- package/dist/chunk-3AL32Q4K.js.map +1 -0
- package/dist/chunk-CYDXFAEB.js +33 -0
- package/dist/chunk-CYDXFAEB.js.map +1 -0
- package/dist/chunk-UYZJAMBR.js +27 -0
- package/dist/chunk-UYZJAMBR.js.map +1 -0
- package/dist/chunk-VWW5OS5B.js +841 -0
- package/dist/chunk-VWW5OS5B.js.map +1 -0
- package/dist/cli.d.ts +44 -0
- package/dist/cli.js +1501 -0
- package/dist/cli.js.map +1 -0
- package/dist/client-DgSnn9BE.d.ts +646 -0
- package/dist/index.d.ts +24 -0
- package/dist/index.js +3007 -0
- package/dist/index.js.map +1 -0
- package/dist/react.d.ts +41 -0
- package/dist/react.js +59 -0
- package/dist/react.js.map +1 -0
- package/dist/schema-CVcGZJfR.d.ts +691 -0
- package/dist/schema-entry-CpO_IGFv.d.ts +522 -0
- package/dist/schema.d.ts +2 -0
- package/dist/schema.js +22 -0
- package/dist/schema.js.map +1 -0
- package/dist/worker.d.ts +437 -0
- package/dist/worker.js +9270 -0
- package/dist/worker.js.map +1 -0
- package/package.json +93 -4
|
@@ -0,0 +1,691 @@
|
|
|
1
|
+
interface StorageObject {
|
|
2
|
+
id: string;
|
|
3
|
+
key: string;
|
|
4
|
+
size: number;
|
|
5
|
+
etag: string;
|
|
6
|
+
contentType: string;
|
|
7
|
+
}
|
|
8
|
+
interface StorageClient {
|
|
9
|
+
upload(path: string, file: Blob, signal?: AbortSignal): Promise<StorageObject>;
|
|
10
|
+
download(path: string, signal?: AbortSignal): Promise<Blob>;
|
|
11
|
+
delete(path: string, signal?: AbortSignal): Promise<void>;
|
|
12
|
+
}
|
|
13
|
+
type StorageFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Types for the client runtime: engine query documents, wire ops, outbox
|
|
17
|
+
* entries and the runtime facade the model client drives. They mirror the
|
|
18
|
+
* engine's wire contracts without importing the engine, so the client bundle
|
|
19
|
+
* stays free of server code.
|
|
20
|
+
*/
|
|
21
|
+
type AttributeType$1 = "string" | "number" | "boolean" | "date" | "json" | "any";
|
|
22
|
+
interface AttributeDefinition$1<T = unknown> {
|
|
23
|
+
readonly type: AttributeType$1;
|
|
24
|
+
readonly isOptional: boolean;
|
|
25
|
+
readonly isIndexed: boolean;
|
|
26
|
+
readonly isUnique: boolean;
|
|
27
|
+
optional(): AttributeDefinition$1<T>;
|
|
28
|
+
indexed(): AttributeDefinition$1<T>;
|
|
29
|
+
unique(): AttributeDefinition$1<T>;
|
|
30
|
+
}
|
|
31
|
+
interface EntityDefinition {
|
|
32
|
+
readonly type: "entity";
|
|
33
|
+
readonly attrs: Record<string, AttributeDefinition$1<unknown>>;
|
|
34
|
+
}
|
|
35
|
+
interface LinkSide {
|
|
36
|
+
on: string;
|
|
37
|
+
has: "one" | "many";
|
|
38
|
+
label: string;
|
|
39
|
+
}
|
|
40
|
+
interface LinkDefinition$1 {
|
|
41
|
+
forward: LinkSide;
|
|
42
|
+
reverse: LinkSide;
|
|
43
|
+
}
|
|
44
|
+
interface SchemaDefinition {
|
|
45
|
+
entities: Record<string, EntityDefinition>;
|
|
46
|
+
links: Record<string, LinkDefinition$1>;
|
|
47
|
+
}
|
|
48
|
+
type QueryScalar$1 = string | number | boolean | null;
|
|
49
|
+
interface QueryComparison$1 {
|
|
50
|
+
$ne?: QueryScalar$1;
|
|
51
|
+
$in?: QueryScalar$1[];
|
|
52
|
+
$nin?: QueryScalar$1[];
|
|
53
|
+
$gt?: QueryScalar$1;
|
|
54
|
+
$gte?: QueryScalar$1;
|
|
55
|
+
$lt?: QueryScalar$1;
|
|
56
|
+
$lte?: QueryScalar$1;
|
|
57
|
+
}
|
|
58
|
+
type QueryWhereValue$1 = QueryScalar$1 | QueryComparison$1;
|
|
59
|
+
interface QueryWhere$1 {
|
|
60
|
+
[attribute: string]: QueryWhereValue$1 | QueryWhere$1 | QueryWhere$1[] | undefined;
|
|
61
|
+
$or?: QueryWhere$1[];
|
|
62
|
+
$and?: QueryWhere$1[];
|
|
63
|
+
$not?: QueryWhere$1;
|
|
64
|
+
}
|
|
65
|
+
interface QueryOptions {
|
|
66
|
+
where?: QueryWhere$1;
|
|
67
|
+
order?: Record<string, "asc" | "desc">;
|
|
68
|
+
limit?: number;
|
|
69
|
+
/**
|
|
70
|
+
* Opaque cursor from a previous page's `pageInfo[namespace].nextCursor`.
|
|
71
|
+
* The engine requires an explicit `order`, because a cursor is only
|
|
72
|
+
* meaningful against a total order. `db.loadMore()` sends this for you.
|
|
73
|
+
*/
|
|
74
|
+
after?: string;
|
|
75
|
+
/** Top level only: report the total matching rows as `pageInfo[ns].count`. */
|
|
76
|
+
count?: boolean;
|
|
77
|
+
}
|
|
78
|
+
interface QueryNode {
|
|
79
|
+
$?: QueryOptions;
|
|
80
|
+
[link: string]: unknown;
|
|
81
|
+
}
|
|
82
|
+
type QueryDocument = Record<string, QueryNode>;
|
|
83
|
+
/** One entity as returned by the engine. Nested links are plain properties. */
|
|
84
|
+
type QueryEntity = Record<string, unknown>;
|
|
85
|
+
/** Result payload keyed by the requested top-level namespace names. */
|
|
86
|
+
type QueryResult = Record<string, QueryEntity[]>;
|
|
87
|
+
interface QueryError {
|
|
88
|
+
code: string;
|
|
89
|
+
message: string;
|
|
90
|
+
}
|
|
91
|
+
/** Truncation metadata the engine reports per namespace. */
|
|
92
|
+
interface PageInfo {
|
|
93
|
+
/** The effective limit, or null when the namespace is uncapped. */
|
|
94
|
+
limit: number | null;
|
|
95
|
+
/** Rows the engine returned after row-level view rules, not rows read. */
|
|
96
|
+
returned: number;
|
|
97
|
+
hasMore: boolean;
|
|
98
|
+
/**
|
|
99
|
+
* Opaque keyset cursor for the next page. Emitted only when `hasMore` is
|
|
100
|
+
* true and the query has an explicit `order`; `db.loadMore()` passes it back
|
|
101
|
+
* as `$: { after }`.
|
|
102
|
+
*/
|
|
103
|
+
nextCursor?: string;
|
|
104
|
+
/** Total matching rows, when the query asked for `count`. */
|
|
105
|
+
count?: number;
|
|
106
|
+
/** The groups, when the query asked for `aggregate`. */
|
|
107
|
+
aggregate?: AggregateGroup[];
|
|
108
|
+
}
|
|
109
|
+
/** One group of an aggregate, as the engine reports it. */
|
|
110
|
+
interface AggregateGroup {
|
|
111
|
+
/** The group's key values; empty without a groupBy. */
|
|
112
|
+
key: Record<string, unknown>;
|
|
113
|
+
count?: number;
|
|
114
|
+
countOf?: Record<string, number>;
|
|
115
|
+
sum?: Record<string, number | null>;
|
|
116
|
+
avg?: Record<string, number | null>;
|
|
117
|
+
min?: Record<string, unknown>;
|
|
118
|
+
max?: Record<string, unknown>;
|
|
119
|
+
}
|
|
120
|
+
type QueryPageInfo = Record<string, PageInfo>;
|
|
121
|
+
interface QueryState {
|
|
122
|
+
data: QueryResult | null;
|
|
123
|
+
isLoading: boolean;
|
|
124
|
+
error: QueryError | null;
|
|
125
|
+
/**
|
|
126
|
+
* Per top-level namespace truncation metadata from the engine. `returned` is
|
|
127
|
+
* the engine's own visible count; do not re-derive it from `data`.
|
|
128
|
+
*/
|
|
129
|
+
pageInfo?: QueryPageInfo;
|
|
130
|
+
}
|
|
131
|
+
interface PresencePeer {
|
|
132
|
+
clientId: string;
|
|
133
|
+
presence: unknown;
|
|
134
|
+
cursor?: unknown;
|
|
135
|
+
drag?: unknown;
|
|
136
|
+
}
|
|
137
|
+
type TxOpKind = "insert" | "patch" | "upsert" | "patchMany" | "deleteMany" | "update" | "merge" | "link" | "unlink" | "delete";
|
|
138
|
+
interface TxOpBase {
|
|
139
|
+
op: TxOpKind;
|
|
140
|
+
namespace: string;
|
|
141
|
+
id: string;
|
|
142
|
+
}
|
|
143
|
+
interface TxUpdateOp extends TxOpBase {
|
|
144
|
+
op: "update";
|
|
145
|
+
values: Record<string, unknown>;
|
|
146
|
+
}
|
|
147
|
+
interface TxInsertOp extends TxOpBase {
|
|
148
|
+
op: "insert";
|
|
149
|
+
values: Record<string, unknown>;
|
|
150
|
+
}
|
|
151
|
+
interface TxPatchOp extends TxOpBase {
|
|
152
|
+
op: "patch";
|
|
153
|
+
values: Record<string, unknown>;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Creates the row from `create` when it is missing, otherwise writes `values`.
|
|
157
|
+
* The engine decides inside the transaction, so the choice cannot race.
|
|
158
|
+
*/
|
|
159
|
+
interface TxUpsertOp extends TxOpBase {
|
|
160
|
+
op: "upsert";
|
|
161
|
+
values: Record<string, unknown>;
|
|
162
|
+
create: Record<string, unknown>;
|
|
163
|
+
}
|
|
164
|
+
interface TxMergeOp extends TxOpBase {
|
|
165
|
+
op: "merge";
|
|
166
|
+
values: Record<string, unknown>;
|
|
167
|
+
}
|
|
168
|
+
interface TxLinkOp extends TxOpBase {
|
|
169
|
+
op: "link";
|
|
170
|
+
link: string;
|
|
171
|
+
targetId: string;
|
|
172
|
+
}
|
|
173
|
+
interface TxUnlinkOp extends TxOpBase {
|
|
174
|
+
op: "unlink";
|
|
175
|
+
link: string;
|
|
176
|
+
targetId: string;
|
|
177
|
+
}
|
|
178
|
+
interface TxDeleteOp extends TxOpBase {
|
|
179
|
+
op: "delete";
|
|
180
|
+
}
|
|
181
|
+
interface TxPatchManyOp {
|
|
182
|
+
op: "patchMany";
|
|
183
|
+
namespace: string;
|
|
184
|
+
where: Record<string, unknown>;
|
|
185
|
+
values: Record<string, unknown>;
|
|
186
|
+
/** Resume after this id (engines before one-transaction bulk writes returned a cursor). */
|
|
187
|
+
after?: string;
|
|
188
|
+
}
|
|
189
|
+
interface TxDeleteManyOp {
|
|
190
|
+
op: "deleteMany";
|
|
191
|
+
namespace: string;
|
|
192
|
+
where: Record<string, unknown>;
|
|
193
|
+
after?: string;
|
|
194
|
+
}
|
|
195
|
+
type TxOp = TxPatchManyOp | TxDeleteManyOp | TxInsertOp | TxPatchOp | TxUpsertOp | TxUpdateOp | TxMergeOp | TxLinkOp | TxUnlinkOp | TxDeleteOp;
|
|
196
|
+
/** A group of ops that travels together. */
|
|
197
|
+
interface TxStep {
|
|
198
|
+
readonly ops: readonly TxOp[];
|
|
199
|
+
readonly op: TxOp;
|
|
200
|
+
}
|
|
201
|
+
type TransactInput = ReadonlyArray<TxStep | TxOp | ReadonlyArray<TxStep | TxOp>>;
|
|
202
|
+
interface OutboxEntry {
|
|
203
|
+
clientTxId: string;
|
|
204
|
+
txId: string;
|
|
205
|
+
workspaceId: string;
|
|
206
|
+
ops: TxOp[];
|
|
207
|
+
createdAt: number;
|
|
208
|
+
/** Sends started so far, persisted before each send. Absent means unknown. */
|
|
209
|
+
attempts?: number;
|
|
210
|
+
}
|
|
211
|
+
/** A queued write the server refused for good and the outbox dropped. */
|
|
212
|
+
interface WriteRejection {
|
|
213
|
+
clientTxId: string;
|
|
214
|
+
ops: TxOp[];
|
|
215
|
+
code: string;
|
|
216
|
+
message: string;
|
|
217
|
+
}
|
|
218
|
+
interface InitConfig {
|
|
219
|
+
/** Stable authenticated claim subject; required for default persistent authenticated browser clients. */
|
|
220
|
+
userId?: string;
|
|
221
|
+
/** Workspace UUID. */
|
|
222
|
+
workspaceId?: string;
|
|
223
|
+
/** Engine origin, e.g. http://localhost:8787. */
|
|
224
|
+
apiUrl?: string;
|
|
225
|
+
/** Override the derived `${apiUrl}/engine/workspaces/:id/websocket` URL. */
|
|
226
|
+
websocketUrl?: string;
|
|
227
|
+
/** Returns a short-lived role-claim JWT for every HTTP/WS request. */
|
|
228
|
+
getToken?: () => Promise<string>;
|
|
229
|
+
schema?: SchemaDefinition;
|
|
230
|
+
/**
|
|
231
|
+
* Called when a queued write is refused permanently during a background
|
|
232
|
+
* flush, after the outbox has dropped it.
|
|
233
|
+
*/
|
|
234
|
+
onWriteRejected?: (rejection: WriteRejection) => void;
|
|
235
|
+
}
|
|
236
|
+
/** Ephemeral presence channel on this client's workspace socket. */
|
|
237
|
+
interface DataRoom {
|
|
238
|
+
publishPresence(presence: unknown): void;
|
|
239
|
+
publishCursor(cursor: unknown): void;
|
|
240
|
+
publishDrag(drag: unknown): void;
|
|
241
|
+
clearDrag(): void;
|
|
242
|
+
subscribePresence(listener: (peers: PresencePeer[]) => void): () => void;
|
|
243
|
+
/** Clears local presence; subscription disposers remain owned by their callers. */
|
|
244
|
+
leave(): void;
|
|
245
|
+
}
|
|
246
|
+
interface DataClient {
|
|
247
|
+
transact(input: TransactInput): Promise<"applied" | "queued">;
|
|
248
|
+
/** Files scoped to the configured workspace and authenticated by its claim. */
|
|
249
|
+
files: StorageClient;
|
|
250
|
+
/** Reuses the workspace socket and its reconnect/replay behavior. */
|
|
251
|
+
room(target: string): DataRoom;
|
|
252
|
+
/** Test/dev helper: empties the pending outbox for this workspace. */
|
|
253
|
+
clearOutbox(): Promise<void>;
|
|
254
|
+
/** Retries pending writes now (also runs on reconnect and `online`). */
|
|
255
|
+
flushOutbox(): Promise<void>;
|
|
256
|
+
/** Subscribes to a query document; the model client's live reads use it. */
|
|
257
|
+
subscribeQuery(query: QueryDocument, listener: () => void): () => void;
|
|
258
|
+
/** Current cached state for a query, without subscribing to it. */
|
|
259
|
+
getQueryState(query: QueryDocument): QueryState;
|
|
260
|
+
/**
|
|
261
|
+
* Requests the next page for the cached query and appends it.
|
|
262
|
+
*
|
|
263
|
+
* Uses `pageInfo[namespace].nextCursor` for each **top-level** namespace that
|
|
264
|
+
* reported one, re-requests with `$: { ...options, after: cursor }`, appends
|
|
265
|
+
* the new rows deduped by `id`, and updates `pageInfo`. Resolves to `false`
|
|
266
|
+
* when there is no cursor left (first page not loaded yet, or exhausted).
|
|
267
|
+
*
|
|
268
|
+
* Nested link results arrive with the page and are not paginated: a cursor is
|
|
269
|
+
* only defined for the top-level namespace's order.
|
|
270
|
+
*
|
|
271
|
+
* After a page lands the live subscription widens to every loaded row, so a
|
|
272
|
+
* reconnect restores the whole window.
|
|
273
|
+
*/
|
|
274
|
+
loadMore(query: QueryDocument): Promise<boolean>;
|
|
275
|
+
/** Opens the shared WebSocket (lazy; safe to call repeatedly). */
|
|
276
|
+
connect(): Promise<void>;
|
|
277
|
+
/** Publishes this client's presence for a target (e.g. a diagram id). */
|
|
278
|
+
publishPresence(target: string, presence: unknown): void;
|
|
279
|
+
/** Publishes this client's cursor for a target. */
|
|
280
|
+
publishCursor(target: string, cursor: unknown): void;
|
|
281
|
+
/** Publishes an ephemeral drag preview for a target. */
|
|
282
|
+
publishDrag(target: string, drag: unknown): void;
|
|
283
|
+
/** Clears this client's drag preview for a target. */
|
|
284
|
+
clearDrag(target: string): void;
|
|
285
|
+
/** Removes this client's presence for a target. */
|
|
286
|
+
clearPresence(target: string): void;
|
|
287
|
+
/** Subscribes to the peer snapshot for a target; immediate first call. */
|
|
288
|
+
subscribePresence(target: string, listener: (peers: PresencePeer[]) => void): () => void;
|
|
289
|
+
/** Stops reconnection timers and closes the socket. */
|
|
290
|
+
close(): void;
|
|
291
|
+
}
|
|
292
|
+
/**
|
|
293
|
+
* Who sent a broadcast message.
|
|
294
|
+
*
|
|
295
|
+
* @experimental May change in a minor release.
|
|
296
|
+
*/
|
|
297
|
+
interface TopicSender {
|
|
298
|
+
/** The sending socket's client id: one per open client. */
|
|
299
|
+
clientId: string;
|
|
300
|
+
/** The claim subject (user id) the sender connected with. */
|
|
301
|
+
userId: string;
|
|
302
|
+
}
|
|
303
|
+
interface TopicListener {
|
|
304
|
+
message: (message: unknown, from: TopicSender) => void;
|
|
305
|
+
error?: (error: QueryError) => void;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* Shared role-claim contract between the Worker (JWT verification) and the
|
|
310
|
+
* workspace engine (permission checks).
|
|
311
|
+
* consumes this shape.
|
|
312
|
+
*/
|
|
313
|
+
declare const WORKSPACE_ROLE_LEVELS: {
|
|
314
|
+
readonly GUEST: 0;
|
|
315
|
+
readonly USER: 1;
|
|
316
|
+
readonly MEMBER: 2;
|
|
317
|
+
readonly EDITOR: 3;
|
|
318
|
+
readonly MODERATOR: 4;
|
|
319
|
+
readonly ADMIN: 5;
|
|
320
|
+
readonly OWNER: 6;
|
|
321
|
+
readonly FOUNDER: 7;
|
|
322
|
+
readonly DEVELOPER: 8;
|
|
323
|
+
};
|
|
324
|
+
type WorkspaceRole = (typeof WORKSPACE_ROLE_LEVELS)[keyof typeof WORKSPACE_ROLE_LEVELS];
|
|
325
|
+
interface RoleClaim {
|
|
326
|
+
/** Platform user id. */
|
|
327
|
+
sub: string;
|
|
328
|
+
/** Platform workspace id (the DO name). */
|
|
329
|
+
workspaceId: string;
|
|
330
|
+
/** Numeric workspace role level. */
|
|
331
|
+
role: WorkspaceRole;
|
|
332
|
+
/** Expiry, seconds since epoch. */
|
|
333
|
+
exp: number;
|
|
334
|
+
/** Issued at, seconds since epoch. */
|
|
335
|
+
iat: number;
|
|
336
|
+
iss?: string;
|
|
337
|
+
aud?: string;
|
|
338
|
+
}
|
|
339
|
+
declare function hasRoleLevel(role: WorkspaceRole, minimum: WorkspaceRole): boolean;
|
|
340
|
+
declare function hasRole(claim: RoleClaim, minimum: WorkspaceRole): boolean;
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* Per-file access rules: who may read, write and delete each file.
|
|
344
|
+
*
|
|
345
|
+
* Installed from the schema's `files` rules by `defineTapeDB`, in the Worker
|
|
346
|
+
* and in every Durable Object. Without rules the defaults are role levels
|
|
347
|
+
* (read: member, write and delete: editor), checked by the Worker alone, as
|
|
348
|
+
* before. With any rule the workspace's Durable Object decides every byte
|
|
349
|
+
* route and filters the file list, because only it holds the index (who
|
|
350
|
+
* uploaded what) and the rows a file can be attached to.
|
|
351
|
+
*
|
|
352
|
+
* A rule is one of:
|
|
353
|
+
* - a role level;
|
|
354
|
+
* - a check over the caller and the file (and, for a write, the file it
|
|
355
|
+
* replaces);
|
|
356
|
+
* - attachment to a row: the file follows the row's own rules. Reading it
|
|
357
|
+
* needs the row to be readable by the caller, writing or deleting it needs
|
|
358
|
+
* the caller to be allowed to update the row. A path that names no row, or
|
|
359
|
+
* a row that does not exist, denies.
|
|
360
|
+
*
|
|
361
|
+
* Every rule fails closed: one that throws denies.
|
|
362
|
+
*/
|
|
363
|
+
|
|
364
|
+
/** A file as rules see it. */
|
|
365
|
+
interface FileInfo {
|
|
366
|
+
path: string;
|
|
367
|
+
/** Bytes; null for a write whose size is not known yet. */
|
|
368
|
+
size: number | null;
|
|
369
|
+
contentType: string | null;
|
|
370
|
+
/** The uploader's claim subject. */
|
|
371
|
+
uploadedBy: string;
|
|
372
|
+
}
|
|
373
|
+
interface FileCheckContext {
|
|
374
|
+
auth: {
|
|
375
|
+
sub: string;
|
|
376
|
+
role: number;
|
|
377
|
+
workspaceId: string;
|
|
378
|
+
};
|
|
379
|
+
/** For read and delete, the stored file; for write, the incoming one. */
|
|
380
|
+
file: FileInfo;
|
|
381
|
+
/** For write, the stored file it would replace, if any. */
|
|
382
|
+
existing?: FileInfo;
|
|
383
|
+
}
|
|
384
|
+
type FileRule = {
|
|
385
|
+
readonly decision: "role";
|
|
386
|
+
readonly level: number;
|
|
387
|
+
} | {
|
|
388
|
+
readonly decision: "check";
|
|
389
|
+
readonly test: (context: FileCheckContext) => boolean;
|
|
390
|
+
} | {
|
|
391
|
+
readonly decision: "attachedTo";
|
|
392
|
+
readonly model: string;
|
|
393
|
+
readonly locate: (path: string) => string | null | undefined;
|
|
394
|
+
};
|
|
395
|
+
interface FileRules {
|
|
396
|
+
read?: FileRule;
|
|
397
|
+
write?: FileRule;
|
|
398
|
+
delete?: FileRule;
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
/**
|
|
402
|
+
* Registry mapping model names to workspace SQLite tables.
|
|
403
|
+
*
|
|
404
|
+
* The registry is the runtime contract shared by query compilation, envelope
|
|
405
|
+
* validation, permissions and durability. It is *not* a hardcoded schema: the
|
|
406
|
+
* consumer defines one schema with `defineSchema()` and the Worker hands the
|
|
407
|
+
* resulting registry to `configureRegistry()` before any request is served.
|
|
408
|
+
*
|
|
409
|
+
* Both `NAMESPACES` and `LINKS` are mutated in place rather than reassigned, so
|
|
410
|
+
* modules that imported the binding at load time observe the configured values.
|
|
411
|
+
* A deployment serves exactly one schema, so this configuration is per Worker
|
|
412
|
+
* instance, not per request.
|
|
413
|
+
*/
|
|
414
|
+
type AttributeType = "string" | "number" | "boolean" | "date" | "json" | "any";
|
|
415
|
+
type DeleteRule = "CASCADE" | "SET NULL" | "RESTRICT";
|
|
416
|
+
interface AttributeReference {
|
|
417
|
+
table: string;
|
|
418
|
+
column: string;
|
|
419
|
+
onDelete?: DeleteRule;
|
|
420
|
+
}
|
|
421
|
+
interface AttributeDefinition {
|
|
422
|
+
type: AttributeType;
|
|
423
|
+
personal?: {
|
|
424
|
+
subject: string;
|
|
425
|
+
required: boolean;
|
|
426
|
+
defaultValue?: string | number | null;
|
|
427
|
+
};
|
|
428
|
+
optional?: boolean;
|
|
429
|
+
/**
|
|
430
|
+
* Column default, as stored (booleans 0/1, dates epoch ms, json as text).
|
|
431
|
+
* Fills the field for rows written before it existed: replayed inserts and,
|
|
432
|
+
* through the migration, rows already in the table.
|
|
433
|
+
*/
|
|
434
|
+
default?: string | number | null;
|
|
435
|
+
indexed?: boolean;
|
|
436
|
+
unique?: boolean;
|
|
437
|
+
references?: AttributeReference;
|
|
438
|
+
}
|
|
439
|
+
interface NamespaceDefinition {
|
|
440
|
+
apiName: string;
|
|
441
|
+
table: string;
|
|
442
|
+
attributes: Record<string, AttributeDefinition>;
|
|
443
|
+
}
|
|
444
|
+
interface OneToManyLink {
|
|
445
|
+
apiName: string;
|
|
446
|
+
kind: "one-to-many";
|
|
447
|
+
forward: {
|
|
448
|
+
namespace: string;
|
|
449
|
+
label: string;
|
|
450
|
+
has: "many";
|
|
451
|
+
};
|
|
452
|
+
reverse: {
|
|
453
|
+
namespace: string;
|
|
454
|
+
label: string;
|
|
455
|
+
has: "one";
|
|
456
|
+
};
|
|
457
|
+
foreignKey: {
|
|
458
|
+
namespace: string;
|
|
459
|
+
attribute: string;
|
|
460
|
+
};
|
|
461
|
+
}
|
|
462
|
+
interface OneToOneLink {
|
|
463
|
+
apiName: string;
|
|
464
|
+
kind: "one-to-one";
|
|
465
|
+
forward: {
|
|
466
|
+
namespace: string;
|
|
467
|
+
label: string;
|
|
468
|
+
has: "one";
|
|
469
|
+
};
|
|
470
|
+
reverse: {
|
|
471
|
+
namespace: string;
|
|
472
|
+
label: string;
|
|
473
|
+
has: "one";
|
|
474
|
+
};
|
|
475
|
+
foreignKey: {
|
|
476
|
+
namespace: string;
|
|
477
|
+
attribute: string;
|
|
478
|
+
unique: true;
|
|
479
|
+
};
|
|
480
|
+
}
|
|
481
|
+
type LinkDefinition = OneToManyLink | OneToOneLink;
|
|
482
|
+
interface RegistryDefinition {
|
|
483
|
+
namespaces: readonly NamespaceDefinition[];
|
|
484
|
+
links: readonly LinkDefinition[];
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
/**
|
|
488
|
+
* Reading old data through later schema changes.
|
|
489
|
+
*
|
|
490
|
+
* Recovery restores a snapshot and replays log lines that were written under
|
|
491
|
+
* whatever schema was current at the time. If a migration since then dropped
|
|
492
|
+
* or renamed a field, an old line still names it, and replaying it against
|
|
493
|
+
* today's registry would fail and leave the workspace unable to boot.
|
|
494
|
+
*
|
|
495
|
+
* Migrations therefore declare what they changed, and recovery projects old
|
|
496
|
+
* rows and ops through every change made after they were written. Only
|
|
497
|
+
* declared changes are tolerated: an attribute or column that no migration
|
|
498
|
+
* accounts for is still an error, so corrupted or foreign data fails closed.
|
|
499
|
+
*/
|
|
500
|
+
type SchemaChange = {
|
|
501
|
+
kind: "dropModel";
|
|
502
|
+
model: string;
|
|
503
|
+
table: string;
|
|
504
|
+
} | {
|
|
505
|
+
kind: "renameModel";
|
|
506
|
+
from: string;
|
|
507
|
+
to: string;
|
|
508
|
+
fromTable: string;
|
|
509
|
+
toTable: string;
|
|
510
|
+
}
|
|
511
|
+
/** `table` is the model's table as of this migration. */
|
|
512
|
+
| {
|
|
513
|
+
kind: "dropField";
|
|
514
|
+
model: string;
|
|
515
|
+
table: string;
|
|
516
|
+
field: string;
|
|
517
|
+
column: string;
|
|
518
|
+
} | {
|
|
519
|
+
kind: "renameField";
|
|
520
|
+
model: string;
|
|
521
|
+
table: string;
|
|
522
|
+
from: string;
|
|
523
|
+
to: string;
|
|
524
|
+
fromColumn: string;
|
|
525
|
+
toColumn: string;
|
|
526
|
+
}
|
|
527
|
+
/** The field's type changed; an old value that no longer fits is dropped. */
|
|
528
|
+
| {
|
|
529
|
+
kind: "retypeField";
|
|
530
|
+
model: string;
|
|
531
|
+
field: string;
|
|
532
|
+
};
|
|
533
|
+
|
|
534
|
+
/**
|
|
535
|
+
* Workspace migrations, in two tracks.
|
|
536
|
+
*
|
|
537
|
+
* The engine track belongs to tapedb: `0001_baseline` (its bookkeeping tables,
|
|
538
|
+
* frozen because deployed workspaces hold its checksum) and every
|
|
539
|
+
* `tapedb_NNNN_*` migration after it. The app track belongs to the deployment:
|
|
540
|
+
* its `NNNN_*` migrations, generated from its schema. Engine migrations run
|
|
541
|
+
* first, so app SQL can rely on the engine's tables as they are now.
|
|
542
|
+
*
|
|
543
|
+
* The configured list is mutated in place by `configureMigrations()` so
|
|
544
|
+
* `migrations.ts` can keep its default-argument shape.
|
|
545
|
+
*/
|
|
546
|
+
|
|
547
|
+
interface BundledWorkspaceMigration {
|
|
548
|
+
id: string;
|
|
549
|
+
sql: string;
|
|
550
|
+
/**
|
|
551
|
+
* What this migration changed, for reading data written before it. Not part
|
|
552
|
+
* of the checksum: only the SQL changes a workspace.
|
|
553
|
+
*/
|
|
554
|
+
changes?: SchemaChange[];
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
/**
|
|
558
|
+
* Query document wire contract for the workspace engine.
|
|
559
|
+
*
|
|
560
|
+
* `where`, `order`, `limit`, `after`, `count`, `select`, `aggregate` and
|
|
561
|
+
* nested link traversal at any depth. This module owns the typed
|
|
562
|
+
* shapes and the registry-independent validation. Registry-specific checks
|
|
563
|
+
* (namespace, attribute and link existence) live in `query-compile.ts`.
|
|
564
|
+
*
|
|
565
|
+
* Values describe the API shape: attribute names are camelCase registry names,
|
|
566
|
+
* booleans are real booleans, dates are epoch milliseconds and `json`/`any`
|
|
567
|
+
* attributes are JSON values. Storage conversion happens in `query-execute.ts`.
|
|
568
|
+
*/
|
|
569
|
+
|
|
570
|
+
/** Scalars accepted by `where` and by comparison operators. */
|
|
571
|
+
type QueryScalar = string | number | boolean | null;
|
|
572
|
+
/** Supported comparison operators. Anything else is rejected. */
|
|
573
|
+
interface QueryComparison {
|
|
574
|
+
$ne?: QueryScalar;
|
|
575
|
+
$in?: QueryScalar[];
|
|
576
|
+
/** Not in the list. Like `$ne`, also matches rows where the value is null. */
|
|
577
|
+
$nin?: QueryScalar[];
|
|
578
|
+
$gt?: QueryScalar;
|
|
579
|
+
$gte?: QueryScalar;
|
|
580
|
+
$lt?: QueryScalar;
|
|
581
|
+
$lte?: QueryScalar;
|
|
582
|
+
}
|
|
583
|
+
type QueryWhereValue = QueryScalar | QueryComparison;
|
|
584
|
+
/**
|
|
585
|
+
* Attribute conditions, ANDed. Three reserved keys combine whole filters:
|
|
586
|
+
* `$or` and `$and` take non-empty arrays of filters, `$not` takes one.
|
|
587
|
+
*/
|
|
588
|
+
/** How a relation filter matches: the parent row, or some/every/no children. */
|
|
589
|
+
type RelationMode = "parent" | "some" | "every" | "none";
|
|
590
|
+
/**
|
|
591
|
+
* A filter on a linked namespace, by the same label `include` uses. Compiled
|
|
592
|
+
* into a correlated subquery, so the rows are never fetched.
|
|
593
|
+
*/
|
|
594
|
+
interface QueryRelationFilter {
|
|
595
|
+
label: string;
|
|
596
|
+
mode: RelationMode;
|
|
597
|
+
where: QueryWhere;
|
|
598
|
+
}
|
|
599
|
+
interface QueryWhere {
|
|
600
|
+
[attribute: string]: QueryWhereValue | QueryWhere | QueryWhere[] | QueryRelationFilter[] | undefined;
|
|
601
|
+
$or?: QueryWhere[];
|
|
602
|
+
$and?: QueryWhere[];
|
|
603
|
+
$not?: QueryWhere;
|
|
604
|
+
$link?: QueryRelationFilter[];
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
/**
|
|
608
|
+
* Permissions.
|
|
609
|
+
*
|
|
610
|
+
* Two kinds of decision, one place:
|
|
611
|
+
*
|
|
612
|
+
* - a **role level** (the default: view=MEMBER, write=EDITOR, delete=MODERATOR)
|
|
613
|
+
* - a **row rule**: a predicate that sees the caller and the row
|
|
614
|
+
*
|
|
615
|
+
* Row rules exist because role levels cannot express "only the author may edit
|
|
616
|
+
* this". They run inside the transaction, next to the write they gate, so the
|
|
617
|
+
* row they judge is the row being changed.
|
|
618
|
+
*
|
|
619
|
+
* `view` accepts two rule forms. A function rule is evaluated per fetched row,
|
|
620
|
+
* so it can express anything but cannot use an index: the executor scans to
|
|
621
|
+
* fill a page, bounded by a cap. A `where` rule returns a query filter for the
|
|
622
|
+
* caller, which is compiled into the SQL of every level that reads the
|
|
623
|
+
* namespace, so it uses indexes and never short-fills a page.
|
|
624
|
+
*/
|
|
625
|
+
|
|
626
|
+
type PermissionAction = "view" | "create" | "update" | "delete";
|
|
627
|
+
/** The caller, as far as a rule is concerned. */
|
|
628
|
+
interface PermissionAuth {
|
|
629
|
+
sub: string;
|
|
630
|
+
role: WorkspaceRole;
|
|
631
|
+
workspaceId: string;
|
|
632
|
+
}
|
|
633
|
+
/**
|
|
634
|
+
* What a rule receives.
|
|
635
|
+
*
|
|
636
|
+
* `data` is the stored row for update, delete and link operations, with API
|
|
637
|
+
* attribute names. `next` is the incoming values for create and update.
|
|
638
|
+
*/
|
|
639
|
+
interface PermissionContext {
|
|
640
|
+
auth: PermissionAuth;
|
|
641
|
+
data?: Record<string, unknown>;
|
|
642
|
+
next?: Record<string, unknown>;
|
|
643
|
+
/**
|
|
644
|
+
* API attribute names this op writes. Lets a rule gate one field: "only the
|
|
645
|
+
* owner may change `price`" is
|
|
646
|
+
* `changed.includes("price") ? data.ownerId === auth.sub : true`.
|
|
647
|
+
*/
|
|
648
|
+
changed?: string[];
|
|
649
|
+
}
|
|
650
|
+
/** A rule returns true to allow. Throw or return false to deny. */
|
|
651
|
+
type PermissionRule = (context: PermissionContext) => boolean;
|
|
652
|
+
/**
|
|
653
|
+
* A `view` rule SQL can evaluate: the rows the caller may see, as a `where`
|
|
654
|
+
* filter. An array is OR of its branches, so "mine or public" is
|
|
655
|
+
* `[{ ownerId: auth.sub }, { isPublic: true }]`. An empty array hides
|
|
656
|
+
* everything. Only valid for `view`.
|
|
657
|
+
*/
|
|
658
|
+
interface ViewWhereRule {
|
|
659
|
+
where: (auth: PermissionAuth) => QueryWhere | readonly QueryWhere[];
|
|
660
|
+
}
|
|
661
|
+
type PermissionDecision = WorkspaceRole | PermissionRule | ViewWhereRule;
|
|
662
|
+
type PermissionOverrides = Record<string, Partial<Record<PermissionAction, PermissionDecision>>>;
|
|
663
|
+
interface PermissionConfig {
|
|
664
|
+
overrides?: PermissionOverrides;
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
/**
|
|
668
|
+
* One schema, two artifacts.
|
|
669
|
+
*
|
|
670
|
+
* `defineSchema()` is the single source of truth. It produces:
|
|
671
|
+
*
|
|
672
|
+
* - the server registry (namespaces + links) that the engine compiles
|
|
673
|
+
* queries and validates transactions against,
|
|
674
|
+
* - the SQL migrations that create those tables,
|
|
675
|
+
* - the client schema that resolves link labels.
|
|
676
|
+
*
|
|
677
|
+
* A deployment writes the entity map once; the CLI emits the migration bundle
|
|
678
|
+
* from the same object, so the two can never drift.
|
|
679
|
+
*/
|
|
680
|
+
|
|
681
|
+
interface TapeDBSchema {
|
|
682
|
+
registry: RegistryDefinition;
|
|
683
|
+
permissions: PermissionConfig;
|
|
684
|
+
migrations: BundledWorkspaceMigration[];
|
|
685
|
+
clientSchema: SchemaDefinition;
|
|
686
|
+
/** Who may read, write and delete each file; absent means the role defaults. */
|
|
687
|
+
files?: FileRules;
|
|
688
|
+
}
|
|
689
|
+
|
|
690
|
+
export { WORKSPACE_ROLE_LEVELS as W, hasRoleLevel as c, hasRole as h };
|
|
691
|
+
export type { BundledWorkspaceMigration as B, DataClient as D, InitConfig as I, OutboxEntry as O, PresencePeer as P, QueryError as Q, RoleClaim as R, StorageObject as S, TopicSender as T, WorkspaceRole as a, WriteRejection as b, StorageFetch as d, TransactInput as e, TxOp as f, QueryDocument as g, QueryResult as i, QueryPageInfo as j, QueryState as k, TopicListener as l, TapeDBSchema as m };
|