@bridgebrew/storage 0.0.0-stage → 0.0.1

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/facets.ts ADDED
@@ -0,0 +1,263 @@
1
+ // Facet domains (AD-24): data a plugin attaches to another plugin's objects (or to nodes, `bridge/node`), stored by
2
+ // the adding plugin keyed by the target's id, with no node of its own: its node is its target's, computed on read.
3
+ // Reads are async, served by the storage backend, and return copies. Each write carries its audit meta (research-011
4
+ // D3): `set` names the fields of the value it stores, `delete` none.
5
+ import type { Context } from 'cordis';
6
+ import type { Filter, Store } from '@bridge/storage';
7
+ import {
8
+ coded,
9
+ fieldsOf,
10
+ queries,
11
+ serialWrites,
12
+ validated,
13
+ type CountOptions,
14
+ type Include,
15
+ type Nodes,
16
+ type ObjectsSpec,
17
+ type Page,
18
+ type PageOptions,
19
+ type Queries,
20
+ type QueryOptions,
21
+ type Related,
22
+ type WatchFilter,
23
+ type WatchMessage,
24
+ watchLimits,
25
+ } from './objects.ts';
26
+
27
+ /** A stored facet: its target's id, its value, and its revision (1 at its first set, one more at each; 0 for one
28
+ * stored before revisions). Nothing is kept of a deleted facet: set again, its revisions start over at 1, so a write
29
+ * at an old one could land on the new facet. A facet edited live (@bridge/records' facetRoutes) is emptied instead. */
30
+ export interface StoredFacet<T> {
31
+ target: string;
32
+ value: T;
33
+ rev?: number;
34
+ }
35
+
36
+ export interface FacetsSpec<T> extends Omit<ObjectsSpec<T>, 'indexes' | 'search' | 'rules'> {
37
+ /** The object domain id `<plugin key>/<name>` the facets attach to, or `bridge/node`. */
38
+ target: string;
39
+ }
40
+
41
+ /** Writes take the caller's context and refuse one of another plugin (`not_owner`); `set` refuses a target that does
42
+ * not exist (`target_unknown`, status 400; also when its object domain is not declared in this worker), a new facet on
43
+ * a target whose node this plugin is not active on (`plugin_inactive`, status 403, AD-25), a value
44
+ * failing its schema (`invalid_value`, status 400), and a
45
+ * reference to a missing object or node (`reference_unknown`, status 400); `delete` an absent facet (`not_found`, 404).
46
+ * `rev` on either: refused with `409 conflict` (its `details.current` the stored facet, none when absent) unless the
47
+ * facet is still at that revision (0: absent). */
48
+ export interface FacetDomain<T> {
49
+ set(
50
+ caller: Context,
51
+ targetId: string,
52
+ value: T,
53
+ options?: { rev?: number },
54
+ ): Promise<StoredFacet<T>>;
55
+ delete(caller: Context, targetId: string, options?: { rev?: number }): Promise<void>;
56
+ get(targetId: string): Promise<T | undefined>;
57
+ /** The facet with its revision (`rev` 0 for one stored before revisions). */
58
+ find(targetId: string): Promise<StoredFacet<T> | undefined>;
59
+ /** Facets visible as their target is (`node`, `include` and `archived` apply to the target's node; a facet whose
60
+ * target is archived or under an archived node is hidden unless `archived`; one whose target is missing is never
61
+ * returned), as `ObjectDomain.query` reads objects: `where` on the value, through references, and on `target`
62
+ * (`{ is: Where }` on the target object, or operators on the target id), `orderBy` on the value then the target
63
+ * id, `with` (`target: true`, reference fields, `_count`; no `facets`). */
64
+ query(options: Omit<QueryOptions, 'search'>): Promise<(StoredFacet<T> & Related)[]>;
65
+ page(options: Omit<PageOptions, 'search'>): Promise<Page<StoredFacet<T> & Related>>;
66
+ count(options: Omit<CountOptions, 'search'>): Promise<number>;
67
+ /** `fn` runs after each durable change; `value` is `undefined` for a deletion. */
68
+ subscribe(fn: (targetId: string, value: T | undefined) => void): () => void;
69
+ /** As `ObjectDomain.watch`: `{ ready: true }` once watching, then per window the targets whose facet changed on
70
+ * the nodes the filter reaches (`changed`, or `purged` for a deletion), or `{ all: true }` past `watchLimits.ids`. */
71
+ watch(filter: WatchFilter, signal?: AbortSignal): AsyncIterable<WatchMessage>;
72
+ release(): void;
73
+ }
74
+
75
+ /** The facet facade over a hub store of `{ target, value }` records keyed by target id. Each durable write emits
76
+ * `<id>/set` `{ target, node, value }` (no `value` for a private domain) or `<id>/deleted` `{ target, node }` through
77
+ * `emit` (AD-25), `node` the target's. */
78
+ export function facetDomain<T>(
79
+ store: Store<StoredFacet<T>>,
80
+ key: string,
81
+ id: string,
82
+ links: {
83
+ /** Whether the target `targetId` exists now. */
84
+ exists(targetId: string): Promise<boolean>;
85
+ /** Rejects with `plugin_inactive` when this plugin is not active on the target's node. */
86
+ active(targetId: string): Promise<void>;
87
+ check(value: unknown): Promise<void>;
88
+ /** The target's node; `undefined` when unknown (its domain not declared, or the target gone). */
89
+ node(targetId: string): Promise<string | undefined>;
90
+ emit<P extends { node: string }>(event: string, payload: P): void;
91
+ /** The backend filter of the facets whose target is on `nodes` (and live, unless `archived`). */
92
+ scope(nodes: string[], archived: boolean): Filter;
93
+ /** Declared `private`: events carry no value. */
94
+ private?: boolean;
95
+ /** The actor of the running code (`plugin` without). */
96
+ actor?: () => string;
97
+ } & Queries,
98
+ nodes: Nodes,
99
+ release: () => void,
100
+ ): FacetDomain<T> {
101
+ const write = serialWrites(key, id, links.actor);
102
+ const revOf = (facet: StoredFacet<T> | undefined) => (facet ? (facet.rev ?? 0) : 0);
103
+ /** Refuses a write at `rev` once the facet moved on from it. */
104
+ const checkRev = (
105
+ facet: StoredFacet<T> | undefined,
106
+ rev: number | undefined,
107
+ targetId: string,
108
+ ) => {
109
+ if (rev === undefined) return;
110
+ if (!Number.isInteger(rev) || rev < 0)
111
+ throw coded(
112
+ `${id}: rev must be a whole number, got ${JSON.stringify(rev)}`,
113
+ 'invalid_rev',
114
+ 400,
115
+ );
116
+ if (rev !== revOf(facet))
117
+ throw Object.assign(
118
+ coded(
119
+ `${id}: the facet on ${targetId} changed since revision ${rev} (now ${revOf(facet)})`,
120
+ 'conflict',
121
+ 409,
122
+ ),
123
+ { details: { current: facet && { ...facet, rev: revOf(facet) } } },
124
+ );
125
+ };
126
+ /** The nodes a watch's filter reaches, as reads judge them. */
127
+ const reach = (node: string, include: Include) =>
128
+ include === 'self'
129
+ ? [node]
130
+ : include === 'inherited'
131
+ ? (nodes.ancestors(node) ?? []).map((each) => each.id)
132
+ : nodes
133
+ .list()
134
+ .filter((each) => nodes.ancestors(each.id)?.some((above) => above.id === node))
135
+ .map((each) => each.id);
136
+ const { page, count } = queries(nodes, id, store, (facet) => facet.target, links.scope, links);
137
+ const shown = (facets: StoredFacet<T>[], extras: Related[] | undefined) =>
138
+ facets.map((facet, i) => ({ ...facet, ...extras?.[i] }));
139
+ /** An event about a target of no known node reaches no one: not emitted. */
140
+ const emit = async (action: string, target: string, value?: T, rev?: number) => {
141
+ const node = await links.node(target);
142
+ if (node !== undefined)
143
+ links.emit(`${id}/${action}`, {
144
+ target,
145
+ node,
146
+ ...(value !== undefined && !links.private && { value }),
147
+ ...(rev !== undefined && { rev }),
148
+ });
149
+ };
150
+ return {
151
+ set: (caller, targetId, value, options) =>
152
+ write('set', caller, async (author) => {
153
+ if (typeof targetId !== 'string' || !(await links.exists(targetId)))
154
+ throw coded(`${id}: no target ${String(targetId)}`, 'target_unknown', 400);
155
+ const before = await store.get(targetId);
156
+ checkRev(before, options?.rev, targetId);
157
+ // A new facet only: an existing one may be overwritten where inactive, as an object may be updated (AD-25).
158
+ if (!before) await links.active(targetId);
159
+ await links.check(value);
160
+ const next = { target: targetId, value, rev: revOf(before) + 1 };
161
+ await validated(id, () =>
162
+ store.set(targetId, next, { op: 'set', fields: fieldsOf(value), ...author }),
163
+ );
164
+ // Gone already when a purge of the target ran in between: the write stands, no event.
165
+ const stored = await store.get(targetId);
166
+ if (stored) await emit('set', targetId, stored.value, revOf(stored));
167
+ return structuredClone(stored ? { ...stored, rev: revOf(stored) } : next);
168
+ }),
169
+ delete: (caller, targetId, options) =>
170
+ write('delete', caller, async (author) => {
171
+ const before = typeof targetId === 'string' ? await store.get(targetId) : undefined;
172
+ if (!before) throw coded(`${id}: no facet on ${String(targetId)}`, 'not_found', 404);
173
+ checkRev(before, options?.rev, targetId);
174
+ await store.delete(targetId, { op: 'delete', fields: null, ...author });
175
+ await emit('deleted', targetId);
176
+ }),
177
+ get: async (targetId) => (await store.get(targetId))?.value,
178
+ find: async (targetId) => {
179
+ const facet = await store.get(targetId);
180
+ return facet && structuredClone({ ...facet, rev: revOf(facet) });
181
+ },
182
+ query: async (options) => {
183
+ const { cursor: _, ...rest } = options as PageOptions;
184
+ const { items, extras } = await page('query', rest);
185
+ return shown(items, extras);
186
+ },
187
+ page: async (options) => {
188
+ const { items, extras, next } = await page('page', options);
189
+ return { items: shown(items, extras), ...(next !== undefined && { next }) };
190
+ },
191
+ count,
192
+ subscribe: (fn) => store.subscribe((targetId, facet) => fn(targetId, facet?.value)),
193
+ watch: ({ node, include = 'inherited' }, signal) => {
194
+ if (typeof node !== 'string' || !nodes.has(node))
195
+ throw coded(`${id}.watch: no node ${JSON.stringify(node)}`, 'invalid_query', 400);
196
+ if (!['self', 'inherited', 'subtree'].includes(include))
197
+ throw coded(
198
+ `${id}.watch: include must be self, inherited, or subtree`,
199
+ 'invalid_query',
200
+ 400,
201
+ );
202
+ return {
203
+ [Symbol.asyncIterator]: () => {
204
+ // ponytail: each watcher subscribes on its own (no hub as objects have); one if watchers grow many.
205
+ const queue: WatchMessage[] = [{ ready: true }];
206
+ const window = new Map<string, 'changed' | 'purged'>();
207
+ let timer: ReturnType<typeof setTimeout> | undefined;
208
+ let wake: (() => void) | undefined;
209
+ let done = false;
210
+ const flush = () => {
211
+ timer = undefined;
212
+ if (done || window.size === 0) return;
213
+ queue.push(
214
+ window.size > watchLimits.ids
215
+ ? { all: true }
216
+ : { ids: [...window].map(([target, action]) => ({ id: target, action })) },
217
+ );
218
+ window.clear();
219
+ wake?.();
220
+ };
221
+ const unsubscribe = store.subscribe((target, facet) => {
222
+ void links.node(target).then((at) => {
223
+ if (done) return;
224
+ // A deletion whose target is gone (a purge takes its facets with it) is told everyone: its node is no
225
+ // longer known, and an id alone says nothing of its value.
226
+ if (at === undefined ? facet !== undefined : !reach(node, include).includes(at))
227
+ return;
228
+ // A deletion stays told when the facet is set again in the window: its revisions started over.
229
+ window.set(target, facet && window.get(target) !== 'purged' ? 'changed' : 'purged');
230
+ timer ??= setTimeout(flush, watchLimits.windowMs);
231
+ });
232
+ });
233
+ const end = () => {
234
+ if (done) return;
235
+ done = true;
236
+ unsubscribe();
237
+ clearTimeout(timer);
238
+ wake?.();
239
+ };
240
+ signal?.addEventListener('abort', end, { once: true });
241
+ return {
242
+ next: async (): Promise<IteratorResult<WatchMessage>> => {
243
+ while (!done && queue.length === 0)
244
+ await new Promise<void>((resolve) => {
245
+ wake = resolve;
246
+ });
247
+ wake = undefined;
248
+ const message = queue.shift();
249
+ return message && !done
250
+ ? { value: message, done: false }
251
+ : { value: undefined, done: true };
252
+ },
253
+ return: async () => {
254
+ end();
255
+ return { value: undefined, done: true };
256
+ },
257
+ };
258
+ },
259
+ };
260
+ },
261
+ release,
262
+ };
263
+ }
package/inventory.ts ADDED
@@ -0,0 +1,47 @@
1
+ // What `GET /<slug>/api/storage/inventory` answers: how this workspace's storage is made, metadata only, never a value
2
+ // (the Storage screen reads it; agents too). Types only, so the browser imports them without the server.
3
+
4
+ /** How a domain holds its data: objects on nodes, facets on another domain's objects (or nodes), a log of events, a plain
5
+ * domain held in memory, or a shared domain (`shared/<name>`, any workspace's through `hostStorage`). */
6
+ export type DomainKind = 'objects' | 'facets' | 'log' | 'plain' | 'shared';
7
+
8
+ /** One declared domain of the workspace's worker. */
9
+ export interface DomainInventory {
10
+ /** `<plugin key>/<name>`. */
11
+ id: string;
12
+ /** The declaring plugin's key (`shared` for shared domains). */
13
+ plugin: string;
14
+ name: string;
15
+ kind: DomainKind;
16
+ version: number;
17
+ /** Read by its owner only (research-011 D6). */
18
+ private: boolean;
19
+ /** Object domains: who writes it (research-052 D3). */
20
+ writers?: 'owner' | 'workspace';
21
+ /** Object domains: the rules it declares (research-052 D1), by name, in their order. */
22
+ rules?: string[];
23
+ /** Facet domains: the object domain (or `bridge/node`) its facets attach to. */
24
+ target?: string;
25
+ /** Its reference fields and the domain each points to, by field. */
26
+ references: { field: string; domain: string }[];
27
+ /** The reference fields of declared domains pointing here, a facet domain's `target` among them. */
28
+ referencedBy: { domain: string; field: string }[];
29
+ /** Object domains: the paths of `value` the backend indexes for ordering. */
30
+ indexes?: string[];
31
+ /** Object domains: the paths of `value` a search reads, and whether a trigram index serves it. */
32
+ search?: { paths: string[]; trigram: boolean };
33
+ /** What it holds, when the backend counts it: objects (`archived`: of them, archived), facets, keys of a plain or
34
+ * shared domain. None for a log, or when the count failed. */
35
+ count?: { total: number; archived?: number };
36
+ }
37
+
38
+ export interface Inventory {
39
+ backend: {
40
+ /** The plugin providing `storageBackend` (storage-sqlite, storage-postgres, storage-json…), when known. */
41
+ plugin?: string;
42
+ /** What its files take on disk now (`Backend.sizes`), one entry per file or folder; none for a database server. */
43
+ sizes?: { file: string; bytes: number }[];
44
+ };
45
+ /** Sorted by id. */
46
+ domains: DomainInventory[];
47
+ }