@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 460 lines 16.2 KB
Raw
1 import { makeRun, StorageName } from "alchemy/Workflows";
2 import * as EffectCause from "effect/Cause";
3 import * as Context from "effect/Context";
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 Schema from "effect/Schema";
9 import type * as Scope from "effect/Scope";
10 import { type DurableDeferred, Workflow, WorkflowEngine } from "effect/workflow";
11 import { targetId } from "./Aggregate.ts";
12 import type * as Rejection from "./Rejection.ts";
13 import * as Telemetry from "./Telemetry.ts";
14
15 /** The hidden payload field that carries a run's cause. */
16 const CAUSE = "__cause";
17
18 const RunCause = Schema.Struct({
19 correlationId: Schema.String,
20 trace: Schema.optional(
21 Schema.Struct({ traceId: Schema.String, spanId: Schema.String, sampled: Schema.Boolean }),
22 ),
23 });
24
25 /**
26 * Trace one run (one replay) of a saga. A run can last for days, so each
27 * starts its own trace and links to the span that started the saga; the
28 * correlation id carries the flow, and every command a step sends keeps it.
29 */
30 const observeRun =
31 (name: string, executionId: string, cause: typeof RunCause.Type | undefined) =>
32 <A, E, R>(effect: Effect.Effect<A, E, R>) => {
33 const correlationId = cause?.correlationId ?? executionId;
34 const attributes = {
35 "domain.saga": name,
36 "domain.key": executionId,
37 "domain.correlation_id": correlationId,
38 };
39 return effect.pipe(
40 Effect.provideService(Telemetry.Correlation, { id: correlationId }),
41 Effect.onExit((exit) =>
42 Telemetry.record(Telemetry.runs, {
43 "domain.kind": "saga",
44 "domain.consumer": name,
45 "domain.outcome": Exit.isSuccess(exit)
46 ? "ok"
47 : exit.cause.pipe(
48 EffectCause.findErrorOption,
49 Option.getOrUndefined,
50 Telemetry.outcomeOf,
51 ),
52 }),
53 ),
54 Effect.annotateLogs(attributes),
55 Effect.withSpan(`Domain.saga ${name}`, {
56 kind: "consumer",
57 root: true,
58 attributes,
59 links: cause?.trace ? [{ span: Telemetry.spanOf(cause.trace), attributes: {} }] : [],
60 }),
61 );
62 };
63
64 type Fields = Schema.Struct.Fields;
65
66 /** The schema of a saga's key: a string id, usually an aggregate's id schema. */
67 export type KeySchema = Schema.Top & { readonly Type: string };
68
69 /** The rejections a saga declares, as one union schema. */
70 type RejectsSchema<Rejects extends ReadonlyArray<Rejection.Any>> = Rejects extends readonly []
71 ? typeof Schema.Never
72 : Schema.Union<Rejects>;
73
74 type ResultSchema<R extends Fields | undefined> = R extends Fields
75 ? Schema.Struct<R>
76 : typeof Schema.Void;
77
78 /** The payload a saga's workflow runs with: its key, plus its input. */
79 type PayloadFields<K extends KeySchema, I extends Fields> = { readonly key: K } & I;
80
81 /**
82 * The pure definition of a saga: its invariants.
83 */
84 export interface Definition<
85 K extends KeySchema,
86 I extends Fields,
87 R extends Fields | undefined,
88 Rejects extends ReadonlyArray<Rejection.Any>,
89 > {
90 /**
91 * What identifies one run, usually the id of the aggregate the saga is
92 * about. Starting a saga again with the same key returns the same run.
93 */
94 readonly key: K;
95 /** What a run is started with, besides its key. */
96 readonly input?: I;
97 /** What a run that completes returns. */
98 readonly result?: R;
99 /** Every way a run can be refused. */
100 readonly rejects?: Rejects;
101 }
102
103 /** Where a saga run is. */
104 export type Status<A, E> =
105 | { readonly _tag: "NotStarted" }
106 | { readonly _tag: "Running" }
107 | { readonly _tag: "Completed"; readonly result: A }
108 | { readonly _tag: "Rejected"; readonly rejection: E }
109 | { readonly _tag: "Interrupted" }
110 | { readonly _tag: "Died"; readonly defect: unknown };
111
112 /** One run of a saga. */
113 export interface Run<A, E> {
114 /** The run's id: the saga's key. */
115 readonly executionId: string;
116 /** Where the run is now. */
117 readonly status: Effect.Effect<Status<A, E>>;
118 /**
119 * Wait for the run to finish: its result, or its rejection. A run can take
120 * days, so wait in tests and scripts, not in a policy or a request.
121 */
122 readonly result: Effect.Effect<A, E>;
123 /** Complete a `DurableDeferred` the run waits on. */
124 readonly signal: <S extends Schema.Constraint, Er extends Schema.Constraint>(
125 deferred: DurableDeferred.DurableDeferred<S, Er>,
126 value: S["Type"],
127 ) => Effect.Effect<void>;
128 /** Stop the run: it fails where it waits, and its compensations run. */
129 readonly interrupt: Effect.Effect<void>;
130 }
131
132 /**
133 * A saga's client, provided by the model that lists it. A run is addressed
134 * by the saga's key.
135 */
136 export interface Client<Key, Input, A, E> {
137 /** Start a run, or return the run already started with this key. Returns at once. */
138 readonly start: (key: Key | { readonly id: Key }, input: Input) => Effect.Effect<Run<A, E>>;
139 /** The run with this key. */
140 readonly get: (key: Key | { readonly id: Key }) => Run<A, E>;
141 }
142
143 /**
144 * Structural constraint satisfied by every saga class.
145 */
146 export interface Any extends Context.Key<unknown, unknown> {
147 readonly kind: "Saga";
148 readonly sagaName: string;
149 readonly workflow: Workflow.Workflow<string, any, any, any>;
150 readonly Implementation: Context.Key<unknown, true>;
151 }
152
153 /** The requirement identifier of a saga's client. */
154 export type Identifier<S extends Any> = S extends Context.Key<infer I, unknown> ? I : never;
155
156 /** The requirement identifier of a saga's implementation. */
157 export type ImplementationIdentifier<S extends Any> = S extends Any
158 ? S["Implementation"] extends Context.Key<infer I, unknown>
159 ? I
160 : never
161 : never;
162
163 /** Type-level identity of a saga's client in an Effect's requirements. */
164 export interface SagaKey<Name extends string> {
165 readonly "~alchemy/Domain/Saga": Name;
166 }
167
168 /** Type-level identity of a saga's implementation in an Effect's requirements. */
169 export interface ImplementationKey<Name extends string> {
170 readonly "~alchemy/Domain/Saga/Implementation": Name;
171 }
172
173 /**
174 * A process that spans several aggregates and takes time: a transfer that
175 * debits one account and credits another, or an order that waits for
176 * payment. Each step runs once and its result is kept, so a run that's
177 * interrupted picks up where it left off. A step that fails after earlier
178 * ones succeeded can undo them with compensations.
179 *
180 * A saga is an Effect workflow. Its steps are `Activity`s, it waits with
181 * `DurableClock` and `DurableDeferred`, and it undoes steps with
182 * `withCompensation`. A policy usually decides when to start one.
183 *
184 * ### Declaring a saga
185 * **Example:** A transfer between two accounts
186 * ```typescript
187 * import * as Domain from "@alchemy.run/domain";
188 * import * as Schema from "effect/Schema";
189 * import { AccountId } from "./AccountId.ts";
190 * import { TransferId } from "./TransferId.ts";
191 *
192 * export class DestinationClosed extends Domain.Rejection("DestinationClosed") {}
193 *
194 * export class ExecuteTransfer extends Domain.Saga("ExecuteTransfer", {
195 * key: TransferId,
196 * input: { from: AccountId, to: AccountId, amount: Schema.Int },
197 * rejects: [DestinationClosed],
198 * }) {}
199 * ```
200 *
201 * ### Implementing it
202 * **Example:** Debit, credit, and refund if the credit fails
203 * ```typescript
204 * import * as Effect from "effect/Effect";
205 * import { Activity } from "effect/workflow";
206 * import { Account } from "./Account.ts";
207 *
208 * export const ExecuteTransferLive = ExecuteTransfer.toLayer(
209 * Effect.gen(function* () {
210 * const accounts = yield* Account;
211 * return Effect.fn(function* ({ key, from, to, amount }) {
212 * yield* Activity.make({
213 * name: "debit",
214 * execute: accounts.send(from, new DebitTransfer({ transferId: key, amount })).pipe(Effect.orDie),
215 * }).pipe(
216 * ExecuteTransfer.withCompensation(() =>
217 * Activity.make({
218 * name: "refund",
219 * execute: accounts.send(from, new RefundTransfer({ transferId: key, amount })).pipe(Effect.orDie),
220 * }),
221 * ),
222 * );
223 * yield* Activity.make({
224 * name: "credit",
225 * error: DestinationClosed,
226 * execute: accounts
227 * .send(to, new CreditTransfer({ transferId: key, amount }))
228 * .pipe(Effect.catchTag("NotOpen", () => new DestinationClosed()), Effect.orDie),
229 * });
230 * });
231 * }),
232 * );
233 * ```
234 *
235 * ### Starting it
236 * **Example:** From a policy
237 * ```typescript
238 * export const TransferExecutionLive = TransferExecution.toLayer(
239 * Effect.gen(function* () {
240 * const executions = yield* ExecuteTransfer;
241 * return Effect.fn(function* ({ source, event }) {
242 * yield* executions.start(source, { from: event.from, to: event.to, amount: event.amount });
243 * });
244 * }),
245 * );
246 * ```
247 *
248 * @primitive
249 */
250 export const make = <
251 const Name extends string,
252 K extends KeySchema,
253 const I extends Fields = {},
254 const R extends Fields | undefined = undefined,
255 const Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
256 >(
257 name: Name,
258 definition: Definition<K, I, R, Rejects>,
259 ): SagaClass<Name, K, I, R, Rejects> => {
260 const rejects = definition.rejects ?? [];
261 const workflow = Workflow.make(name, {
262 // The run's cause rides along, so every replay links back to it and keeps its flow.
263 payload: {
264 key: definition.key,
265 ...definition.input,
266 [CAUSE]: Schema.optional(RunCause),
267 } as unknown as PayloadFields<K, I>,
268 idempotencyKey: (payload) => (payload as { readonly key: string }).key,
269 success: (definition.result ? Schema.Struct(definition.result) : Schema.Void) as Schema.Top,
270 error: (rejects.length > 0 ? Schema.Union(rejects) : Schema.Never) as Schema.Top,
271 });
272 const Tag = Context.Service<SagaKey<Name>, Client<unknown, unknown, unknown, unknown>>()(
273 `alchemy/Domain/Saga/${name}`,
274 );
275 const Implementation = Context.Service<ImplementationKey<Name>, true>()(
276 `alchemy/Domain/Saga/${name}/Implementation`,
277 );
278 return class extends Tag {
279 static readonly kind = "Saga" as const;
280 static readonly sagaName: Name = name;
281 static readonly definition = definition;
282 static readonly workflow = workflow;
283 static readonly Implementation = Implementation;
284 static readonly withCompensation = workflow.withCompensation;
285 static toLayer<E, Req>(build: Effect.Effect<Handler<any, any, any, any>, E, Req>) {
286 const register = Layer.unwrap(
287 Effect.map(build, (handle) =>
288 workflow.toLayer((payload, executionId) => {
289 const { [CAUSE]: cause, ...rest } = payload as Record<string, unknown> & {
290 readonly [CAUSE]?: typeof RunCause.Type;
291 };
292 return observeRun(
293 name,
294 executionId,
295 cause,
296 )(handle(rest as never) as Effect.Effect<any, any, any>);
297 }),
298 ),
299 );
300 return Layer.merge(register, Layer.succeed(Implementation, true as const));
301 }
302 } as unknown as SagaClass<Name, K, I, R, Rejects>;
303 };
304
305 /** What a saga's implementation runs for each run: its key and input. */
306 export type Handler<Payload, A, E, Req> = (payload: Payload) => Effect.Effect<A, E, Req>;
307
308 /** The services Effect workflows provide to a run, which a handler may use freely. */
309 type RunServices =
310 | WorkflowEngine.WorkflowEngine
311 | WorkflowEngine.WorkflowInstance
312 | Workflow.Execution<string>
313 | Scope.Scope;
314
315 /**
316 * The class type returned by {@link make}.
317 */
318 export interface SagaClass<
319 Name extends string,
320 K extends KeySchema,
321 I extends Fields,
322 R extends Fields | undefined,
323 Rejects extends ReadonlyArray<Rejection.Any>,
324 > extends Context.ServiceClass<
325 SagaKey<Name>,
326 string,
327 Client<K["Type"], Schema.Struct.Type<I>, ResultSchema<R>["Type"], RejectsSchema<Rejects>["Type"]>
328 > {
329 readonly kind: "Saga";
330 readonly sagaName: Name;
331 readonly definition: Definition<K, I, R, Rejects>;
332 /** The Effect workflow the saga runs as. */
333 readonly workflow: Workflow.Workflow<
334 Name,
335 Schema.Struct<PayloadFields<K, I>>,
336 ResultSchema<R>,
337 RejectsSchema<Rejects>
338 >;
339 /** Provided by {@link toLayer}; a model that lists the saga requires it. */
340 readonly Implementation: Context.Key<ImplementationKey<Name>, true>;
341 /**
342 * Undo a step if the run fails later: `compensation` runs with the step's
343 * result. Use it on a top-level step, usually an `Activity`.
344 */
345 readonly withCompensation: Workflow.Workflow<
346 Name,
347 Schema.Struct<PayloadFields<K, I>>,
348 ResultSchema<R>,
349 RejectsSchema<Rejects>
350 >["withCompensation"];
351 /**
352 * Implement the saga. The construction Effect runs once, resolving the
353 * services its steps use (aggregate clients, external systems); the handler
354 * it returns runs each run, with its key and input.
355 */
356 toLayer<E, Req, HandlerReq>(
357 build: Effect.Effect<
358 Handler<
359 Schema.Struct.Type<PayloadFields<K, I>>,
360 ResultSchema<R>["Type"],
361 RejectsSchema<Rejects>["Type"],
362 HandlerReq
363 >,
364 E,
365 Req
366 >,
367 ): Layer.Layer<
368 ImplementationKey<Name>,
369 E,
370 Req | WorkflowEngine.WorkflowEngine | Exclude<HandlerReq, RunServices>
371 >;
372 }
373
374 // ---------------------------------------------------------------- the client
375
376 /**
377 * A model's view of a workflow engine. Its sagas' workflows are named
378 * `<model>/<saga>`, so two models that run the same saga never share its runs.
379 *
380 * @internal
381 */
382 export const engineFor = (
383 engine: WorkflowEngine.WorkflowEngine["Service"],
384 modelName: string,
385 ): WorkflowEngine.WorkflowEngine["Service"] => {
386 const prefix = `${modelName}/`;
387 const renamed = new WeakMap<Workflow.Any, Workflow.Any>();
388 // A running saga reports its own (already renamed) workflow back; keep it as is.
389 const rename = <W extends Workflow.Any>(workflow: W): W => {
390 if (workflow._tag.startsWith(prefix)) return workflow;
391 let found = renamed.get(workflow);
392 if (found === undefined) {
393 found = Object.create(workflow, {
394 _tag: { value: `${prefix}${workflow._tag}`, enumerable: true },
395 // Storage named after the model too: `Billing.OpenAccount`.
396 annotations: {
397 value: Context.add(workflow.annotations, StorageName, `${modelName}.${workflow._tag}`),
398 enumerable: true,
399 },
400 }) as Workflow.Any;
401 renamed.set(workflow, found);
402 }
403 return found as W;
404 };
405 return {
406 ...engine,
407 register: (workflow, execute) => engine.register(rename(workflow), execute),
408 execute: (workflow, options) => engine.execute(rename(workflow), options),
409 poll: (workflow, executionId) => engine.poll(rename(workflow), executionId),
410 interrupt: (workflow, executionId) => engine.interrupt(rename(workflow), executionId),
411 interruptUnsafe: (workflow, executionId) =>
412 engine.interruptUnsafe(rename(workflow), executionId),
413 resume: (workflow, executionId) => engine.resume(rename(workflow), executionId),
414 scheduleClock: (workflow, options) => engine.scheduleClock(rename(workflow), options),
415 deferredDone: (deferred, options) =>
416 engine.deferredDone(deferred, {
417 ...options,
418 workflowName: options.workflowName.startsWith(prefix)
419 ? options.workflowName
420 : `${prefix}${options.workflowName}`,
421 }),
422 };
423 };
424
425 /** @internal Build a saga's client over a workflow engine. */
426 export const client = (
427 saga: Any,
428 engine: WorkflowEngine.WorkflowEngine["Service"],
429 ): Client<unknown, unknown, unknown, unknown> => {
430 const workflow = saga.workflow;
431 const get = (key: unknown): Run<unknown, unknown> => {
432 const run = makeRun(engine, workflow, targetId(key));
433 return {
434 ...run,
435 // A saga fails only with its rejections.
436 status: Effect.map(run.status, (status): Status<unknown, unknown> =>
437 status._tag === "Failed" ? { _tag: "Rejected", rejection: status.error } : status,
438 ),
439 };
440 };
441 return {
442 start: (key, input) =>
443 Effect.gen(function* () {
444 const executionId = targetId(key);
445 const trace = yield* Telemetry.currentTrace;
446 const correlation = yield* Telemetry.correlationFor(executionId);
447 yield* engine.execute(workflow, {
448 executionId,
449 payload: {
450 ...(input as object),
451 key: executionId,
452 [CAUSE]: { correlationId: correlation, ...(trace ? { trace } : {}) },
453 },
454 discard: true,
455 });
456 return get(executionId);
457 }) as Effect.Effect<Run<unknown, unknown>>,
458 get,
459 };
460 };