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
| 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 | }; |