sailfork / t3code-github / .repos/ alchemy-effect/ packages/ integration-tests/ test/ Domain/ Telemetry.test.ts

import * as Domain from "@alchemy.run/domain";
import { Story } from "@alchemy.run/domain/Story";
import { describe, expect, it } from "@alchemy.run/test";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Layer from "effect/Layer";
import * as Metric from "effect/Metric";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import * as Schema from "effect/Schema";
import * as Socket from "effect/socket/Socket";
import * as Stream from "effect/Stream";
import * as Tracer from "effect/Tracer";
import { Activity } from "effect/workflow";

// A wallet whose debits a policy audits on a second aggregate, and reminds later.
class Opened extends Domain.Event("Opened", { balance: Schema.Number }) {}
class Debited extends Domain.Event(
  "Debited",
  { amount: Schema.Number, note: Schema.Redacted(Schema.String) },
  { attributes: (e) => ({ "wallet.amount": e.amount, "wallet.note": e.note }) },
) {}
class Insufficient extends Domain.Rejection(
  "Insufficient",
  { balance: Schema.Number },
  { attributes: (r) => ({ "wallet.balance": r.balance }) },
) {}

class Open extends Domain.Command("Open", {
  target: Schema.String,
  input: { balance: Schema.Number },
  events: [Opened],
}) {}
class Debit extends Domain.Command("Debit", {
  target: Schema.String,
  input: { amount: Schema.Number, note: Schema.Redacted(Schema.String) },
  events: [Debited],
  rejects: [Insufficient],
  attributes: (cmd) => ({ "wallet.amount": cmd.amount }),
}) {}

class Wallet extends Domain.Aggregate("Wallet", {
  id: Schema.String,
  state: Schema.Struct({ balance: Schema.Number }),
  initial: { balance: 0 },
  commands: [Open, Debit],
  decide: {
    Open: (_, cmd) => [new Opened({ balance: cmd.balance })],
    Debit: Effect.fn(function* (s, cmd) {
      yield* Effect.annotateCurrentSpan("wallet.checked", true);
      return s.balance < cmd.amount
        ? yield* new Insufficient({ balance: s.balance })
        : [new Debited({ amount: cmd.amount, note: cmd.note })];
    }),
  },
  evolve: {
    Opened: (_, e) => ({ balance: e.balance }),
    Debited: (s, e) => ({ balance: s.balance - e.amount }),
  },
}) {}

class Audited extends Domain.Event("Audited", { wallet: Schema.String }) {}
class Reminded extends Domain.Event("Reminded") {}
class Audit extends Domain.Command("Audit", {
  target: Schema.String,
  input: { wallet: Schema.String },
  events: [Audited],
}) {}
class Remind extends Domain.Command("Remind", { target: Schema.String, events: [Reminded] }) {}
class Ledger extends Domain.Aggregate("Ledger", {
  id: Schema.String,
  state: Schema.Struct({ audits: Schema.Number }),
  initial: { audits: 0 },
  commands: [Audit, Remind],
  decide: {
    Audit: (_, cmd) => [new Audited({ wallet: cmd.wallet })],
    Remind: () => [new Reminded()],
  },
  evolve: {
    Audited: (s) => ({ audits: s.audits + 1 }),
    Reminded: (s) => s,
  },
}) {}

class AuditDebits extends Domain.Policy("AuditDebits", { from: Wallet, on: [Debited] }) {}
const AuditDebitsLive = AuditDebits.toLayer(
  Effect.gen(function* () {
    const ledgers = yield* Ledger;
    return Effect.fn(function* ({ source }) {
      yield* ledgers.send("main", new Audit({ wallet: source.id }));
      yield* ledgers
        .schedule("main", new Remind(), { after: "1 hour" })
        .pipe(Effect.catchTag("AlreadyExecuted", () => Effect.void));
    });
  }),
);

class Balance extends Domain.View("Balance", {
  from: [Wallet],
  key: Wallet,
  state: Schema.Struct({ balance: Schema.Number }),
  initial: { balance: 0 },
  evolve: {
    Opened: (_, e) => ({ balance: e.balance }),
    Debited: (v, e) => ({ balance: v.balance - e.amount }),
  },
}) {}

