sailfork / t3code-github / .repos/ alchemy-effect/ packages/ domain/ src/ Saga.ts

import { makeRun, StorageName } from "alchemy/Workflows";
import * as EffectCause from "effect/Cause";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import type * as Scope from "effect/Scope";
import { type DurableDeferred, Workflow, WorkflowEngine } from "effect/workflow";
import { targetId } from "./Aggregate.ts";
import type * as Rejection from "./Rejection.ts";
import * as Telemetry from "./Telemetry.ts";

/** The hidden payload field that carries a run's cause. */
const CAUSE = "__cause";

const RunCause = Schema.Struct({
  correlationId: Schema.String,
  trace: Schema.optional(
    Schema.Struct({ traceId: Schema.String, spanId: Schema.String, sampled: Schema.Boolean }),
  ),
});

/**
 * Trace one run (one replay) of a saga. A run can last for days, so each
 * starts its own trace and links to the span that started the saga; the
 * correlation id carries the flow, and every command a step sends keeps it.
 */
const observeRun =
  (name: string, executionId: string, cause: typeof RunCause.Type | undefined) =>
  <A, E, R>(effect: Effect.Effect<A, E, R>) => {
    const correlationId = cause?.correlationId ?? executionId;
    const attributes = {
      "domain.saga": name,
      "domain.key": executionId,
      "domain.correlation_id": correlationId,
    };
    return effect.pipe(
      Effect.provideService(Telemetry.Correlation, { id: correlationId }),
      Effect.onExit((exit) =>
        Telemetry.record(Telemetry.runs, {
          "domain.kind": "saga",
          "domain.consumer": name,
          "domain.outcome": Exit.isSuccess(exit)
            ? "ok"
            : exit.cause.pipe(
                EffectCause.findErrorOption,
                Option.getOrUndefined,
                Telemetry.outcomeOf,
              ),
        }),
      ),
      Effect.annotateLogs(attributes),
      Effect.withSpan(`Domain.saga ${name}`, {
        kind: "consumer",
        root: true,
        attributes,
        links: cause?.trace ? [{ span: Telemetry.spanOf(cause.trace), attributes: {} }] : [],
      }),
    );
  };

type Fields = Schema.Struct.Fields;

/** The schema of a saga's key: a string id, usually an aggregate's id schema. */
export type KeySchema = Schema.Top & { readonly Type: string };

/** The rejections a saga declares, as one union schema. */
type RejectsSchema<Rejects extends ReadonlyArray<Rejection.Any>> = Rejects extends readonly []
  ? typeof Schema.Never
  : Schema.Union<Rejects>;

type ResultSchema<R extends Fields | undefined> = R extends Fields
  ? Schema.Struct<R>
  : typeof Schema.Void;

/** The payload a saga's workflow runs with: its key, plus its input. */
type PayloadFields<K extends KeySchema, I extends Fields> = { readonly key: K } & I;

/**
 * The pure definition of a saga: its invariants.
 */
export interface Definition<
  K extends KeySchema,
  I extends Fields,
  R extends Fields | undefined,
  Rejects extends ReadonlyArray<Rejection.Any>,
> {
  /**
   * What identifies one run, usually the id of the aggregate the saga is
   * about. Starting a saga again with the same key returns the same run.
   */
  readonly key: K;
  /** What a run is started with, besides its key. */
  readonly input?: I;
  /** What a run that completes returns. */
  readonly result?: R;
  /** Every way a run can be refused. */
  readonly rejects?: Rejects;
}

/** Where a saga run is. */
export type Status<A, E> =
  | { readonly _tag: "NotStarted" }
  | { readonly _tag: "Running" }
  | { readonly _tag: "Completed"; readonly result: A }
  | { readonly _tag: "Rejected"; readonly rejection: E }
  | { readonly _tag: "Interrupted" }
  | { readonly _tag: "Died"; readonly defect: unknown };

/** One run of a saga. */
export interface Run<A, E> {
  /** The run's id: the saga's key. */
  readonly executionId: string;
  /** Where the run is now. */
  readonly status: Effect.Effect<Status<A, E>>;
  /**
   * Wait for the run to finish: its result, or its rejection. A run can take
   * days, so wait in tests and scripts, not in a policy or a request.
   */
  readonly result: Effect.Effect<A, E>;
  /** Complete a `DurableDeferred` the run waits on. */
  readonly signal: <S extends Schema.Constraint, Er extends Schema.Constraint>(
    deferred: DurableDeferred.DurableDeferred<S, Er>,
    value: S["Type"],
  ) => Effect.Effect<void>;
  /** Stop the run: it fails where it waits, and its compensations run. */
  readonly interrupt: Effect.Effect<void>;
}

