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

main
ts 1,017 lines 36.4 KB
Raw
1 import * as Context from "effect/Context";
2 import * as DateTime from "effect/DateTime";
3 import * as Duration from "effect/Duration";
4 import * as Effect from "effect/Effect";
5 import * as Exit from "effect/Exit";
6 import * as Layer from "effect/Layer";
7 import * as Option from "effect/Option";
8 import * as Schedule from "effect/Schedule";
9 import * as Stream from "effect/Stream";
10 import { WorkflowEngine } from "effect/workflow";
11 import * as Aggregate from "./Aggregate.ts";
12 import * as CatchUp from "./CatchUp.ts";
13 import type * as Command from "./Command.ts";
14 import {
15 DefinitionError,
16 ForeignAppend,
17 LazyViewNeedsOneSource,
18 MissingWorkflowEngine,
19 } from "./DefinitionError.ts";
20 import { matches } from "./Filter.ts";
21 import * as Kernel from "./Kernel.ts";
22 import type * as Key from "./Key.ts";
23 import {
24 type Accepted,
25 type AggregateStore,
26 type Delivery,
27 type ModelHost,
28 Platform,
29 type PolicyStore,
30 type ProjectionStore,
31 type StreamEntry,
32 type StreamMeta,
33 type StreamStore,
34 type ViewSnapshot,
35 type ViewStore,
36 } from "./Platform.ts";
37 import type * as Policy from "./Policy.ts";
38 import * as Projection from "./Projection.ts";
39 import * as RequestContext from "./RequestContext.ts";
40 import * as Saga from "./Saga.ts";
41 import type * as DomainStream from "./Stream.ts";
42 import * as Telemetry from "./Telemetry.ts";
43 import * as View from "./View.ts";
44 import * as Watch from "./Watch.ts";
45
46 type Identifier<T> = T extends Context.Key<infer I, unknown> ? I : never;
47
48 /**
49 * Low-level access to a built Model's kernel and stores (story runner,
50 * diagnostics).
51 *
52 * @internal
53 */
54 export class Internals extends Context.Service<
55 Internals,
56 {
57 readonly kernel: Kernel.Kernel;
58 readonly aggregates: ReadonlyMap<string, AggregateStore>;
59 readonly views: ReadonlyMap<string, ViewStore>;
60 readonly streams: ReadonlyMap<string, StreamStore>;
61 /** The client of the aggregate that handles each command, by command tag. */
62 readonly commands: ReadonlyMap<string, Aggregate.ClientImpl>;
63 /** Each view's read API, by view name. */
64 readonly viewHosts: ReadonlyMap<string, View.Host<unknown, Key.Any, unknown>>;
65 /** Each stream's API, by stream name. */
66 readonly streamHosts: ReadonlyMap<string, DomainStream.Host<Key.Any, unknown>>;
67 }
68 >()("alchemy/Domain/ModelInternals") {}
69
70 /**
71 * The entities that make up a Model.
72 */
73 export interface Members<
74 A extends ReadonlyArray<Aggregate.Any>,
75 V extends ReadonlyArray<View.Any>,
76 P extends ReadonlyArray<Policy.Any>,
77 J extends ReadonlyArray<Projection.Any>,
78 S extends ReadonlyArray<DomainStream.Any>,
79 G extends ReadonlyArray<Saga.Any> = readonly [],
80 > {
81 readonly aggregates: A;
82 readonly views?: V;
83 readonly policies?: P;
84 readonly projections?: J;
85 readonly streams?: S;
86 readonly sagas?: G;
87 }
88
89 /**
90 * The class type returned by {@link make}.
91 *
92 * `Provided` is every aggregate, view, stream and projection-progress service
93 * the Model provides; `Policies` is every policy and projection whose
94 * implementation `layer` requires.
95 */
96 export interface ModelClass<
97 Name extends string,
98 Provided,
99 Policies,
100 Parts extends Servable = Servable,
101 > {
102 new (_: never): {};
103 readonly kind: "Model";
104 readonly modelName: Name;
105 /** The model's aggregates, in order. */
106 readonly aggregates: Parts["aggregates"];
107 /** Every command of the model's aggregates, each once. */
108 readonly commands: Parts["commands"];
109 /** The model's views, in order. */
110 readonly views: Parts["views"];
111 /** The model's streams, in order. */
112 readonly streams: Parts["streams"];
113 readonly definitions: Kernel.Definitions;
114 /**
115 * Host every entity on the ambient {@link Platform}. The policy and
116 * projection Layers (`handlers`) are built after the aggregates, views and
117 * streams exist, so a handler can resolve them while it is constructed.
118 * `options` tune how it's hosted, such as what it records in traces.
119 */
120 layer<E = never, R = never>(
121 handlers: Layer.Layer<Policies, E, R>,
122 options?: LayerOptions<Parts["views"][number]["viewName"]>,
123 ): Layer.Layer<Provided | Internals, E, Platform | Exclude<R, Provided>>;
124 }
125
126 /**
127 * Structural constraint satisfied by every Model class.
128 */
129 export interface Any extends Servable {
130 readonly kind: "Model";
131 readonly modelName: string;
132 readonly definitions: Kernel.Definitions;
133 }
134
135 /**
136 * What an Api over a model may serve, in the order the model lists them:
137 * its aggregates, their commands, its views and its streams. An Api names
138 * what it serves from these.
139 */
140 export interface Servable {
141 readonly aggregates: ReadonlyArray<Aggregate.Any>;
142 /** Every command of the model's aggregates, each once. */
143 readonly commands: ReadonlyArray<Command.Any>;
144 readonly views: ReadonlyArray<View.Any>;
145 readonly streams: ReadonlyArray<DomainStream.Any>;
146 }
147
148 /** What a model's members serve. */
149 export interface ServableBy<
150 A extends ReadonlyArray<Aggregate.Any>,
151 V extends ReadonlyArray<View.Any>,
152 S extends ReadonlyArray<DomainStream.Any>,
153 > {
154 readonly aggregates: A;
155 readonly commands: ReadonlyArray<A[number]["definition"]["commands"][number]>;
156 readonly views: V;
157 readonly streams: S;
158 }
159
160 type ProvidedBy<
161 A extends ReadonlyArray<Aggregate.Any>,
162 V extends ReadonlyArray<View.Any>,
163 J extends ReadonlyArray<Projection.Any>,
164 S extends ReadonlyArray<DomainStream.Any>,
165 G extends ReadonlyArray<Saga.Any>,
166 > =
167 | Identifier<A[number]>
168 | Identifier<V[number]>
169 | Identifier<S[number]>
170 | Saga.Identifier<G[number]>
171 | Projection.ProgressIdentifier<J[number]>;
172
173 /** How a model's `layer` hosts it: tuning that doesn't change what the model means. */
174 export interface LayerOptions<Views extends string = string> {
175 /** What the hosted model records in traces. See {@link Telemetry.Options}. */
176 readonly telemetry?: Telemetry.Options;
177 /**
178 * Before Domain version 0, models in one Worker that listed the same
179 * aggregate, view or saga shared its Durable Object class, and so its data.
180 * Each model now has classes of its own, and the first deploy moves the
181 * shared class to one of them. Set this on the model that keeps that data;
182 * the others start empty. The deploy fails until exactly one model sets it.
183 *
184 * @default false
185 */
186 readonly legacyData?: boolean;
187 /**
188 * Views that fill lazily when they are added. A deploy that adds one waits
189 * for nothing: each key reads its history the first time it is read (or when
190 * its source next changes). Only for a view that reads one aggregate and is
191 * keyed by it, so each key's history is its own instance's events. (Such a
192 * view is always rebuilt this way when its `version` is bumped.)
193 */
194 readonly lazy?: ReadonlyArray<Views>;
195 }
196
197 /** Every implementation a model's `layer` requires: its policies, projections and sagas. */
198 type HandledBy<
199 P extends ReadonlyArray<Policy.Any>,
200 J extends ReadonlyArray<Projection.Any>,
201 G extends ReadonlyArray<Saga.Any>,
202 > = Identifier<P[number]> | Identifier<J[number]> | Saga.ImplementationIdentifier<G[number]>;
203
204 /**
205 * The aggregates, views and policies you host together. `layer(policies)`
206 * builds them all on the Platform you provide, and provides each aggregate
207 * and view as a service.
208 *
209 * ### Declaring and hosting a model
210 * **Example:** In memory, with its policies and external systems
211 * ```typescript
212 * import * as Domain from "@alchemy.run/domain";
213 * import * as Layer from "effect/Layer";
214 * import { Account } from "./Account.ts";
215 * import { AccountSummary } from "./AccountSummary.ts";
216 * import { Customer } from "./Customer.ts";
217 * import { MainAccountProvisioning, MainAccountProvisioningLive } from "./MainAccountProvisioning.ts";
218 *
219 * export class Bank extends Domain.Model("Bank", {
220 * aggregates: [Account, Customer],
221 * views: [AccountSummary],
222 * policies: [MainAccountProvisioning],
223 * }) {}
224 *
225 * export const BankInMemory = Bank.layer(MainAccountProvisioningLive).pipe(
226 * Layer.provide(Domain.InMemory),
227 * );
228 * ```
229 *
230 * @primitive
231 */
232 export const make = <
233 const Name extends string,
234 const A extends ReadonlyArray<Aggregate.Any>,
235 const V extends ReadonlyArray<View.Any> = readonly [],
236 const P extends ReadonlyArray<Policy.Any> = readonly [],
237 const J extends ReadonlyArray<Projection.Any> = readonly [],
238 const S extends ReadonlyArray<DomainStream.Any> = readonly [],
239 const G extends ReadonlyArray<Saga.Any> = readonly [],
240 >(
241 name: Name,
242 members: Members<A, V, P, J, S, G>,
243 ): ModelClass<Name, ProvidedBy<A, V, J, S, G>, HandledBy<P, J, G>, ServableBy<A, V, S>> => {
244 const definitions: Kernel.Definitions = {
245 aggregates: members.aggregates,
246 views: members.views ?? [],
247 policies: members.policies ?? [],
248 projections: members.projections ?? [],
249 streams: members.streams ?? [],
250 };
251 return class {
252 static readonly kind = "Model" as const;
253 static readonly modelName: Name = name;
254 static readonly definitions: Kernel.Definitions = definitions;
255 static readonly sagas: ReadonlyArray<Saga.Any> = members.sagas ?? [];
256 static readonly aggregates = definitions.aggregates;
257 static readonly commands = [
258 ...new Set(definitions.aggregates.flatMap((aggregate) => aggregate.definition.commands)),
259 ];
260 static readonly views = definitions.views;
261 static readonly streams = definitions.streams;
262 static layer<E, R>(handlers: Layer.Layer<HandledBy<P, J, G>, E, R>, options?: LayerOptions) {
263 return Layer.effectContext(
264 build(
265 name,
266 definitions,
267 handlers,
268 members.sagas ?? [],
269 Telemetry.resolve(options?.telemetry),
270 options?.legacyData ?? false,
271 options?.lazy ?? [],
272 ),
273 );
274 }
275 } as unknown as ModelClass<
276 Name,
277 ProvidedBy<A, V, J, S, G>,
278 HandledBy<P, J, G>,
279 ServableBy<A, V, S>
280 >;
281 };
282
283 /**
284 * Check a Model's definitions without hosting it: every problem that would
285 * otherwise fail its Layer's build, such as a view consuming a source keyed
286 * by another aggregate without `keyOf`, a view with `state` but no
287 * `initial`, a policy listening for an event no source emits, or a stream
288 * with two writers. Returns all of them, in definition order; an empty
289 * array means the Model is valid. Problems that depend on what a handler
290 * returns, such as `decide` returning an event its command does not
291 * declare, still surface when the handler runs.
292 *
293 * **Example:** A unit test for the whole Model
294 * ```typescript
295 * import * as Domain from "@alchemy.run/domain";
296 * import { expect, it } from "vitest";
297 * import { Bank } from "./Bank.model.ts";
298 *
299 * it("the model is well defined", () => {
300 * expect(Domain.verify(Bank)).toEqual([]);
301 * });
302 * ```
303 */
304 export const verify = (model: Any): ReadonlyArray<Kernel.DefinitionError> =>
305 Kernel.verify(model.definitions);
306
307 /**
308 * Trace one projection batch. A batch merges events from many commits, so it
309 * starts its own trace and links to each event's.
310 */
311 const observeProjection =
312 (name: string, key: string, batch: ReadonlyArray<Accepted>) =>
313 <A, E, R>(effect: Effect.Effect<A, E, R>) => {
314 const tags = { "domain.kind": "projection", "domain.consumer": name };
315 const links = batch.flatMap(({ delivery }) =>
316 delivery.envelope.trace
317 ? [{ span: Telemetry.spanOf(delivery.envelope.trace), attributes: {} }]
318 : [],
319 );
320 const correlations = [
321 ...new Set(
322 batch.map(({ delivery }) => delivery.envelope.correlationId ?? delivery.envelope.commandId),
323 ),
324 ];
325 return effect.pipe(
326 Effect.onExit((exit) =>
327 Effect.gen(function* () {
328 const now = yield* Effect.sync(() => Date.now());
329 for (const { delivery } of batch) {
330 yield* Telemetry.record(Telemetry.lag, tags, now - delivery.envelope.at);
331 }
332 yield* Telemetry.record(Telemetry.batchSize, { "domain.consumer": name }, batch.length);
333 yield* Telemetry.record(Telemetry.runs, {
334 ...tags,
335 "domain.outcome": Exit.isSuccess(exit) ? "ok" : "failed",
336 });
337 }),
338 ),
339 Effect.withSpan(`Domain.projection ${name}`, {
340 kind: "consumer",
341 root: true,
342 links,
343 attributes: {
344 "domain.projection": name,
345 "domain.key": key,
346 "domain.batch": batch.length,
347 ...(correlations.length === 1 ? { "domain.correlation_id": correlations[0] } : {}),
348 },
349 }),
350 );
351 };
352
353 const build = <A, E, R>(
354 modelName: string,
355 definitions: Kernel.Definitions,
356 policies: Layer.Layer<A, E, R>,
357 sagas: ReadonlyArray<Saga.Any>,
358 telemetry: Telemetry.Resolved,
359 legacyData: boolean,
360 lazy: ReadonlyArray<string>,
361 ) =>
362 Effect.gen(function* () {
363 // The model's own storage: models sharing a definition never share its data.
364 const platform = yield* (yield* Platform).model({
365 modelName,
366 id: definitions,
367 sagas: sagas.map((saga) => saga.workflow._tag),
368 legacyData,
369 });
370 const kernel = yield* Kernel.make(definitions, telemetry);
371
372 const aggregateStores = new Map<string, AggregateStore>();
373 const viewStores = new Map<string, ViewStore>();
374 const policyStores = new Map<string, PolicyStore>();
375 const projectionStores = new Map<string, ProjectionStore>();
376 const streamStores = new Map<string, StreamStore>();
377
378 const deliver = (delivery: Delivery): Effect.Effect<void> =>
379 Effect.suspend(() => {
380 const { kind, name } = delivery.target;
381 if (kind === "view") return viewStores.get(name)!.receive(delivery.key, [delivery]);
382 const store = kind === "policy" ? policyStores.get(name) : projectionStores.get(name);
383 return store
384 ? store.receive(delivery)
385 : Effect.die(new Error(`${kind} ${name} is not hosted yet`));
386 });
387
388 for (const aggregate of definitions.aggregates) {
389 aggregateStores.set(
390 aggregate.aggregateName,
391 // Assigned, not spread: a kit's `targets` is read when used, once versions are set.
392 yield* platform.aggregate(
393 aggregate,
394 Object.assign(kernel.aggregateKit(aggregate, deliver), {
395 push: Watch.aggregatePush(kernel, aggregate),
396 }),
397 ),
398 );
399 }
400 const viewTarget = (name: string) => kernel.targetIdOf("view", name);
401 for (const name of lazy) {
402 if (!kernel.inPlace("view", name))
403 return yield* Effect.die(
404 new DefinitionError({ reason: new LazyViewNeedsOneSource({ view: name }) }),
405 );
406 }
407 // A view keyed by the one aggregate it reads fills each key itself, from its
408 // instance's events, before the key answers: when it is lazy, and when its
409 // version was bumped (it is rebuilt in place). The deploy runs no backfill for it.
410 const selfFilled = new Set(
411 definitions.views
412 .filter(
413 (view) =>
414 kernel.inPlace("view", view.viewName) &&
415 (lazy.includes(view.viewName) || kernel.generationOf("view", view.viewName) > 0),
416 )
417 .map((view) => view.viewName),
418 );
419 for (const view of definitions.views) {
420 // Only a view that fills itself reads its keys' history on first touch; any
421 // other view is filled by the deploy's backfill, and its keys apply live.
422 const source = selfFilled.has(view.viewName)
423 ? kernel.sourcesOf(viewTarget(view.viewName))?.[0]
424 : undefined;
425 viewStores.set(
426 view.viewName,
427 yield* platform.view(
428 view,
429 Object.assign(kernel.viewKit(view, deliver), {
430 push: Watch.viewPush(kernel, view),
431 ...(source === undefined ? {} : { catchUp: { source } }),
432 }),
433 ),
434 );
435 }
436
437 for (const stream of definitions.streams) {
438 streamStores.set(
439 stream.streamName,
440 yield* platform.stream(stream, {
441 name: stream.streamName,
442 push: Watch.streamPush(kernel, stream),
443 }),
444 );
445 }
446
447 let hosts = Context.empty() as Context.Context<unknown>;
448 const commands = new Map<string, Aggregate.ClientImpl>();
449 for (const aggregate of definitions.aggregates) {
450 const client = aggregateClient(
451 kernel,
452 aggregate,
453 aggregateStores.get(aggregate.aggregateName)!,
454 );
455 hosts = Context.add(hosts, aggregate, client);
456 for (const command of aggregate.definition.commands) commands.set(command.tag, client);
457 }
458 const viewHosts = new Map<string, View.Host<unknown, Key.Any, unknown>>();
459 for (const view of definitions.views) {
460 const host = viewHost(
461 kernel,
462 view,
463 viewStores.get(view.viewName)!,
464 // Such a key reads its history before it answers: every answer has it all.
465 selfFilled.has(view.viewName)
466 ? Effect.succeed({ complete: true })
467 : history(platform, () => viewTarget(view.viewName)),
468 );
469 viewHosts.set(view.viewName, host);
470 hosts = Context.add(hosts, view, host);
471 }
472 const streamHosts = new Map<string, DomainStream.Host<Key.Any, unknown>>();
473 for (const stream of definitions.streams) {
474 const host = streamHost(kernel, stream, streamStores.get(stream.streamName)!);
475 streamHosts.set(stream.streamName, host);
476 hosts = Context.add(hosts, stream, host);
477 }
478 for (const projection of definitions.projections) {
479 hosts = Context.add(
480 hosts,
481 projection.Progress,
482 projectionProgress(
483 kernel,
484 projection,
485 () => projectionStores.get(projection.projectionName)!,
486 history(platform, () =>
487 CatchUp.targetId({
488 kind: "projection",
489 name: projection.projectionName,
490 generation: kernel.generationOf("projection", projection.projectionName),
491 }),
492 ),
493 ),
494 );
495 }
496
497 // Sagas run on the platform's workflow engine.
498 if (sagas.length > 0) {
499 const engine = yield* Effect.serviceOption(WorkflowEngine.WorkflowEngine);
500 if (Option.isNone(engine)) {
501 return yield* Effect.die(
502 new DefinitionError({
503 reason: new MissingWorkflowEngine({ sagas: sagas.map((saga) => saga.sagaName) }),
504 }),
505 );
506 }
507 // The model's own runs: its sagas register and start under `<model>/<saga>`.
508 const modelEngine = Saga.engineFor(engine.value, modelName);
509 hosts = Context.add(hosts, WorkflowEngine.WorkflowEngine, modelEngine);
510 for (const saga of sagas) hosts = Context.add(hosts, saga, Saga.client(saga, modelEngine));
511 }
512
513 // Policies, projections and sagas are built with the clients available, then hosted.
514 const implementations = yield* Layer.build(policies).pipe(Effect.provide(hosts));
515 const implementationOf = (projection: Projection.Any) =>
516 Context.getUnsafe(
517 implementations as Context.Context<unknown>,
518 projection as Context.Key<unknown, Projection.Implementation<unknown>>,
519 );
520 for (const projection of definitions.projections) {
521 const version = implementationOf(projection).options.version;
522 if (version) kernel.setVersion(`projection:${projection.projectionName}`, version);
523 }
524 for (const projection of definitions.projections) {
525 const implementation = implementationOf(projection);
526 const writes = (projection.definition.writes ?? []).map((stream) =>
527 streamStores.get(stream.streamName)!,
528 );
529 projectionStores.set(
530 projection.projectionName,
531 yield* platform.projection(projection, {
532 name: projection.projectionName,
533 options: { batch: Projection.batchMillis(implementation.options) },
534 generation: kernel.generationOf("projection", projection.projectionName),
535 singleSource: kernel.singleSource(`projection:${projection.projectionName}`),
536 history: kernel.history,
537 run: (key, batch) =>
538 Effect.gen(function* () {
539 // Platforms run handlers inside their runtime (a Durable Object, or this process).
540 const inputs = yield* kernel.projectionInputs(projection, key, batch);
541 // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- the platform runs handlers inside its runtime, which provides RuntimeContext
542 yield* implementation.handle(inputs) as Effect.Effect<void>;
543 // What this run handled, so stream reads `atLeast` a receipt see it.
544 if (writes.length === 0) return;
545 const checkpoints: Record<string, number> = {};
546 for (const { delivery } of batch) {
547 checkpoints[delivery.source] = Math.max(
548 checkpoints[delivery.source] ?? 0,
549 delivery.seq,
550 );
551 }
552 yield* Effect.forEach(writes, (store) => store.advance(key, checkpoints), {
553 discard: true,
554 });
555 }).pipe(observeProjection(projection.projectionName, key, batch)),
556 }),
557 );
558 }
559 for (const policy of definitions.policies) {
560 const handler = Context.getUnsafe(
561 implementations as Context.Context<unknown>,
562 policy as Context.Key<unknown, Policy.Handler<unknown>>,
563 );
564 policyStores.set(
565 policy.policyName,
566 yield* platform.policy(policy, kernel.policyKit(policy, handler)),
567 );
568 }
569 // Every store is built: catch up the consumers that are new to the platform.
570 // Lazy views have no backfill: their keys catch up when read.
571 const lazyTargets = new Set([...selfFilled].map(viewTarget));
572 // Every consumer is in the model, so its sources route to it; those that fill
573 // themselves get no backfill.
574 if (platform.start)
575 yield* platform.start(
576 kernel.targets,
577 kernel.planOf,
578 kernel.targets.filter((target) => !lazyTargets.has(target)),
579 );
580
581 return Context.add(hosts, Internals, {
582 kernel,
583 aggregates: aggregateStores,
584 views: viewStores,
585 streams: streamStores,
586 commands,
587 viewHosts,
588 streamHosts,
589 });
590 });
591
592 const aggregateClient = (
593 kernel: Kernel.Kernel,
594 aggregate: Aggregate.Any,
595 store: AggregateStore,
596 ): Aggregate.ClientImpl => {
597 /** What a send carries besides the command: its id, context, flow and trace. */
598 const metaFor = (
599 target: unknown,
600 command: { readonly _tag: string },
601 options: Aggregate.SendOptions | undefined,
602 link: boolean,
603 ) =>
604 Effect.gen(function* () {
605 const commandId = yield* Aggregate.commandIdFor(options);
606 const context = yield* RequestContext.capture;
607 const correlationId = yield* Telemetry.correlationFor(commandId);
608 yield* Effect.annotateCurrentSpan({
609 "domain.command_id": commandId,
610 "domain.correlation_id": correlationId,
611 ...Telemetry.attributesOf(command.constructor, command),
612 });
613 const trace = yield* Telemetry.currentTrace;
614 return {
615 id: Aggregate.targetId(target),
616 meta: {
617 commandId,
618 context,
619 correlationId,
620 ...(trace ? { trace } : {}),
621 ...(link ? { link } : {}),
622 },
623 };
624 });
625 const spanOptions = (target: unknown) => ({
626 kind: "client" as const,
627 attributes: {
628 "domain.aggregate": aggregate.aggregateName,
629 "domain.id": Aggregate.targetId(target),
630 },
631 });
632 return {
633 send: (target, command, options) =>
634 Effect.gen(function* () {
635 // The span records a rejection as an outcome; the caller still fails with it.
636 const result = yield* Effect.gen(function* () {
637 const { id, meta } = yield* metaFor(target, command, options, false);
638 const encoded = yield* kernel.encodeCommand(aggregate, command);
639 const result = yield* store.send(id, encoded, meta);
640 yield* Effect.annotateCurrentSpan(
641 "domain.outcome",
642 result._tag === "Accepted"
643 ? "accepted"
644 : ((result.rejection as { readonly _tag?: string })._tag ?? "rejected"),
645 );
646 return result;
647 }).pipe(
648 Effect.withSpan(
649 `Domain.send ${aggregate.aggregateName}.${command._tag}`,
650 spanOptions(target),
651 ),
652 );
653 return result._tag === "Rejected"
654 ? yield* Effect.fail(kernel.decodeRejection(aggregate, result.rejection))
655 : yield* kernel.decodeReceipt(aggregate, command._tag, result.receipt);
656 }),
657 schedule: (target, command, options) =>
658 Effect.gen(function* () {
659 // The command runs later, so its span links back here rather than continuing this trace.
660 const { id, meta } = yield* metaFor(target, command, options, true);
661 const at = yield* store.schedule(
662 id,
663 yield* kernel.encodeCommand(aggregate, command),
664 meta,
665 options.at !== undefined
666 ? { at: DateTime.toEpochMillis(options.at) }
667 : { afterMillis: Duration.toMillis(Duration.fromInputUnsafe(options.after)) },
668 );
669 return { commandId: meta.commandId, at: DateTime.makeUnsafe(at) };
670 }).pipe(
671 Effect.withSpan(
672 `Domain.schedule ${aggregate.aggregateName}.${command._tag}`,
673 spanOptions(target),
674 ),
675 ),
676 unschedule: (target, commandId) =>
677 store.unschedule(Aggregate.targetId(target), commandId).pipe(
678 Effect.withSpan(`Domain.unschedule ${aggregate.aggregateName}`, {
679 ...spanOptions(target),
680 attributes: { ...spanOptions(target).attributes, "domain.command_id": commandId },
681 }),
682 ),
683 state: (target) =>
684 store
685 .state(Aggregate.targetId(target))
686 .pipe(Effect.map(({ state }) => kernel.decodeState(aggregate, state))),
687 };
688 };
689
690 const decodeSnapshot = (
691 kernel: Kernel.Kernel,
692 view: View.Any,
693 snapshot: ViewSnapshot,
694 ): Option.Option<unknown> =>
695 snapshot.state === null
696 ? Option.none()
697 : Option.some(kernel.decodeViewState(view, snapshot.state));
698
699 const viewHost = (
700 kernel: Kernel.Kernel,
701 view: View.Any,
702 store: ViewStore,
703 history: Effect.Effect<View.History>,
704 ): View.Host<unknown, Key.Any, unknown> => {
705 const watch = (key: Key.RefOf<Key.Any>, options?: View.WatchOptions<unknown>) =>
706 store.changes(Aggregate.targetId(key)).pipe(
707 Stream.map((snapshot) =>
708 Option.filter(decodeSnapshot(kernel, view, snapshot), (state) =>
709 matches(options?.where, state),
710 ),
711 ),
712 Stream.changesWith((a, b) =>
713 Option.isNone(a) && Option.isNone(b)
714 ? true
715 : Option.isSome(a) && Option.isSome(b) && a.value === b.value,
716 ),
717 );
718 const watchEach = <P, E, R>(
719 parent: Stream.Stream<P, E, R>,
720 keysOf: (parent: P) => ReadonlyArray<Key.RefOf<Key.Any>>,
721 options?: View.WatchOptions<unknown>,
722 ): Stream.Stream<readonly [P, ReadonlyArray<readonly [Key.RefOf<Key.Any>, unknown]>], E, R> =>
723 parent.pipe(
724 Stream.switchMap(
725 (p): Stream.Stream<readonly [P, ReadonlyArray<readonly [Key.RefOf<Key.Any>, unknown]>]> => {
726 const keys = keysOf(p);
727 if (keys.length === 0) return Stream.succeed([p, []]);
728 return Stream.zipLatestAll(
729 ...keys.map((key) => watch(key, options).pipe(Stream.map((o) => [key, o] as const))),
730 ).pipe(
731 Stream.map(
732 (pairs) =>
733 [
734 p,
735 pairs.flatMap(([key, state]) =>
736 Option.isSome(state) ? [[key, state.value] as const] : [],
737 ),
738 ] as const,
739 ),
740 );
741 },
742 ),
743 );
744 /** The stored snapshot of a key, once it has applied `atLeast` (if given). */
745 const readAtLeast = (
746 id: string,
747 options?: {
748 readonly atLeast?: { readonly stream: string; readonly version: number };
749 readonly timeout?: Duration.Input;
750 },
751 ) => {
752 const read = store.read(id);
753 const atLeast = options?.atLeast;
754 if (!atLeast) return read;
755 return read.pipe(
756 Effect.flatMap((snapshot) =>
757 (snapshot.checkpoints[atLeast.stream] ?? 0) >= atLeast.version
758 ? Effect.succeed(snapshot)
759 : Effect.fail("stale" as const),
760 ),
761 Effect.retry({
762 schedule: Schedule.spaced("25 millis"),
763 times: Math.ceil(
764 Duration.toMillis(Duration.fromInputUnsafe(options?.timeout ?? "10 seconds")) / 25,
765 ),
766 }),
767 Effect.mapError(() =>
768 View.ConsistencyTimeout.make({
769 view: view.viewName,
770 key: id,
771 stream: atLeast.stream,
772 version: atLeast.version,
773 }),
774 ),
775 );
776 };
777 return {
778 history,
779 query: (key, options) =>
780 readAtLeast(Aggregate.targetId(key), options).pipe(
781 Effect.map((snapshot) => decodeSnapshot(kernel, view, snapshot)),
782 ),
783 // State and seq come from one stored snapshot, so the cursor matches the state.
784 snapshot: (key, options) =>
785 readAtLeast(Aggregate.targetId(key), options).pipe(
786 Effect.map((snapshot) => ({
787 state: Option.getOrNull(decodeSnapshot(kernel, view, snapshot)),
788 cursor: snapshot.seq,
789 })),
790 ),
791 waitFor: (key, where, options) =>
792 watch(key, { where }).pipe(
793 Stream.filter(Option.isSome),
794 Stream.map((state) => state.value),
795 Stream.runHead,
796 Effect.timeoutOption(options.timeout),
797 Effect.flatMap((result) =>
798 Option.isSome(result) && Option.isSome(result.value)
799 ? Effect.succeed(result.value.value)
800 : Effect.fail(
801 new View.WaitTimeout({ view: view.viewName, key: Aggregate.targetId(key) }),
802 ),
803 ),
804 ),
805 watch,
806 watchEach,
807 events: (key, options) =>
808 store.tail(Aggregate.targetId(key), options?.after ?? 0).pipe(
809 Stream.mapEffect((entry) => kernel.decodeViewEntry(view, entry)),
810 Stream.filter((entry) => matches(options?.where, entry.event)),
811 ),
812 list: (key, options) =>
813 store.list(Aggregate.targetId(key)).pipe(
814 Effect.flatMap((stored) => {
815 const desc = options?.order === "desc";
816 const after = options?.after;
817 return Effect.forEach(
818 (desc ? [...stored].reverse() : stored).filter(
819 (row) => after === undefined || (desc ? row.seq < after : row.seq > after),
820 ),
821 (row) =>
822 Effect.map(kernel.decodeViewEntry(view, row), (entry) => ({ seq: row.seq, entry })),
823 );
824 }),
825 Effect.map((decoded) => {
826 const rows = decoded.filter((row) => matches(options?.where, row.entry.event));
827 const take = options?.take ?? rows.length;
828 const page = rows.slice(0, take);
829 return {
830 entries: page.map((row) => row.entry),
831 cursor: rows.length > take && page.length > 0 ? page[page.length - 1]!.seq : null,
832 };
833 }),
834 ),
835 };
836 };
837
838 /** Wait until a progress check passes, retrying every 25ms up to `timeout`. */
839 const waitUntil = <A>(
840 check: Effect.Effect<A, "stale">,
841 timeout: Duration.Input | undefined,
842 onTimeout: () => View.ConsistencyTimeout,
843 ) =>
844 check.pipe(
845 Effect.retry({
846 schedule: Schedule.spaced("25 millis"),
847 times: Math.ceil(Duration.toMillis(Duration.fromInputUnsafe(timeout ?? "10 seconds")) / 25),
848 }),
849 Effect.mapError(onTimeout),
850 );
851
852 const streamHost = (
853 kernel: Kernel.Kernel,
854 stream: DomainStream.Any,
855 store: StreamStore,
856 ): DomainStream.Host<Key.Any, unknown> => {
857 const decode = (entry: StreamEntry) => kernel.decodeStreamEntry(entry);
858 const latest = (key: string, meta: StreamMeta) =>
859 meta.seq === 0
860 ? Effect.succeedNone
861 : store.tail(key, meta.seq - 1).pipe(
862 Stream.take(1),
863 Stream.runHead,
864 Effect.flatMap(
865 Option.match({
866 onNone: () => Effect.succeedNone,
867 onSome: (entry) => Effect.asSome(decode(entry)),
868 }),
869 ),
870 );
871 return {
872 peek: (key, options) => {
873 const atLeast = options?.atLeast;
874 const read = atLeast
875 ? waitUntil(
876 store
877 .read(Aggregate.targetId(key))
878 .pipe(
879 Effect.flatMap((meta) =>
880 (meta.checkpoints[atLeast.stream] ?? 0) >= atLeast.version
881 ? Effect.succeed(meta)
882 : Effect.fail("stale" as const),
883 ),
884 ),
885 options?.timeout,
886 () =>
887 View.ConsistencyTimeout.make({
888 view: stream.streamName,
889 key: Aggregate.targetId(key),
890 stream: atLeast.stream,
891 version: atLeast.version,
892 }),
893 )
894 : store.read(Aggregate.targetId(key));
895 return read.pipe(Effect.flatMap((meta) => latest(Aggregate.targetId(key), meta)));
896 },
897 watch: (key) =>
898 store.changes(Aggregate.targetId(key)).pipe(
899 Stream.changesWith((a, b) => a.seq === b.seq),
900 Stream.mapEffect((meta) => latest(Aggregate.targetId(key), meta)),
901 ),
902 events: (key, options) =>
903 store.tail(Aggregate.targetId(key), options?.after ?? 0).pipe(
904 Stream.mapEffect(decode),
905 Stream.filter((entry) => matches(options?.where, entry.event)),
906 ),
907 list: (key, options) =>
908 store.list(Aggregate.targetId(key)).pipe(
909 Effect.flatMap((stored) => {
910 const desc = options?.order === "desc";
911 const after = options?.after;
912 return Effect.forEach(
913 (desc ? [...stored].reverse() : stored).filter(
914 (row) => after === undefined || (desc ? row.seq < after : row.seq > after),
915 ),
916 (row) => Effect.map(decode(row), (entry) => ({ seq: row.seq, entry })),
917 );
918 }),
919 Effect.map((decoded) => {
920 const rows = decoded.filter((row) => matches(options?.where, row.entry.event));
921 const take = options?.take ?? rows.length;
922 const page = rows.slice(0, take);
923 return {
924 entries: page.map((row) => row.entry),
925 cursor: rows.length > take && page.length > 0 ? page[page.length - 1]!.seq : null,
926 };
927 }),
928 ),
929 append: (origin, ...events) =>
930 Effect.suspend(() => {
931 const meta = (origin as unknown as Record<symbol, Kernel.InputMetaValue | undefined>)[
932 Kernel.InputMeta
933 ];
934 const writer = kernel.writerOf(stream);
935 if (!meta || !writer || writer.projectionName !== meta.projection) {
936 return Effect.die(
937 new DefinitionError({ reason: new ForeignAppend({ stream: stream.streamName }) }),
938 );
939 }
940 meta.appends += 1;
941 const position: [number, number] = [meta.position, meta.appends];
942 return Effect.forEach(events, (event) =>
943 kernel.encodeEvent(event as { readonly _tag: string }),
944 ).pipe(
945 Effect.flatMap((encoded) =>
946 store.append(meta.key, {
947 origin: position,
948 source: meta.source,
949 sourceSeq: meta.sourceSeq,
950 at: meta.at,
951 commandId: meta.commandId,
952 events: encoded,
953 }),
954 ),
955 );
956 }),
957 };
958 };
959
960 /** How much history has reached a consumer, as the platform reports it. */
961 const history = (platform: ModelHost, target: () => string): Effect.Effect<View.History> =>
962 Effect.suspend(() =>
963 platform.history
964 ? Effect.map(platform.history(target()), ({ complete }) => ({ complete }))
965 : Effect.succeed({ complete: true }),
966 );
967
968 const projectionProgress = (
969 kernel: Kernel.Kernel,
970 projection: Projection.Any,
971 store: () => ProjectionStore,
972 history: Effect.Effect<View.History>,
973 ): Projection.Progress => ({
974 history,
975 caughtUp: (receipt, options) =>
976 Effect.gen(function* () {
977 const [aggregate, ...rest] = receipt.stream.split("/");
978 const id = rest.join("/");
979 const first = receipt.version - receipt.events.length + 1;
980 const waits = new Map<string, number>();
981 receipt.events.forEach((event, index) => {
982 for (const key of kernel.projectionKeys(
983 projection,
984 aggregate!,
985 id,
986 event as { readonly _tag: string },
987 first + index,
988 )) {
989 waits.set(key, Math.max(waits.get(key) ?? 0, first + index));
990 }
991 });
992 yield* Effect.forEach(
993 waits,
994 ([key, seq]) =>
995 waitUntil(
996 store()
997 .checkpoints(key)
998 .pipe(
999 Effect.flatMap((checkpoints) =>
1000 (checkpoints[receipt.stream] ?? 0) >= seq
1001 ? Effect.void
1002 : Effect.fail("stale" as const),
1003 ),
1004 ),
1005 options?.timeout,
1006 () =>
1007 View.ConsistencyTimeout.make({
1008 view: projection.projectionName,
1009 key,
1010 stream: receipt.stream,
1011 version: seq,
1012 }),
1013 ),
1014 { discard: true },
1015 );
1016 }),
1017 });