The best way to control Claude Code, Codex and more from any computer or phone

main
ts 1,180 lines 47.3 KB
Raw
1 import * as Effect from "effect/Effect";
2 import * as Layer from "effect/Layer";
3 import * as Semaphore from "effect/Semaphore";
4 import * as Stream from "effect/Stream";
5 import * as SubscriptionRef from "effect/SubscriptionRef";
6 import { WorkflowEngine } from "effect/workflow";
7 import type * as Aggregate from "./Aggregate.ts";
8 import { AlreadyCancelled, AlreadyExecuted, NotScheduled } from "./Aggregate.ts";
9 import * as Backfill from "./Backfill.ts";
10 import { type Routed, targetId } from "./CatchUp.ts";
11 import * as InMemoryWorkflows from "./InMemoryWorkflows.ts";
12 import {
13 type Accepted,
14 type Delivery,
15 emptySnapshot,
16 emptyStreamMeta,
17 hostedModels,
18 Platform,
19 type Json,
20 type ModelHost,
21 type SendResult,
22 type StoredEvent,
23 type StreamEntry,
24 type StreamMeta,
25 type ViewEntry,
26 type ViewSnapshot,
27 } from "./Platform.ts";
28
29 /**
30 * Options for {@link make}.
31 */
32 export interface Options {
33 /**
34 * When `true`, deliveries queue until {@link Control.drain} is called and
35 * policy runs are tracked so a caller can wait for quiescence. Used by the
36 * story runner. Defaults to `false` (deliver in the background).
37 */
38 readonly manual?: boolean;
39 /** Clock used to time-stamp commands. Defaults to `Date.now`. */
40 readonly now?: () => number;
41 }
42
43 /**
44 * Control surface of an in-memory platform.
45 */
46 export interface Control {
47 /**
48 * Send due scheduled commands, then deliver every queued delivery (and
49 * those it produces) until the queue is empty.
50 */
51 readonly drain: Effect.Effect<void>;
52 /** `true` when nothing is queued and every running policy is suspended. */
53 readonly idle: Effect.Effect<boolean>;
54 /** Mark the current policy run as suspended while `effect` runs (story external systems). */
55 readonly suspended: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
56 /** Defects raised by policy and projection runs. */
57 readonly failures: ReadonlyArray<unknown>;
58 /** Saga runs that ended with a defect, in the order they died. */
59 readonly deaths: ReadonlyArray<{
60 readonly saga: string;
61 readonly executionId: string;
62 readonly defect: unknown;
63 }>;
64 /**
65 * Every event a command committed (seeded events excluded), in commit
66 * order: its aggregate, instance id, and position in the instance's
67 * events, from 0.
68 */
69 readonly commits: ReadonlyArray<{
70 readonly aggregate: string;
71 readonly id: string;
72 readonly index: number;
73 }>;
74 }
75
76 /** A scheduled command: when it is due, and how to send it. */
77 interface Timer {
78 readonly at: number;
79 readonly fire: Effect.Effect<void>;
80 }
81
82 /** A function that builds each value once per argument. */
83 const memo = <A>(make: (key: string) => A) => {
84 const made = new Map<string, A>();
85 return (key: string): A => {
86 let found = made.get(key);
87 if (found === undefined) made.set(key, (found = make(key)));
88 return found;
89 };
90 };
91
92 /**
93 * Build an in-memory platform and its control surface.
94 */
95 export const make = (
96 options: Options = {},
97 ): {
98 readonly layer: Layer.Layer<Platform | WorkflowEngine.WorkflowEngine>;
99 readonly control: Control;
100 } => {
101 const now = options.now ?? (() => Date.now());
102 // Deliveries and saga runs, in the order they were queued.
103 const pending: Array<Effect.Effect<void>> = [];
104 let draining = false;
105 let running = 0;
106 let suspended = 0;
107 const failures: Array<unknown> = [];
108 const deaths: Array<{ saga: string; executionId: string; defect: unknown }> = [];
109 const commits: Array<{ aggregate: string; id: string; index: number }> = [];
110 // Scheduled commands by `aggregate/id/commandId`, so rescheduling replaces.
111 const timers = new Map<string, Timer>();
112 /** Fire every timer that is due on the platform's clock; each removes itself. */
113 const fireDue: Effect.Effect<void> = Effect.suspend(() => {
114 const due = [...timers.values()].filter((timer) => timer.at <= now());
115 return Effect.forEach(due, (timer) => timer.fire, { discard: true });
116 });
117
118 const deliverAll: Effect.Effect<void> = Effect.suspend(function loop(): Effect.Effect<void> {
119 const next = pending.shift();
120 if (!next) {
121 draining = false;
122 return Effect.void;
123 }
124 draining = true;
125 return next.pipe(Effect.flatMap(loop));
126 });
127
128 const drain: Effect.Effect<void> = fireDue.pipe(Effect.andThen(deliverAll));
129
130 const enqueueWork = (work: ReadonlyArray<Effect.Effect<void>>) =>
131 Effect.suspend(() => {
132 pending.push(...work);
133 if (options.manual || draining || pending.length === 0) return Effect.void;
134 draining = true;
135 return Effect.forkDetach(drain).pipe(Effect.asVoid);
136 });
137
138 const enqueue = (
139 deliveries: ReadonlyArray<Delivery>,
140 deliver: (d: Delivery) => Effect.Effect<void>,
141 ) => enqueueWork(deliveries.map((delivery) => deliver(delivery)));
142
143 /**
144 * Fire `fire` at `at` while it is still the timer under `key` (not
145 * cancelled, replaced or already fired): from `drain` as a story's clock
146 * moves, otherwise in real time. `exclusive` wraps the check and the fire,
147 * so a caller holding the same lock sees one or the other.
148 */
149 const timer = (
150 key: string,
151 at: number,
152 fire: Effect.Effect<void>,
153 exclusive: (effect: Effect.Effect<void>) => Effect.Effect<void> = (effect) => effect,
154 ) =>
155 Effect.suspend(() => {
156 const armed: Timer = {
157 at,
158 fire: exclusive(
159 Effect.suspend(() => {
160 if (timers.get(key) !== armed) return Effect.void;
161 timers.delete(key);
162 return fire;
163 }),
164 ),
165 };
166 timers.set(key, armed);
167 if (options.manual) return Effect.void;
168 return Effect.forkDetach(
169 Effect.sleep(Math.max(0, at - now())).pipe(Effect.andThen(fireDue)),
170 ).pipe(Effect.asVoid);
171 });
172
173 const workflows = InMemoryWorkflows.make({
174 now,
175 // A run is forked like a policy run, so one waiting on an external system
176 // doesn't hold up the queue.
177 enqueue: (run) =>
178 enqueueWork([
179 Effect.suspend(() => {
180 running++;
181 return Effect.forkDetach(run.pipe(Effect.ensuring(Effect.sync(() => running--)))).pipe(
182 Effect.asVoid,
183 );
184 }),
185 ]),
186 timer,
187 failed: (cause) => void failures.push(cause),
188 died: (saga, executionId, defect) => void deaths.push({ saga, executionId, defect }),
189 });
190
191 const control: Control = {
192 drain,
193 idle: Effect.sync(() => pending.length === 0 && !draining && running === suspended),
194 suspended: (effect) =>
195 Effect.suspend(() => {
196 suspended++;
197 return effect.pipe(Effect.ensuring(Effect.sync(() => suspended--)));
198 }),
199 failures,
200 deaths,
201 commits,
202 };
203
204 // Each model has its own storage and catch-up state, kept when the same
205 // model is built again on this platform (a redeploy): models never share data.
206 const hostFor = memo((modelName: string): ModelHost => {
207 // Storage by entity, kept when a model is built again on this platform (a redeploy).
208 const storage = new Map<string, unknown>();
209 const stored = <T>(key: string, make: () => T): T => {
210 if (!storage.has(key)) storage.set(key, make());
211 return storage.get(key) as T;
212 };
213 // ---------------------------------------------------------------- backfill
214 // Every source instance, consumer key and directory node is an object with its
215 // own storage, kept across builds (deploys); its jobs run on the work queue.
216 const memoryStorage = (address: string, lock: Semaphore.Semaphore): Backfill.Storage => {
217 const data = stored(`bf:${address}`, () => new Map<string, unknown>());
218 return {
219 get: <A>(key: string) => Effect.sync(() => data.get(key) as A | undefined),
220 put: (entries) =>
221 Effect.sync(() => {
222 for (const [key, value] of Object.entries(entries)) data.set(key, value);
223 }),
224 delete: (keys) =>
225 Effect.sync(() => {
226 for (const key of keys) data.delete(key);
227 }),
228 list: <A>(options: { prefix: string; startAfter?: string; limit?: number }) =>
229 Effect.sync(() => {
230 const out: Array<readonly [string, A]> = [];
231 for (const key of [...data.keys()].sort()) {
232 if (!key.startsWith(options.prefix)) continue;
233 if (options.startAfter !== undefined && key <= options.startAfter) continue;
234 out.push([key, data.get(key) as A]);
235 if (options.limit !== undefined && out.length >= options.limit) break;
236 }
237 return out;
238 }),
239 exclusive: (effect) => lock.withPermits(1)(effect),
240 };
241 };
242 // Queued jobs, by object and id: scheduling one already queued is a no-op.
243 const scheduled = new Set<string>();
244 const memoryJobs = (
245 address: string,
246 run: (id: string) => Effect.Effect<void>,
247 ): Backfill.Jobs => ({
248 schedule: (id, afterMillis) =>
249 Effect.suspend(() => {
250 const key = `${address}|${id}`;
251 // A job that waits (on code that doesn't know a target yet) waits on the clock.
252 if (afterMillis > 0)
253 return timer(
254 `bf|${key}`,
255 now() + afterMillis,
256 run(id).pipe(Effect.catchCause((cause) => Effect.sync(() => failures.push(cause)))),
257 );
258 if (scheduled.has(key)) return Effect.void;
259 scheduled.add(key);
260 return enqueueWork([
261 Effect.suspend(() => {
262 scheduled.delete(key);
263 return run(id).pipe(
264 Effect.catchCause((cause) => Effect.sync(() => failures.push(cause))),
265 );
266 }),
267 ]);
268 }),
269 });
270 const nodes = new Map<string, Backfill.Node>();
271 const node = (path: string): Backfill.Node => {
272 let found = nodes.get(path);
273 if (!found) {
274 const address = `node:${path}`;
275 const lock = stored(`lock:${address}`, () => Semaphore.makeUnsafe(1));
276 found = Backfill.makeNode(
277 memoryStorage(address, lock),
278 memoryJobs(address, (id) => node(path).run(id)),
279 net,
280 limits,
281 );
282 nodes.set(path, found);
283 }
284 return found;
285 };
286 // Every consumer in the model of the latest build, and the tuning: keys waiting on
287 // discovery ask again on the work queue, as soon as other work has run.
288 let model: ReadonlyArray<string> = [];
289 let planOf: (target: string) => Backfill.Plan | undefined = () => undefined;
290 const limits: Backfill.Limits = { ...Backfill.defaultLimits, pollMillis: 0 };
291 // The source and consumer parts of each hosted entity, as of the latest build.
292 const sourceRoles = new Map<string, (id: string) => Backfill.Source>();
293 const consumerRoles = new Map<string, (key: string) => Backfill.Consumer>();
294 const consumerRole = (target: string, key: string) => {
295 const { kind, name } = Backfill.consumerOf(target);
296 return consumerRoles.get(`${kind}:${name}`)?.(key);
297 };
298 /** Each consumer's routing of a source's stored rows, as of the latest build: what its scanners use. */
299 const consumerRoutes = new Map<string, Backfill.ScannerHost["route"]>();
300 const scanners = new Map<string, Backfill.Scanner>();
301 /** The scanner of one source instance, for one consumer generation. */
302 const scanner = (target: string, ref: Backfill.SourceRef) => {
303 const address = `scanner:${target}/${ref.source}/${ref.id}`;
304 let found = scanners.get(address);
305 if (!found) {
306 const lock = stored(`lock:${address}`, () => Semaphore.makeUnsafe(1));
307 const { kind, name } = Backfill.consumerOf(target);
308 const role: Backfill.Scanner = Backfill.makeScanner(
309 memoryStorage(address, lock),
310 memoryJobs(address, (id) => role.run(id)),
311 net,
312 {
313 route: (target, ref, rows) =>
314 consumerRoutes.get(`${kind}:${name}`)?.(target, ref, rows) ?? Effect.succeed([]),
315 },
316 limits,
317 );
318 scanners.set(address, (found = role));
319 }
320 return found;
321 };
322 const runs = new Map<string, Backfill.Run>();
323 /** The root of a consumer generation's run. Each pass is one try at everything; keys work between. */
324 const run = (target: string) => {
325 let found = runs.get(target);
326 if (!found) {
327 const address = `run:${target}`;
328 const lock = stored(`lock:${address}`, () => Semaphore.makeUnsafe(1));
329 const role: Backfill.Run = Backfill.makeRun(
330 memoryStorage(address, lock),
331 memoryJobs(address, (id) => role.run(id)),
332 net,
333 { waitMillis: 0, againMillis: 0 },
334 );
335 runs.set(target, (found = role));
336 }
337 return found;
338 };
339 const net: Backfill.Network = {
340 node: {
341 register: (path, ref) => node(path).register(path, ref),
342 child: (path, child) => node(path).child(path, child),
343 list: (path, after) => node(path).list(path, after),
344 },
345 source: {
346 // A source no longer in the model has nothing to give.
347 cursor: (ref, target) =>
348 Effect.suspend(
349 () => sourceRoles.get(ref.source)?.(ref.id).cursor(target) ?? Effect.succeed(0),
350 ),
351 read: (ref, target, key, after, limit) =>
352 Effect.suspend(
353 () =>
354 sourceRoles.get(ref.source)?.(ref.id).read(target, key, after, limit) ??
355 Effect.succeed({ from: after, rows: [], handoff: "live" as const }),
356 ),
357 log: (ref, after, limit) =>
358 Effect.suspend(
359 () => sourceRoles.get(ref.source)?.(ref.id).log(after, limit) ?? Effect.succeed([]),
360 ),
361 handoff: (ref, target, key, through) =>
362 Effect.suspend(
363 () =>
364 sourceRoles.get(ref.source)?.(ref.id).handoff(target, key, through) ??
365 Effect.succeed("live" as const),
366 ),
367 },
368 consumer: {
369 push: (target, key, deliveries) =>
370 Effect.suspend(() => consumerRole(target, key)?.push(target, deliveries) ?? Effect.void),
371 ready: (target, key, waitMillis) =>
372 Effect.suspend(
373 () =>
374 consumerRole(target, key)?.ready(target, waitMillis) ??
375 Effect.succeed("settled" as const),
376 ),
377 start: (target, key, ref, waitMillis) =>
378 Effect.suspend(
379 () =>
380 consumerRole(target, key)?.start(target, ref, waitMillis) ??
381 Effect.succeed("settled" as const),
382 ),
383 },
384 scanner: {
385 scan: (target, ref, waitMillis) =>
386 Effect.suspend(() => scanner(target, ref).scan(target, ref, waitMillis)),
387 ready: (target, ref, waitMillis) =>
388 Effect.suspend(() => scanner(target, ref).ready(target, waitMillis)),
389 kick: (target, ref) => Effect.suspend(() => scanner(target, ref).kick(target, ref)),
390 },
391 relay: { run: (name, run, items) => Effect.suspend(() => relay.run(name, run, items)) },
392 run: {
393 begin: (target, plan) => Effect.suspend(() => run(target).begin(target, plan)),
394 phase: (target) => Effect.suspend(() => run(target).phase(target)),
395 progress: (target) => Effect.suspend(() => run(target).progress(target)),
396 },
397 };
398 const relay = Backfill.makeRelay(net);
399 /** List an instance in the directory; its first commit waits for it. */
400 const register = (ref: Backfill.SourceRef) =>
401 node(Backfill.leafOf(ref)).register(Backfill.leafOf(ref), ref);
402 return {
403 aggregate: (_aggregate, kit) =>
404 Effect.sync(() => {
405 const { instances, lock, versions } = stored(`aggregate:${kit.name}`, () => ({
406 instances: new Map<
407 string,
408 {
409 state: Json;
410 version: number;
411 readonly receipts: Map<string, SendResult>;
412 /** Ids cancelled and not scheduled again since. */
413 readonly cancelled: Set<string>;
414 readonly events: Array<StoredEvent>;
415 /** How far its events were routed to each view and projection. */
416 routed: Routed | undefined;
417 }
418 >(),
419 lock: Semaphore.makeUnsafe(1),
420 // The latest version of each instance that anyone watches.
421 versions: new Map<string, SubscriptionRef.SubscriptionRef<number>>(),
422 }));
423 const versionOf = (id: string) =>
424 Effect.suspend(() => {
425 const found = versions.get(id);
426 if (found) return Effect.succeed(found);
427 return SubscriptionRef.make(instance(id).version).pipe(
428 Effect.tap((created) => Effect.sync(() => versions.set(id, created))),
429 );
430 });
431 const announce = (id: string) =>
432 Effect.suspend(() => {
433 const ref = versions.get(id);
434 return ref ? SubscriptionRef.set(ref, instance(id).version) : Effect.void;
435 });
436 const instance = (id: string) => {
437 let found = instances.get(id);
438 if (!found)
439 instances.set(
440 id,
441 (found = {
442 state: null,
443 version: 0,
444 receipts: new Map(),
445 cancelled: new Set(),
446 events: [],
447 routed: undefined,
448 }),
449 );
450 return found;
451 };
452 const sourceRole = memo((id: string) => {
453 const address = `source:${kit.name}/${id}`;
454 const role: Backfill.Source = Backfill.makeSource(
455 memoryStorage(address, lock),
456 memoryJobs(address, () => role.flush),
457 net,
458 {
459 ref: { source: kit.name, id },
460 model: () => model,
461 singleSource: (target) => planOf(target)?.singleSource === true,
462 log: (after, limit) =>
463 Effect.sync(() =>
464 instance(id)
465 .events.filter((event) => event.envelope.seq > after)
466 .slice(0, limit),
467 ),
468 version: Effect.sync(() => instance(id).version),
469 routed: Effect.sync(() => instance(id).routed),
470 markLive: (target) =>
471 Effect.sync(() => {
472 const current = instance(id);
473 current.routed = { ...current.routed, [target]: current.version };
474 }),
475 },
476 limits,
477 );
478 return role;
479 });
480 sourceRoles.set(kit.name, sourceRole);
481 // Callers hold `lock`.
482 const commit = (id: string, command: Json, meta: Aggregate.SendMeta) =>
483 Effect.gen(function* () {
484 const current = instance(id);
485 const duplicate = current.receipts.get(meta.commandId);
486 if (duplicate) return duplicate;
487 const result = yield* kit.handle({
488 id,
489 state: current.state,
490 version: current.version,
491 command,
492 commandId: meta.commandId,
493 context: meta.context,
494 now: now(),
495 correlationId: meta.correlationId,
496 trace: meta.trace,
497 link: meta.link,
498 });
499 if (result._tag === "Rejected") return result satisfies SendResult;
500 if (current.version === 0) yield* register({ source: kit.name, id });
501 const live = yield* Backfill.routeCommit(
502 sourceRole(id),
503 kit.targets,
504 current.routed,
505 current.version,
506 result.version,
507 result.deliveries,
508 );
509 current.routed = live.routed;
510 current.state = result.state;
511 current.version = result.version;
512 for (let i = 0; i < result.events.length; i++)
513 commits.push({ aggregate: kit.name, id, index: current.events.length + i });
514 current.events.push(...result.events);
515 const sent: SendResult = {
516 _tag: "Accepted",
517 receipt: {
518 stream: `${kit.name}/${id}`,
519 version: result.version,
520 events: result.events.map((e) => e.event),
521 reply: result.reply,
522 },
523 };
524 current.receipts.set(meta.commandId, sent);
525 yield* announce(id);
526 yield* enqueue(live.send, kit.deliver);
527 return sent;
528 });
529 const send = (id: string, command: Json, meta: Aggregate.SendMeta) =>
530 lock.withPermits(1)(commit(id, command, meta));
531 const executed = (id: string, commandId: string) => instance(id).receipts.has(commandId);
532 return {
533 send,
534 schedule: (id, command, meta, due) =>
535 lock.withPermits(1)(
536 Effect.suspend(() => {
537 const fields = { aggregate: kit.name, id, commandId: meta.commandId };
538 if (executed(id, meta.commandId)) return Effect.fail(new AlreadyExecuted(fields));
539 instance(id).cancelled.delete(meta.commandId);
540 const at = "at" in due ? due.at : now() + due.afterMillis;
541 return timer(
542 `${modelName}/${kit.name}/${id}/${meta.commandId}`,
543 at,
544 commit(id, command, meta).pipe(Effect.asVoid),
545 lock.withPermits(1),
546 ).pipe(Effect.as(at));
547 }),
548 ),
549 unschedule: (id, commandId) =>
550 lock.withPermits(1)(
551 Effect.suspend(
552 (): Effect.Effect<void, AlreadyExecuted | AlreadyCancelled | NotScheduled> => {
553 const fields = { aggregate: kit.name, id, commandId };
554 if (executed(id, commandId)) return Effect.fail(new AlreadyExecuted(fields));
555 const { cancelled } = instance(id);
556 if (cancelled.has(commandId)) return Effect.fail(new AlreadyCancelled(fields));
557 if (!timers.delete(`${modelName}/${kit.name}/${id}/${commandId}`))
558 return Effect.fail(new NotScheduled(fields));
559 cancelled.add(commandId);
560 return Effect.void;
561 },
562 ),
563 ),
564 state: (id) =>
565 Effect.sync(() => ({ state: instance(id).state, version: instance(id).version })),
566 events: (id) => Effect.sync(() => [...instance(id).events]),
567 changes: (id) =>
568 Stream.unwrap(
569 versionOf(id).pipe(
570 Effect.map((ref) =>
571 SubscriptionRef.changes(ref).pipe(
572 Stream.map(() => ({
573 state: instance(id).state,
574 version: instance(id).version,
575 })),
576 ),
577 ),
578 ),
579 ),
580 tail: (id, after) =>
581 Stream.unwrap(
582 versionOf(id).pipe(
583 Effect.map((ref) => {
584 let last = after;
585 return SubscriptionRef.changes(ref).pipe(
586 Stream.flatMap(() => {
587 const fresh = instance(id).events.filter((e) => e.envelope.seq > last);
588 if (fresh.length > 0) last = fresh[fresh.length - 1]!.envelope.seq;
589 return Stream.fromIterable(fresh);
590 }),
591 );
592 }),
593 ),
594 ),
595 seed: (id, events) =>
596 lock.withPermits(1)(
597 Effect.gen(function* () {
598 const current = instance(id);
599 const result = yield* kit.seed({
600 id,
601 state: current.state,
602 version: current.version,
603 events,
604 commandId: `seed:${id}:${current.version}`,
605 now: now(),
606 });
607 if (current.version === 0) yield* register({ source: kit.name, id });
608 const live = yield* Backfill.routeCommit(
609 sourceRole(id),
610 kit.targets,
611 current.routed,
612 current.version,
613 result.version,
614 result.deliveries,
615 );
616 current.routed = live.routed;
617 current.state = result.state;
618 current.version = result.version;
619 current.events.push(...result.events);
620 yield* announce(id);
621 yield* enqueue(live.send, kit.deliver);
622 }),
623 ),
624 };
625 }),
626
627 view: (_view, kit) =>
628 Effect.sync(() => {
629 const stash = stored(`view:${kit.name}`, () => ({
630 /** The generation the stored keys were built by. */
631 generation: 0,
632 keys: new Map<
633 string,
634 {
635 readonly snapshot: SubscriptionRef.SubscriptionRef<ViewSnapshot>;
636 readonly entries: SubscriptionRef.SubscriptionRef<ReadonlyArray<ViewEntry>>;
637 /** The key's immutable input log: every delivery it applied, in order. */
638 readonly inputs: Array<Delivery>;
639 /** How far its entries were routed to each view and projection. */
640 routed: Routed | undefined;
641 }
642 >(),
643 lock: Semaphore.makeUnsafe(1),
644 }));
645 const { keys, lock } = stash;
646 // Rebuilt (a new generation): start every key over; the history is replayed to it.
647 if (stash.generation < kit.generation) {
648 keys.clear();
649 stash.generation = kit.generation;
650 }
651 const get = (key: string) =>
652 Effect.suspend(() => {
653 const found = keys.get(key);
654 if (found) return Effect.succeed(found);
655 return Effect.all({
656 snapshot: SubscriptionRef.make(emptySnapshot),
657 entries: SubscriptionRef.make<ReadonlyArray<ViewEntry>>([]),
658 }).pipe(
659 Effect.map((created) => ({
660 ...created,
661 inputs: [] as Array<Delivery>,
662 routed: undefined as Routed | undefined,
663 })),
664 Effect.tap((created) => Effect.sync(() => keys.set(key, created))),
665 );
666 });
667 const target = kit.target;
668 /** Apply deliveries to a key and route what it emits. Callers hold `lock`. */
669 const apply = (key: string, deliveries: ReadonlyArray<Delivery>) =>
670 Effect.gen(function* () {
671 const current = yield* get(key);
672 const before = yield* SubscriptionRef.get(current.snapshot);
673 const result = yield* kit.apply(key, before, deliveries);
674 if (!result.changed) return;
675 current.inputs.push(
676 ...deliveries.filter((d) => (before.checkpoints[d.source] ?? 0) < d.seq),
677 );
678 if (result.entries.length > 0) {
679 yield* SubscriptionRef.update(current.entries, (entries) => [
680 ...entries,
681 ...result.entries,
682 ]);
683 }
684 const live = yield* Backfill.routeCommit(
685 sourceRole(key),
686 kit.targets,
687 current.routed,
688 before.seq,
689 result.snapshot.seq,
690 result.downstream,
691 );
692 current.routed = live.routed;
693 yield* SubscriptionRef.set(current.snapshot, result.snapshot);
694 yield* enqueue(live.send, kit.deliver);
695 }).pipe(kit.observe(key, deliveries));
696 // As a consumer: buffers and merges history while a backfill runs.
697 const consumer = memo((key: string) => {
698 const address = `consumer:${target}/${key}`;
699 const role: Backfill.Consumer = Backfill.makeConsumer(
700 memoryStorage(address, lock),
701 memoryJobs(address, (id) => role.merge(id.slice("bf-merge:".length))),
702 net,
703 {
704 key,
705 target: () => target,
706 singleSource: () => kit.singleSource,
707 sources: () => planOf(target)?.sources ?? [],
708 history: (ref, rows) => kit.history(target, ref.source, ref.id, rows),
709 apply: (deliveries) => apply(key, deliveries),
710 },
711 limits,
712 );
713 return role;
714 });
715 consumerRoles.set(`view:${kit.name}`, consumer);
716 consumerRoutes.set(`view:${kit.name}`, (target, ref, rows) =>
717 kit.history(target, ref.source, ref.id, rows),
718 );
719 // As a source: other views and projections read its entries.
720 const sourceRole = memo((key: string) => {
721 const address = `source:${kit.name}/${key}`;
722 const entries = Effect.flatMap(get(key), (current) =>
723 SubscriptionRef.get(current.entries),
724 );
725 const role: Backfill.Source = Backfill.makeSource(
726 memoryStorage(address, lock),
727 memoryJobs(address, () => role.flush),
728 net,
729 {
730 ref: { source: kit.name, id: key },
731 model: () => model,
732 singleSource: (target) => planOf(target)?.singleSource === true,
733 log: (after, limit) =>
734 Effect.map(entries, (all) =>
735 all.filter((entry) => entry.seq > after).slice(0, limit),
736 ),
737 version: Effect.flatMap(get(key), (current) =>
738 Effect.map(SubscriptionRef.get(current.snapshot), (snapshot) => snapshot.seq),
739 ),
740 routed: Effect.map(get(key), (current) => current.routed),
741 markLive: (target) =>
742 Effect.gen(function* () {
743 const current = yield* get(key);
744 const { seq } = yield* SubscriptionRef.get(current.snapshot);
745 current.routed = { ...current.routed, [target]: seq };
746 }),
747 },
748 limits,
749 );
750 return role;
751 });
752 // A key of a view keyed by its one aggregate reads its history from that
753 // instance before it answers anything, the first time: when the view is
754 // lazy, or rebuilt in place. After that, it is read like any other.
755 const caughtUp = new Set<string>();
756 const ready = (key: string): Effect.Effect<void> =>
757 Effect.suspend(() => {
758 const catchUp = kit.catchUp;
759 if (catchUp === undefined || caughtUp.has(key)) return Effect.void;
760 const ref = { source: catchUp.source, id: key };
761 return consumer(key)
762 .start(target, ref, 5_000)
763 .pipe(
764 Effect.repeat({ until: (started) => started === "settled", times: 20 }),
765 Effect.tap((started) =>
766 Effect.sync(() => {
767 if (started === "settled") caughtUp.add(key);
768 }),
769 ),
770 Effect.asVoid,
771 );
772 });
773 // Read as a source (by a view or projection catching up), a key has its
774 // own history first: what reads it never sees a key still filling.
775 sourceRoles.set(kit.name, (key) => {
776 const role = sourceRole(key);
777 const first = ready(key);
778 return {
779 ...role,
780 log: (after, limit) => Effect.andThen(first, role.log(after, limit)),
781 cursor: (target) => Effect.andThen(first, role.cursor(target)),
782 read: (target, at, after, limit) =>
783 Effect.andThen(first, role.read(target, at, after, limit)),
784 handoff: (target, at, through) =>
785 Effect.andThen(first, role.handoff(target, at, through)),
786 };
787 });
788 return {
789 receive: (key, deliveries) =>
790 Effect.gen(function* () {
791 // A key is listed as a source before it first applies anything.
792 if (!keys.has(key)) yield* register({ source: kit.name, id: key });
793 if (yield* consumer(key).admit(target, deliveries))
794 yield* lock.withPermits(1)(apply(key, deliveries));
795 }),
796 read: (key) =>
797 ready(key).pipe(
798 Effect.andThen(get(key)),
799 Effect.flatMap((current) => SubscriptionRef.get(current.snapshot)),
800 ),
801 changes: (key) =>
802 Stream.unwrap(
803 ready(key).pipe(
804 Effect.andThen(get(key)),
805 Effect.map((current) => SubscriptionRef.changes(current.snapshot)),
806 ),
807 ),
808 list: (key) =>
809 ready(key).pipe(
810 Effect.andThen(get(key)),
811 Effect.flatMap((current) => SubscriptionRef.get(current.entries)),
812 ),
813 tail: (key, after) =>
814 Stream.unwrap(
815 ready(key).pipe(
816 Effect.andThen(get(key)),
817 Effect.map((current) => {
818 let last = after;
819 return SubscriptionRef.changes(current.entries).pipe(
820 Stream.flatMap((entries) => {
821 const fresh = entries.filter((entry) => entry.seq > last);
822 if (fresh.length > 0) last = fresh[fresh.length - 1]!.seq;
823 return Stream.fromIterable(fresh);
824 }),
825 );
826 }),
827 ),
828 ),
829 };
830 }),
831
832 projection: (_projection, kit) =>
833 Effect.sync(() => {
834 interface Partition {
835 readonly log: Array<Accepted>;
836 processed: number;
837 readonly intake: Record<string, number>;
838 readonly checkpoints: Record<string, number>;
839 timer: boolean;
840 readonly lock: Semaphore.Semaphore;
841 }
842 const stash = stored(`projection:${kit.name}`, () => ({
843 /** The generation the stored logs were built by. */
844 generation: 0,
845 partitions: new Map<string, Partition>(),
846 }));
847 const { partitions } = stash;
848 // Rebuilt (a new generation): start every key's log over; the history is replayed to it.
849 if (stash.generation < kit.generation) {
850 partitions.clear();
851 stash.generation = kit.generation;
852 }
853 const partition = (key: string) => {
854 let found = partitions.get(key);
855 if (!found) {
856 partitions.set(
857 key,
858 (found = {
859 log: [],
860 processed: 0,
861 intake: {},
862 checkpoints: {},
863 timer: false,
864 lock: Semaphore.makeUnsafe(1),
865 }),
866 );
867 }
868 return found;
869 };
870 const batch = kit.options.batch;
871 /** Handle the key's unprocessed inputs in order, in batches; leave a short batch to fill. */
872 const process = (key: string, flush: boolean): Effect.Effect<void> =>
873 Effect.suspend(() => {
874 const p = partition(key);
875 return p.lock.withPermits(1)(
876 Effect.gen(function* () {
877 while (p.processed < p.log.length) {
878 const pending = p.log.length - p.processed;
879 const size = batch?.size ?? 1;
880 const oldest = p.log[p.processed]!;
881 if (
882 !flush &&
883 !options.manual &&
884 pending < size &&
885 batch &&
886 now() - oldest.at < batch.waitMillis
887 ) {
888 if (!p.timer) {
889 p.timer = true;
890 running++;
891 yield* Effect.forkDetach(
892 Effect.sleep(batch.waitMillis - (now() - oldest.at)).pipe(
893 Effect.andThen(
894 Effect.sync(() => {
895 p.timer = false;
896 }),
897 ),
898 Effect.andThen(process(key, true)),
899 Effect.ensuring(Effect.sync(() => running--)),
900 ),
901 );
902 }
903 return;
904 }
905 const run = p.log.slice(p.processed, p.processed + size);
906 yield* kit.run(key, run);
907 p.processed += run.length;
908 for (const { delivery } of run) {
909 p.checkpoints[delivery.source] = Math.max(
910 p.checkpoints[delivery.source] ?? 0,
911 delivery.seq,
912 );
913 }
914 }
915 }),
916 );
917 });
918 /** Accept a delivery into its key's log (once), then handle the log. */
919 const intake = (delivery: Delivery) =>
920 Effect.suspend(() => {
921 // For an earlier generation of the projection: nothing to run.
922 if ((delivery.target.generation ?? 0) < kit.generation) return Effect.void;
923 const p = partition(delivery.key);
924 if ((p.intake[delivery.source] ?? 0) >= delivery.seq) return Effect.void;
925 p.intake[delivery.source] = delivery.seq;
926 p.log.push({ position: p.log.length + 1, delivery, at: now() });
927 running++;
928 return Effect.forkDetach(
929 process(delivery.key, false).pipe(
930 Effect.catchCause((cause) =>
931 Effect.sync(() => failures.push(cause)).pipe(
932 Effect.andThen(Effect.logError(`projection ${kit.name} failed`, cause)),
933 ),
934 ),
935 Effect.ensuring(Effect.sync(() => running--)),
936 ),
937 ).pipe(Effect.asVoid);
938 });
939 const target = targetId({
940 kind: "projection",
941 name: kit.name,
942 ...(kit.generation > 0 ? { generation: kit.generation } : {}),
943 });
944 // Buffers and merges history while a backfill runs.
945 const consumer = memo((key: string) => {
946 const address = `consumer:${target}/${key}`;
947 const role: Backfill.Consumer = Backfill.makeConsumer(
948 memoryStorage(address, partition(key).lock),
949 memoryJobs(address, (id) => role.merge(id.slice("bf-merge:".length))),
950 net,
951 {
952 key,
953 target: () => target,
954 singleSource: () => kit.singleSource,
955 sources: () => planOf(target)?.sources ?? [],
956 history: (ref, rows) => kit.history(target, ref.source, ref.id, rows),
957 apply: (deliveries) => Effect.forEach(deliveries, intake, { discard: true }),
958 },
959 limits,
960 );
961 return role;
962 });
963 consumerRoles.set(`projection:${kit.name}`, consumer);
964 consumerRoutes.set(`projection:${kit.name}`, (target, ref, rows) =>
965 kit.history(target, ref.source, ref.id, rows),
966 );
967 return {
968 receive: (delivery) =>
969 Effect.gen(function* () {
970 if (yield* consumer(delivery.key).admit(target, [delivery]))
971 yield* intake(delivery);
972 }),
973 checkpoints: (key) => Effect.sync(() => ({ ...partition(key).checkpoints })),
974 };
975 }),
976
977 stream: (_stream, _kit) =>
978 Effect.sync(() => {
979 const { keys, lock } = stored(`stream:${_kit.name}`, () => ({
980 keys: new Map<
981 string,
982 {
983 readonly meta: SubscriptionRef.SubscriptionRef<StreamMeta>;
984 readonly entries: SubscriptionRef.SubscriptionRef<ReadonlyArray<StreamEntry>>;
985 }
986 >(),
987 lock: Semaphore.makeUnsafe(1),
988 }));
989 const get = (key: string) =>
990 Effect.suspend(() => {
991 const found = keys.get(key);
992 if (found) return Effect.succeed(found);
993 return Effect.all({
994 meta: SubscriptionRef.make(emptyStreamMeta),
995 entries: SubscriptionRef.make<ReadonlyArray<StreamEntry>>([]),
996 }).pipe(Effect.tap((created) => Effect.sync(() => keys.set(key, created))));
997 });
998 return {
999 append: (key, write) =>
1000 lock.withPermits(1)(
1001 Effect.gen(function* () {
1002 const current = yield* get(key);
1003 const meta = yield* SubscriptionRef.get(current.meta);
1004 if (!isAfter(write.origin, meta.origin)) return;
1005 const added: Array<StreamEntry> = write.events.map((event, index) => {
1006 const seq = meta.seq + index + 1;
1007 return {
1008 seq,
1009 event,
1010 envelope: {
1011 id: key,
1012 stream: `${_kit.name}/${key}`,
1013 seq,
1014 at: write.at,
1015 commandId: write.commandId,
1016 },
1017 };
1018 });
1019 yield* SubscriptionRef.update(current.entries, (entries) => [
1020 ...entries,
1021 ...added,
1022 ]);
1023 yield* SubscriptionRef.set(current.meta, {
1024 seq: meta.seq + added.length,
1025 origin: write.origin,
1026 checkpoints: {
1027 ...meta.checkpoints,
1028 [write.source]: Math.max(
1029 meta.checkpoints[write.source] ?? 0,
1030 write.sourceSeq,
1031 ),
1032 },
1033 });
1034 }),
1035 ),
1036 advance: (key, checkpoints) =>
1037 lock.withPermits(1)(
1038 Effect.gen(function* () {
1039 const current = yield* get(key);
1040 yield* SubscriptionRef.update(current.meta, (meta) => ({
1041 ...meta,
1042 checkpoints: mergeCheckpoints(meta.checkpoints, checkpoints),
1043 }));
1044 }),
1045 ),
1046 read: (key) =>
1047 get(key).pipe(Effect.flatMap((current) => SubscriptionRef.get(current.meta))),
1048 changes: (key) =>
1049 Stream.unwrap(
1050 get(key).pipe(Effect.map((current) => SubscriptionRef.changes(current.meta))),
1051 ),
1052 list: (key) =>
1053 get(key).pipe(Effect.flatMap((current) => SubscriptionRef.get(current.entries))),
1054 tail: (key, after) =>
1055 Stream.unwrap(
1056 get(key).pipe(
1057 Effect.map((current) => {
1058 let last = after;
1059 return SubscriptionRef.changes(current.entries).pipe(
1060 Stream.flatMap((entries) => {
1061 const fresh = entries.filter((entry) => entry.seq > last);
1062 if (fresh.length > 0) last = fresh[fresh.length - 1]!.seq;
1063 return Stream.fromIterable(fresh);
1064 }),
1065 );
1066 }),
1067 ),
1068 ),
1069 };
1070 }),
1071
1072 policy: (_policy, kit) =>
1073 Effect.sync(() => {
1074 const locks = stored(`policy:${kit.name}`, () => new Map<string, Semaphore.Semaphore>());
1075 const lockFor = (key: string) => {
1076 let found = locks.get(key);
1077 if (!found) locks.set(key, (found = Semaphore.makeUnsafe(1)));
1078 return found;
1079 };
1080 return {
1081 receive: (delivery) =>
1082 Effect.suspend(() => {
1083 running++;
1084 return lockFor(delivery.key)
1085 .withPermits(1)(kit.run(delivery))
1086 .pipe(
1087 Effect.catchCause((cause) =>
1088 Effect.sync(() => failures.push(cause)).pipe(
1089 Effect.andThen(Effect.logError(`policy ${kit.name} failed`, cause)),
1090 ),
1091 ),
1092 Effect.ensuring(Effect.sync(() => running--)),
1093 Effect.forkDetach,
1094 Effect.asVoid,
1095 );
1096 }),
1097 };
1098 }),
1099
1100 // A deploy that adds consumers starts their runs.
1101 start: (targets, plans, backfill) =>
1102 Effect.suspend(() => {
1103 model = targets;
1104 planOf = plans;
1105 return Effect.forEach(
1106 backfill,
1107 (target) => {
1108 const plan = plans(target);
1109 if (plan === undefined) return Effect.void;
1110 // A consumer that reads other sources than its run started with, at the same
1111 // version: building the model fails, saying to bump the version.
1112 return Effect.flatMap(run(target).begin(target, plan), (begun) =>
1113 begun.status === "changed"
1114 ? Effect.die(
1115 new Backfill.PlanChanged({
1116 message: Backfill.planChanged(target, begun.started, plan),
1117 }),
1118 )
1119 : Effect.void,
1120 );
1121 },
1122 { discard: true },
1123 );
1124 }),
1125 history: (target) =>
1126 Effect.map(run(target).phase(target), (phase) => ({ complete: phase === "complete" })),
1127 };
1128 });
1129 const claim = hostedModels({ release: true });
1130 const platform = Platform.of({
1131 model: ({ modelName, id }) => Effect.as(claim(modelName, id), hostFor(modelName)),
1132 });
1133
1134 return {
1135 layer: Layer.mergeAll(
1136 Layer.succeed(Platform, platform),
1137 Layer.succeed(WorkflowEngine.WorkflowEngine, workflows),
1138 ),
1139 control,
1140 };
1141 };
1142
1143 /**
1144 * Host a domain model in the current process: aggregates, views and policies,
1145 * with nothing to deploy. Use it in tests and single-process apps; swap it
1146 * for `DomainCloudflare.layerDurableObjects()` and nothing else changes.
1147 *
1148 * ### Hosting in memory
1149 * **Example:** A model with its policies
1150 * ```typescript
1151 * import * as Domain from "@alchemy.run/domain";
1152 * import * as Layer from "effect/Layer";
1153 * import { Bank, BankPolicies } from "./Bank.ts";
1154 *
1155 * export const BankInMemory = Bank.layer(BankPolicies).pipe(Layer.provide(Domain.InMemory));
1156 * ```
1157 *
1158 * @layer
1159 * @provides Domain.Platform
1160 * @provides WorkflowEngine
1161 */
1162 export const InMemory: Layer.Layer<Platform | WorkflowEngine.WorkflowEngine> = Layer.suspend(
1163 () => make().layer,
1164 );
1165
1166 /** Is a stream write's origin after the last one applied? @internal */
1167 export const isAfter = (
1168 origin: readonly [number, number],
1169 last: readonly [number, number],
1170 ): boolean => origin[0] > last[0] || (origin[0] === last[0] && origin[1] > last[1]);
1171
1172 /** The later of two sets of per-source checkpoints. @internal */
1173 export const mergeCheckpoints = (
1174 a: Readonly<Record<string, number>>,
1175 b: Readonly<Record<string, number>>,
1176 ): Record<string, number> => {
1177 const out: Record<string, number> = { ...a };
1178 for (const [source, seq] of Object.entries(b)) out[source] = Math.max(out[source] ?? 0, seq);
1179 return out;
1180 };