/**
 * A saga's client, provided by the model that lists it. A run is addressed
 * by the saga's key.
 */
export interface Client<Key, Input, A, E> {
  /** Start a run, or return the run already started with this key. Returns at once. */
  readonly start: (key: Key | { readonly id: Key }, input: Input) => Effect.Effect<Run<A, E>>;
  /** The run with this key. */
  readonly get: (key: Key | { readonly id: Key }) => Run<A, E>;
}

/**
 * Structural constraint satisfied by every saga class.
 */
export interface Any extends Context.Key<unknown, unknown> {
  readonly kind: "Saga";
  readonly sagaName: string;
  readonly workflow: Workflow.Workflow<string, any, any, any>;
  readonly Implementation: Context.Key<unknown, true>;
}

/** The requirement identifier of a saga's client. */
export type Identifier<S extends Any> = S extends Context.Key<infer I, unknown> ? I : never;

/** The requirement identifier of a saga's implementation. */
export type ImplementationIdentifier<S extends Any> = S extends Any
  ? S["Implementation"] extends Context.Key<infer I, unknown>
    ? I
    : never
  : never;

/** Type-level identity of a saga's client in an Effect's requirements. */
export interface SagaKey<Name extends string> {
  readonly "~alchemy/Domain/Saga": Name;
}

/** Type-level identity of a saga's implementation in an Effect's requirements. */
export interface ImplementationKey<Name extends string> {
  readonly "~alchemy/Domain/Saga/Implementation": Name;
}

/**
 * A process that spans several aggregates and takes time: a transfer that
 * debits one account and credits another, or an order that waits for
 * payment. Each step runs once and its result is kept, so a run that's
 * interrupted picks up where it left off. A step that fails after earlier
 * ones succeeded can undo them with compensations.
 *
 * A saga is an Effect workflow. Its steps are `Activity`s, it waits with
 * `DurableClock` and `DurableDeferred`, and it undoes steps with
 * `withCompensation`. A policy usually decides when to start one.
 *
 * ### Declaring a saga
 * **Example:** A transfer between two accounts
 * ```typescript
 * import * as Domain from "@alchemy.run/domain";
 * import * as Schema from "effect/Schema";
 * import { AccountId } from "./AccountId.ts";
 * import { TransferId } from "./TransferId.ts";
 *
 * export class DestinationClosed extends Domain.Rejection("DestinationClosed") {}
 *
 * export class ExecuteTransfer extends Domain.Saga("ExecuteTransfer", {
 *   key: TransferId,
 *   input: { from: AccountId, to: AccountId, amount: Schema.Int },
 *   rejects: [DestinationClosed],
 * }) {}
 * ```
 *
 * ### Implementing it
 * **Example:** Debit, credit, and refund if the credit fails
 * ```typescript
 * import * as Effect from "effect/Effect";
 * import { Activity } from "effect/workflow";
 * import { Account } from "./Account.ts";
 *
 * export const ExecuteTransferLive = ExecuteTransfer.toLayer(
 *   Effect.gen(function* () {
 *     const accounts = yield* Account;
 *     return Effect.fn(function* ({ key, from, to, amount }) {
 *       yield* Activity.make({
 *         name: "debit",
 *         execute: accounts.send(from, new DebitTransfer({ transferId: key, amount })).pipe(Effect.orDie),
 *       }).pipe(
 *         ExecuteTransfer.withCompensation(() =>
 *           Activity.make({
 *             name: "refund",
 *             execute: accounts.send(from, new RefundTransfer({ transferId: key, amount })).pipe(Effect.orDie),
 *           }),
 *         ),
 *       );
 *       yield* Activity.make({
 *         name: "credit",
 *         error: DestinationClosed,
 *         execute: accounts
 *           .send(to, new CreditTransfer({ transferId: key, amount }))
 *           .pipe(Effect.catchTag("NotOpen", () => new DestinationClosed()), Effect.orDie),
 *       });
 *     });
 *   }),
 * );
 * ```
 *
 * ### Starting it
 * **Example:** From a policy
 * ```typescript
 * export const TransferExecutionLive = TransferExecution.toLayer(
 *   Effect.gen(function* () {
 *     const executions = yield* ExecuteTransfer;
 *     return Effect.fn(function* ({ source, event }) {
 *       yield* executions.start(source, { from: event.from, to: event.to, amount: event.amount });
 *     });
 *   }),
 * );
 * ```
 *
 * @primitive
 */