// The model a browser client reads the balance from.
class Balances extends Domain.Model("TelemetryBalances", {
  aggregates: [Wallet],
  views: [Balance],
}) {}
class WalletApi extends Domain.Api("WalletApi", { model: Balances, views: ["Balance"] }) {}

class Bank extends Domain.Model("TelemetryBank", {
  aggregates: [Wallet, Ledger],
  policies: [AuditDebits],
}) {}

// A second model: a policy that checks an external system and starts a saga,
// and a projection over the wallet's events.
class Scorer extends Domain.ExternalSystem("Scorer", {
  score: { args: { wallet: Schema.String }, success: { risk: Schema.Number } },
}) {}

class Review extends Domain.Saga("Review", { key: Schema.String, input: {} }) {}
const ReviewLive = Review.toLayer(
  Effect.gen(function* () {
    const ledgers = yield* Ledger;
    return Effect.fn(function* ({ key }) {
      yield* Activity.make({
        name: "audit",
        execute: ledgers.send("main", new Audit({ wallet: key })).pipe(Effect.orDie),
      });
    });
  }),
);

class ReviewDebits extends Domain.Policy("ReviewDebits", { from: Wallet, on: [Debited] }) {}
const ReviewDebitsLive = ReviewDebits.toLayer(
  Effect.gen(function* () {
    const scorer = yield* Scorer;
    const reviews = yield* Review;
    return Effect.fn(function* ({ source }) {
      const { risk } = yield* scorer.score({ wallet: source.id });
      if (risk > 0.5) yield* reviews.start(source, {});
    });
  }),
);

class Movements extends Domain.Projection("Movements", {
  from: [Wallet],
  key: Wallet,
  on: [Debited],
}) {}
const MovementsLive = Movements.toLayer(Effect.succeed(() => Effect.void));

class Reviewed extends Domain.Model("TelemetryReviews", {
  aggregates: [Wallet, Ledger],
  policies: [ReviewDebits],
  projections: [Movements],
  sagas: [Review],
}) {}

const reviewStory = Story.make(Reviewed, {
  layer: Layer.mergeAll(ReviewDebitsLive, ReviewLive, MovementsLive),
  stub: [Scorer],
});

const story = Story.make(Bank, { layer: Layer.mergeAll(AuditDebitsLive) });
const alice = Wallet.ref("alice");
const ledger = Ledger.ref("main");

/** A tracer that keeps every span it starts. */
const recording = () => {
  const spans: Array<Tracer.NativeSpan> = [];
  const tracer = Tracer.make({
    span: (options) => {
      const span = new Tracer.NativeSpan(options);
      spans.push(span);
      return span;
    },
  });
  const named = (name: string) => spans.filter((span) => span.name === name);
  const one = (name: string) => {
    const found = named(name);
    expect(found.map((s) => s.name)).toEqual([name]);
    return found[0]!;
  };
  return { spans, tracer, named, one };
};

const parentId = (span: Tracer.Span) => Option.getOrUndefined(span.parent)?.spanId;