export const make = <
  const Name extends string,
  K extends KeySchema,
  const I extends Fields = {},
  const R extends Fields | undefined = undefined,
  const Rejects extends ReadonlyArray<Rejection.Any> = readonly [],
>(
  name: Name,
  definition: Definition<K, I, R, Rejects>,
): SagaClass<Name, K, I, R, Rejects> => {
  const rejects = definition.rejects ?? [];
  const workflow = Workflow.make(name, {
    // The run's cause rides along, so every replay links back to it and keeps its flow.
    payload: {
      key: definition.key,
      ...definition.input,
      [CAUSE]: Schema.optional(RunCause),
    } as unknown as PayloadFields<K, I>,
    idempotencyKey: (payload) => (payload as { readonly key: string }).key,
    success: (definition.result ? Schema.Struct(definition.result) : Schema.Void) as Schema.Top,
    error: (rejects.length > 0 ? Schema.Union(rejects) : Schema.Never) as Schema.Top,
  });
  const Tag = Context.Service<SagaKey<Name>, Client<unknown, unknown, unknown, unknown>>()(
    `alchemy/Domain/Saga/${name}`,
  );
  const Implementation = Context.Service<ImplementationKey<Name>, true>()(
    `alchemy/Domain/Saga/${name}/Implementation`,
  );
  return class extends Tag {
    static readonly kind = "Saga" as const;
    static readonly sagaName: Name = name;
    static readonly definition = definition;
    static readonly workflow = workflow;
    static readonly Implementation = Implementation;
    static readonly withCompensation = workflow.withCompensation;
    static toLayer<E, Req>(build: Effect.Effect<Handler<any, any, any, any>, E, Req>) {
      const register = Layer.unwrap(
        Effect.map(build, (handle) =>
          workflow.toLayer((payload, executionId) => {
            const { [CAUSE]: cause, ...rest } = payload as Record<string, unknown> & {
              readonly [CAUSE]?: typeof RunCause.Type;
            };
            return observeRun(
              name,
              executionId,
              cause,
            )(handle(rest as never) as Effect.Effect<any, any, any>);
          }),
        ),
      );
      return Layer.merge(register, Layer.succeed(Implementation, true as const));
    }
  } as unknown as SagaClass<Name, K, I, R, Rejects>;
};

/** What a saga's implementation runs for each run: its key and input. */
export type Handler<Payload, A, E, Req> = (payload: Payload) => Effect.Effect<A, E, Req>;

/** The services Effect workflows provide to a run, which a handler may use freely. */
type RunServices =
  | WorkflowEngine.WorkflowEngine
  | WorkflowEngine.WorkflowInstance
  | Workflow.Execution<string>
  | Scope.Scope;

/**
 * The class type returned by {@link make}.
 */
export interface SagaClass<
  Name extends string,
  K extends KeySchema,
  I extends Fields,
  R extends Fields | undefined,
  Rejects extends ReadonlyArray<Rejection.Any>,
> extends Context.ServiceClass<
  SagaKey<Name>,
  string,
  Client<K["Type"], Schema.Struct.Type<I>, ResultSchema<R>["Type"], RejectsSchema<Rejects>["Type"]>
> {
  readonly kind: "Saga";
  readonly sagaName: Name;
  readonly definition: Definition<K, I, R, Rejects>;
  /** The Effect workflow the saga runs as. */
  readonly workflow: Workflow.Workflow<
    Name,
    Schema.Struct<PayloadFields<K, I>>,
    ResultSchema<R>,
    RejectsSchema<Rejects>
  >;
  /** Provided by {@link toLayer}; a model that lists the saga requires it. */
  readonly Implementation: Context.Key<ImplementationKey<Name>, true>;
  /**
   * Undo a step if the run fails later: `compensation` runs with the step's
   * result. Use it on a top-level step, usually an `Activity`.
   */
  readonly withCompensation: Workflow.Workflow<
    Name,
    Schema.Struct<PayloadFields<K, I>>,
    ResultSchema<R>,
    RejectsSchema<Rejects>
  >["withCompensation"];
  /**
   * Implement the saga. The construction Effect runs once, resolving the
   * services its steps use (aggregate clients, external systems); the handler
   * it returns runs each run, with its key and input.
   */
  toLayer<E, Req, HandlerReq>(
    build: Effect.Effect<
      Handler<
        Schema.Struct.Type<PayloadFields<K, I>>,
        ResultSchema<R>["Type"],
        RejectsSchema<Rejects>["Type"],
        HandlerReq
      >,
      E,
      Req
    >,
  ): Layer.Layer<
    ImplementationKey<Name>,
    E,
    Req | WorkflowEngine.WorkflowEngine | Exclude<HandlerReq, RunServices>
  >;
}

// ---------------------------------------------------------------- the client

/**
 * A model's view of a workflow engine. Its sagas' workflows are named
 * `<model>/<saga>`, so two models that run the same saga never share its runs.
 *
 * @internal
 */
export const engineFor = (
  engine: WorkflowEngine.WorkflowEngine["Service"],
  modelName: string,
): WorkflowEngine.WorkflowEngine["Service"] => {
  const prefix = `${modelName}/`;
  const renamed = new WeakMap<Workflow.Any, Workflow.Any>();
  // A running saga reports its own (already renamed) workflow back; keep it as is.
  const rename = <W extends Workflow.Any>(workflow: W): W => {
    if (workflow._tag.startsWith(prefix)) return workflow;
    let found = renamed.get(workflow);
    if (found === undefined) {
      found = Object.create(workflow, {
        _tag: { value: `${prefix}${workflow._tag}`, enumerable: true },
        // Storage named after the model too: `Billing.OpenAccount`.
        annotations: {
          value: Context.add(workflow.annotations, StorageName, `${modelName}.${workflow._tag}`),
          enumerable: true,
        },
      }) as Workflow.Any;
      renamed.set(workflow, found);
    }
    return found as W;
  };
  return {
    ...engine,
    register: (workflow, execute) => engine.register(rename(workflow), execute),
    execute: (workflow, options) => engine.execute(rename(workflow), options),
    poll: (workflow, executionId) => engine.poll(rename(workflow), executionId),
    interrupt: (workflow, executionId) => engine.interrupt(rename(workflow), executionId),
    interruptUnsafe: (workflow, executionId) =>
      engine.interruptUnsafe(rename(workflow), executionId),
    resume: (workflow, executionId) => engine.resume(rename(workflow), executionId),
    scheduleClock: (workflow, options) => engine.scheduleClock(rename(workflow), options),
    deferredDone: (deferred, options) =>
      engine.deferredDone(deferred, {
        ...options,
        workflowName: options.workflowName.startsWith(prefix)
          ? options.workflowName
          : `${prefix}${options.workflowName}`,
      }),
  };
};

/** @internal Build a saga's client over a workflow engine. */
export const client = (
  saga: Any,
  engine: WorkflowEngine.WorkflowEngine["Service"],
): Client<unknown, unknown, unknown, unknown> => {
  const workflow = saga.workflow;
  const get = (key: unknown): Run<unknown, unknown> => {
    const run = makeRun(engine, workflow, targetId(key));
    return {
      ...run,
      // A saga fails only with its rejections.
      status: Effect.map(run.status, (status): Status<unknown, unknown> =>
        status._tag === "Failed" ? { _tag: "Rejected", rejection: status.error } : status,
      ),
    };
  };
  return {
    start: (key, input) =>
      Effect.gen(function* () {
        const executionId = targetId(key);
        const trace = yield* Telemetry.currentTrace;
        const correlation = yield* Telemetry.correlationFor(executionId);
        yield* engine.execute(workflow, {
          executionId,
          payload: {
            ...(input as object),
            key: executionId,
            [CAUSE]: { correlationId: correlation, ...(trace ? { trace } : {}) },
          },
          discard: true,
        });
        return get(executionId);
      }) as Effect.Effect<Run<unknown, unknown>>,
    get,
  };
};