describe("Domain telemetry", { tags: ["unit", "local"] }, () => {
  it.effect("a command's whole flow is one trace, with one correlation id", () =>
    Effect.gen(function* () {
      const { tracer, one, spans } = recording();
      yield* story(
        Story.given(alice, new Opened({ balance: 100 })),
        Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })),
        Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })),
        Story.then(ledger, new Audited({ wallet: "alice" })),
      ).pipe(Effect.withTracer(tracer));

      const debit = one("Domain.decide Wallet.Debit");
      const policy = one("Domain.policy AuditDebits");
      const audit = one("Domain.decide Ledger.Audit");
      const auditSend = one("Domain.send Ledger.Audit");

      // The policy continues the debit's trace, and the command it sends continues the policy's.
      expect(policy.traceId).toBe(debit.traceId);
      expect(parentId(policy)).toBe(debit.spanId);
      expect(parentId(auditSend)).toBe(policy.spanId);
      expect(parentId(audit)).toBe(auditSend.spanId);
      expect(audit.traceId).toBe(debit.traceId);

      // One correlation id, the debit's command id, end to end.
      const correlation = debit.attributes.get("domain.correlation_id");
      expect(correlation).toBe(debit.attributes.get("domain.command_id"));
      for (const span of [policy, auditSend, audit]) {
        expect(span.attributes.get("domain.correlation_id")).toBe(correlation);
      }
      expect(spans.every((s) => s.status._tag === "Ended")).toBe(true);
    }),
  );

  it.effect("records only the attributes a declaration returns, and never a Redacted value", () =>
    Effect.gen(function* () {
      const { tracer, one } = recording();
      yield* story(
        Story.given(alice, new Opened({ balance: 100 })),
        Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })),
        Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })),
        Story.then(ledger, new Audited({ wallet: "alice" })),
      ).pipe(Effect.withTracer(tracer));

      const debit = one("Domain.decide Wallet.Debit");
      expect(debit.attributes.get("wallet.amount")).toBe(40);
      expect(debit.attributes.get("wallet.checked")).toBe(true); // annotated inside decide
      expect(debit.attributes.get("domain.outcome")).toBe("accepted");
      // The event's own attributes ride on its span event; its note is Redacted.
      const [name, , attributes] = debit.events[0]!;
      expect(name).toBe("Debited");
      expect(attributes).toMatchObject({ "wallet.amount": 40, "wallet.note": "<redacted>" });

      // Nothing from a payload is recorded unless a declaration asks for it.
      const audit = one("Domain.decide Ledger.Audit");
      const keys = [...audit.attributes.keys()];
      expect(keys.every((key) => key.startsWith("domain."))).toBe(true);
      const values = [
        ...debit.attributes.values(),
        ...debit.events.flatMap(([, , a]) => Object.values(a)),
      ];
      expect(values).not.toContain("rent");
    }),
  );

  it.effect("a rejection is an outcome, not an error", () =>
    Effect.gen(function* () {
      const { tracer, one } = recording();
      yield* story(
        Story.given(alice, new Opened({ balance: 10 })),
        Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })),
        Story.rejected(new Insufficient({ balance: 10 })),
      ).pipe(Effect.withTracer(tracer));

      const debit = one("Domain.decide Wallet.Debit");
      expect(debit.attributes.get("domain.outcome")).toBe("Insufficient");
      expect(debit.attributes.get("wallet.balance")).toBe(10);
      expect(debit.status._tag === "Ended" && debit.status.exit._tag).toBe("Success");
      const send = one("Domain.send Wallet.Debit");
      expect(send.attributes.get("domain.outcome")).toBe("Insufficient");
      expect(send.status._tag === "Ended" && send.status.exit._tag).toBe("Success");
    }),
  );

  it.effect("a scheduled command links to its cause instead of continuing its trace", () =>
    Effect.gen(function* () {
      const { tracer, one } = recording();
      yield* story(
        Story.clock("2026-01-01T00:00:00Z"),
        Story.given(alice, new Opened({ balance: 100 })),
        Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })),
        Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })),
        Story.then(ledger, new Audited({ wallet: "alice" })),
        Story.clock("2026-01-01T01:00:00Z"),
        Story.then(ledger, new Reminded()),
      ).pipe(Effect.withTracer(tracer));

      const scheduled = one("Domain.schedule Ledger.Remind");
      const remind = one("Domain.decide Ledger.Remind");
      expect(parentId(remind)).not.toBe(scheduled.spanId);
      expect(remind.links.map((l) => l.span.spanId)).toEqual([scheduled.spanId]);
      // Still the same flow.
      expect(remind.attributes.get("domain.correlation_id")).toBe(
        one("Domain.decide Wallet.Debit").attributes.get("domain.correlation_id"),
      );
    }),
  );

  it.effect("a saga run starts its own trace, linked to the policy that started it", () =>
    Effect.gen(function* () {
      const { tracer, one, named } = recording();
      yield* reviewStory(
        Story.given(alice, new Opened({ balance: 100 })),
        Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })),
        Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })),
        Story.call(Scorer.score, { wallet: "alice" }),
        Story.succeed(Scorer.score, { risk: 0.9 }),
        Story.then(ledger, new Audited({ wallet: "alice" })),
        Story.saga(Review, "alice", { _tag: "Completed", result: undefined }),
      ).pipe(Effect.withTracer(tracer));

      const debit = one("Domain.decide Wallet.Debit");
      const policy = one("Domain.policy ReviewDebits");
      // The external call is part of the policy's run.
      expect(parentId(one("Domain.external Scorer.score"))).toBe(policy.spanId);

      // Every replay of the run is its own trace, linked to the policy that started it.
      const runs = named("Domain.saga Review");
      expect(runs.length).toBeGreaterThan(0);
      for (const run of runs) {
        expect(run.traceId).not.toBe(debit.traceId);
        expect(run.links.map((l) => l.span.spanId)).toEqual([policy.spanId]);
        expect(run.attributes.get("domain.correlation_id")).toBe(
          debit.attributes.get("domain.correlation_id"),
        );
      }
      // The command its step sends keeps the flow's correlation id.
      expect(one("Domain.decide Ledger.Audit").attributes.get("domain.correlation_id")).toBe(
        debit.attributes.get("domain.correlation_id"),
      );
    }),
  );

  it.effect("a projection batch links to the commits it handles", () =>
    Effect.gen(function* () {
      const { tracer, one } = recording();
      yield* reviewStory(
        Story.given(alice, new Opened({ balance: 100 })),
        Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })),
        Story.then(alice, new Debited({ amount: 40, note: Redacted.make("rent") })),
        Story.call(Scorer.score, { wallet: "alice" }),
        Story.succeed(Scorer.score, { risk: 0.1 }),
      ).pipe(Effect.withTracer(tracer));

      const debit = one("Domain.decide Wallet.Debit");
      const batch = one("Domain.projection Movements");
      expect(batch.traceId).not.toBe(debit.traceId);
      expect(batch.links.map((l) => l.span.spanId)).toEqual([debit.spanId]);
      expect(batch.attributes.get("domain.batch")).toBe(1);
    }),
  );

  it.effect("a live read carries the caller's span, so the server joins its trace", () =>
    Effect.gen(function* () {
      const { tracer } = recording();
      const urls: Array<string> = [];
      // A socket that never opens: enough to see what the client asked for.
      const sockets = Layer.succeed(Socket.WebSocketConstructor, (url) => {
        urls.push(url);
        return {
          addEventListener: () => {},
          removeEventListener: () => {},
          close: () => {},
          readyState: 0,
        } as never;
      });
      const watched = yield* Effect.gen(function* () {
        const client = yield* WalletApi.client;
        const fiber = yield* client.Balance.watch("alice").pipe(Stream.runDrain, Effect.forkChild);
        for (let i = 0; i < 100 && urls.length === 0; i++) yield* Effect.yieldNow;
        const span = yield* Effect.currentSpan;
        yield* Fiber.interrupt(fiber);
        return span;
      }).pipe(
        Effect.withSpan("click"),
        Effect.scoped,
        Effect.provide(
          Domain.protocolWebSocket("http://bank.test/api").pipe(
            Layer.provide(Layer.mergeAll(FetchHttpClient.layer, sockets)),
          ),
        ),
        Effect.withTracer(tracer),
      );
      expect(urls).toHaveLength(1);
      const read = JSON.parse(new URL(urls[0]!).searchParams.get("read")!);
      expect(read.tag).toBe("Balance.watch");
      // The RPC client's span for the read, a child of the caller's.
      expect(read.traceId).toBe(watched.traceId);
      expect(typeof read.spanId).toBe("string");
    }),
  );

  it.effect("counts commands by outcome", () =>
    Effect.gen(function* () {
      const rejected = Metric.withAttributes(Domain.Telemetry.commands, {
        "domain.aggregate": "Wallet",
        "domain.command": "Debit",
        "domain.outcome": "Insufficient",
      });
      const before = (yield* Metric.value(rejected)).count;
      yield* story(
        Story.given(alice, new Opened({ balance: 10 })),
        Story.when(alice, new Debit({ amount: 40, note: Redacted.make("rent") })),
        Story.rejected(new Insufficient({ balance: 10 })),
      );
      expect((yield* Metric.value(rejected)).count).toBe(before + 1);
    }),
  );
});