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

import * as Domain from "@alchemy.run/domain";
import * as DomainHttp from "@alchemy.run/domain/Http";
import { InMemory } from "@alchemy.run/domain/InMemory";
import { describe, expect, it } from "@alchemy.run/test";
import * as BunHttpServer from "@effect/platform-bun/BunHttpServer";
import * as Cause from "effect/Cause";
import * as Effect from "effect/Effect";
import * as Sse from "effect/encoding/Sse";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as HttpApi from "effect/http-api/HttpApi";
import * as HttpApiBuilder from "effect/http-api/HttpApiBuilder";
import type * as HttpApiGroup from "effect/http-api/HttpApiGroup";
import * as HttpApiSchema from "effect/http-api/HttpApiSchema";
import * as OpenApi from "effect/http-api/OpenApi";
import * as Headers from "effect/http/Headers";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import * as HttpRouter from "effect/http/HttpRouter";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as RpcMiddleware from "effect/rpc/RpcMiddleware";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";

// ---------------------------------------------------------------- a wallet domain

const WalletId = Schema.String.pipe(Schema.brand("WalletId"));

/** Who is calling. The session middleware provides it from an `x-owner` header. */
class Owner extends Domain.RequestContext<Owner>()("Test/Owner", Schema.String) {}
class Unauthenticated extends Domain.Rejection("Unauthenticated") {}
class Session extends RpcMiddleware.Service<Session, { provides: Owner }>()("Test/Session", {
  // A middleware error answers with the status it is annotated with.
  error: Unauthenticated.pipe(HttpApiSchema.status(401)),
}) {}
const SessionLive = Layer.succeed(Session, (effect, { headers }) =>
  Option.match(Headers.get(headers, "x-owner"), {
    onNone: () => Effect.fail(new Unauthenticated()),
    onSome: (owner) => Effect.provideService(effect, Owner, owner),
  }),
);

class Deposited extends Domain.Event("Deposited", {
  owner: Schema.String,
  amount: Schema.Int,
  at: Schema.DateTimeUtc,
}) {}
class OverLimit extends Domain.Rejection("OverLimit", { limit: Schema.Int }) {}
/** Its status is Effect's own `httpApiStatus` annotation, which every HttpApi reads. */
class NotOwner extends Domain.Rejection("NotOwner", {}, { httpApiStatus: 403 }) {}

class Deposit extends Domain.Command("Deposit", {
  target: WalletId,
  middleware: [Session],
  // `at` is a transform (an ISO string on the wire, a DateTime in `decide`).
  input: { amount: Schema.Int, at: Schema.DateTimeUtc },
  events: [Deposited],
  rejects: [OverLimit],
  reply: { balance: Schema.Int, at: Schema.NullOr(Schema.DateTimeUtc) },
}) {}

const WalletState = Schema.Struct({
  owner: Schema.NullOr(Schema.String),
  balance: Schema.Int,
  at: Schema.NullOr(Schema.DateTimeUtc),
});

class Wallet extends Domain.Aggregate("Wallet", {
  id: WalletId,
  state: WalletState,
  initial: { owner: null, balance: 0, at: null },
  commands: [Deposit],
  decide: {
    Deposit: Effect.fn(function* (_, cmd) {
      if (cmd.amount > 100) return yield* new OverLimit({ limit: 100 });
      return [new Deposited({ owner: yield* Owner, amount: cmd.amount, at: cmd.at })];
    }),
  },
  evolve: {
    Deposited: (s, e) => ({ owner: e.owner, balance: s.balance + e.amount, at: e.at }),
  },
  reply: { Deposit: (s) => ({ balance: s.balance, at: s.at }) },
  read: { middleware: [Session] },
}) {}

/** Only the wallet's owner reads its balance. */
class Balance extends Domain.View("Balance", {
  from: [Wallet],
  key: Wallet,
  middleware: [Session],
  rejects: [NotOwner],
  state: Schema.Struct({ owner: Schema.String, balance: Schema.Int }),
  initial: { owner: "", balance: 0 },
  evolve: { Deposited: (s, e) => ({ owner: e.owner, balance: s.balance + e.amount }) },
  validate: Effect.fn(function* (_request, s) {
    if (s !== null && s.owner !== (yield* Owner)) return yield* new NotOwner();
  }),
}) {}

// ---------------------------------------------------------------- the HTTP surface

/**
 * A session with a client half: a typed client attaches the caller as
 * `x-owner`. The server holds one for its own calls, as "server".
 */
class SignedSession extends RpcMiddleware.Service<SignedSession, { provides: Owner }>()(
  "Test/SignedSession",
  { error: Unauthenticated.pipe(HttpApiSchema.status(401)), requiredForClient: true },
) {}
const SignedSessionLive = Layer.succeed(SignedSession, (effect, { headers }) =>
  Option.match(Headers.get(headers, "x-owner"), {
    onNone: () => Effect.fail(new Unauthenticated()),
    onSome: (owner) => Effect.provideService(effect, Owner, owner),
  }),
);
const ServerCredential = RpcMiddleware.layerClient(SignedSession, ({ request, next }) =>
  next({ ...request, headers: Headers.set(request.headers, "x-owner", "server") }),
);

class Signed extends Domain.Event("Signed", { owner: Schema.String }) {}
class Sign extends Domain.Command("Sign", {
  target: Schema.String,
  middleware: [SignedSession],
  events: [Signed],
  reply: { owner: Schema.NullOr(Schema.String) },
}) {}
class Ledger extends Domain.Aggregate("Ledger", {
  id: Schema.String,
  state: Schema.Struct({ owner: Schema.NullOr(Schema.String) }),
  initial: { owner: null },
  commands: [Sign],
  decide: {
    Sign: Effect.fn(function* () {
      return [new Signed({ owner: yield* Owner })];
    }),
  },
  evolve: { Signed: (_, e) => ({ owner: e.owner }) },
  reply: { Sign: (s) => ({ owner: s.owner }) },
}) {}
class Wallets extends Domain.Model("HttpWallets", {
  aggregates: [Wallet, Ledger],
  views: [Balance],
}) {}
class WalletApi extends Domain.Api("WalletApi", {
  model: Wallets,
  commands: ["Deposit"],
  aggregates: ["Wallet"],
}) {}
class LedgerApi extends Domain.Api("LedgerApi", {
  model: Wallets,
  commands: ["Sign"],
  views: [],
}) {}

/** Every call the Api serves. */
const WalletHttp = DomainHttp.toHttpApi(WalletApi);

/** An Api for HTTP clients that may only deposit: publishing less is a smaller Api. */
class DepositOnlyApi extends Domain.Api("DepositOnlyApi", {
  model: Wallets,
  commands: ["Deposit"],
  views: [],
  aggregates: [],
}) {}

/** The hosted model, its middleware, and an in-process Bun server with a client for it. */
const Hosted = Layer.mergeAll(
  SessionLive,
  SignedSessionLive,
  ServerCredential,
  Wallets.layer(Layer.empty),
).pipe(Layer.provide(InMemory), Layer.provideMerge(BunHttpServer.layerTest));

const serve = <Id extends string, Groups extends HttpApiGroup.Constraint>(
  api: HttpApi.HttpApi<Id, Groups>,
  handlers: Layer.Layer<HttpApiGroup.ToService<Id, Groups>, never, Layer.Success<typeof Hosted>>,
) =>
  HttpRouter.serve(HttpApiBuilder.layer(api), { disableListenLog: true, disableLogger: true }).pipe(
    Layer.provide(handlers),
    Layer.provideMerge(Hosted),
  );

/** The surface's own HttpApi, served. */
const Served = serve(WalletHttp.api, WalletHttp.layer);

/** An app's own HttpApi that serves the group under `/v1`. */
const AppApi = HttpApi.make("App").add(WalletHttp.group.prefix("/v1"));

interface SendOptions {
  readonly owner?: string;
  readonly body?: unknown;
  readonly headers?: Record<string, string>;
}

const execute = (method: "GET" | "POST", path: string, options: SendOptions) =>
  Effect.gen(function* () {
    const client = yield* HttpClient.HttpClient;
    let request = HttpClientRequest.make(method)(path).pipe(
      HttpClientRequest.setHeaders(options.headers ?? {}),
    );
    if (options.owner) request = HttpClientRequest.setHeader(request, "x-owner", options.owner);
    if (options.body !== undefined)
      request = HttpClientRequest.bodyJsonUnsafe(request, options.body);
    return yield* client.execute(request);
  });

const send = (method: "GET" | "POST", path: string, options: SendOptions = {}) =>
  Effect.gen(function* () {
    const response = yield* execute(method, path, options);
    const text = yield* response.text;
    return { status: response.status, body: text === "" ? undefined : JSON.parse(text) };
  });

/**
 * Open a live read. The status arrives once the read has its first value, so
 * the read is subscribed when this returns; `take(n)` collects the next `n`
 * SSE events, each with its parsed `data`.
 */
const listen = (path: string, options: SendOptions = {}) =>
  Effect.gen(function* () {
    const response = yield* execute("GET", path, options);
    const contentType = response.headers["content-type"];
    const take = (n: number) =>
      response.stream.pipe(
        Stream.decodeText,
        Stream.pipeThroughChannel(Sse.decode()),
        Stream.take(n),
        Stream.map((event) => ({ event: event.event, data: JSON.parse(event.data) })),
        Stream.runCollect,
        Effect.timeout("5 seconds"),
      );
    return { status: response.status, contentType, take };
  });

const at = "2026-10-25T12:00:00.000Z";

// ---------------------------------------------------------------- tests

describe("Domain toHttpApi", { tags: ["unit", "local"] }, () => {
  it.live("a command endpoint runs the command and answers with its receipt", () =>
    Effect.gen(function* () {
      const { status, body } = yield* send("POST", "/Deposit", {
        owner: "sam",
        body: { target: "w-1", input: { amount: 40, at } },
      });
      expect(status).toBe(200);
      // The transform is decoded once on the way in and encoded once on the way out.
      expect(body).toEqual({ reply: { balance: 40, at }, stream: expect.any(String), version: 1 });
    }).pipe(Effect.provide(Served)),
  );

  it.live("a rejection answers with its status and its typed body", () =>
    Effect.gen(function* () {
      const over = yield* send("POST", "/Deposit", {
        owner: "sam",
        body: { target: "w-1", input: { amount: 500, at } },
      });
      // A declared rejection with no status of its own is a 422.
      expect(over).toEqual({ status: 422, body: { _tag: "OverLimit", limit: 100 } });

      // The middleware runs as for any client, and its error keeps its annotated status.
      const anonymous = yield* send("POST", "/Deposit", {
        body: { target: "w-1", input: { amount: 1, at } },
      });
      expect(anonymous).toEqual({ status: 401, body: { _tag: "Unauthenticated" } });

      // Input the command's schema refuses never reaches the model.
      const malformed = yield* send("POST", "/Deposit", {
        owner: "sam",
        body: { target: "w-1", input: { amount: "lots", at } },
      });
      expect(malformed.status).toBe(400);
    }).pipe(Effect.provide(Served)),
  );

  it.live("a read endpoint answers with the key's state, read after a write", () =>
    Effect.gen(function* () {
      const { body: receipt } = yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-2", input: { amount: 25, at } },
      });
      const read = yield* send(
        "GET",
        `/Balance/w-2?stream=${encodeURIComponent(receipt.stream)}&version=${receipt.version}`,
        { owner: "kim" },
      );
      expect(read).toEqual({ status: 200, body: { owner: "kim", balance: 25 } });

      // The view's `validate` runs, and its rejection takes the status `toHttpApi` gave it.
      const someoneElse = yield* send("GET", "/Balance/w-2", { owner: "sam" });
      expect(someoneElse).toEqual({ status: 403, body: { _tag: "NotOwner" } });

      // A key with nothing in it reads as `null`, like the Api's own `get`.
      const empty = yield* send("GET", "/Balance/w-9", { owner: "kim" });
      expect(empty).toEqual({ status: 200, body: null });

      // `stream` without `version` is not a position to wait for.
      const half = yield* send("GET", "/Balance/w-2?stream=x", { owner: "kim" });
      expect(half.status).toBe(400);
    }).pipe(Effect.provide(Served)),
  );

  it.live("a snapshot endpoint answers with the state and its cursor", () =>
    Effect.gen(function* () {
      yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-4", input: { amount: 7, at } },
      });
      const snapshot = yield* send("GET", "/Balance/w-4/snapshot", { owner: "kim" });
      expect(snapshot).toEqual({
        status: 200,
        body: { state: { owner: "kim", balance: 7 }, cursor: expect.any(Number) },
      });
      // Its own path: `get` still answers with the bare state.
      expect((yield* send("GET", "/Balance/w-4", { owner: "kim" })).body).toEqual({
        owner: "kim",
        balance: 7,
      });
    }).pipe(Effect.provide(Served)),
  );

  it.live("a watch endpoint streams the state, then every change, as Server-Sent Events", () =>
    Effect.gen(function* () {
      yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-5", input: { amount: 10, at } },
      });
      const watch = yield* listen("/Balance/w-5/watch", { owner: "kim" });
      expect(watch.status).toBe(200);
      expect(watch.contentType).toContain("text/event-stream");
      const events = yield* Effect.forkChild(watch.take(2));
      yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-5", input: { amount: 5, at } },
      });
      expect(yield* Fiber.join(events)).toEqual([
        {
          event: "message",
          data: { state: { owner: "kim", balance: 10 }, cursor: expect.any(Number) },
        },
        {
          event: "message",
          data: { state: { owner: "kim", balance: 15 }, cursor: expect.any(Number) },
        },
      ]);
    }).pipe(Effect.provide(Served)),
  );

  it.live("a live read's middleware and validate answer with their status before it streams", () =>
    Effect.gen(function* () {
      yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-6", input: { amount: 1, at } },
      });
      // The session middleware refuses a caller with no owner.
      expect(yield* send("GET", "/Balance/w-6/watch")).toEqual({
        status: 401,
        body: { _tag: "Unauthenticated" },
      });
      // The view's `validate` refuses someone else's wallet.
      expect(yield* send("GET", "/Balance/w-6/watch", { owner: "sam" })).toEqual({
        status: 403,
        body: { _tag: "NotOwner" },
      });
      // An aggregate's `read` middleware guards its events too.
      expect((yield* send("GET", "/Wallet/w-6/events")).status).toBe(401);
    }).pipe(Effect.provide(Served)),
  );

  it.live("a change validate refuses ends the stream with a typed failure event", () =>
    Effect.gen(function* () {
      yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-7", input: { amount: 1, at } },
      });
      const watch = yield* listen("/Balance/w-7/watch", { owner: "kim" });
      const events = yield* Effect.forkChild(watch.take(3));
      // Sam's deposit makes Sam the owner, so Kim may no longer read the wallet.
      yield* send("POST", "/Deposit", {
        owner: "sam",
        body: { target: "w-7", input: { amount: 1, at } },
      });
      const [first, failure, ...rest] = yield* Fiber.join(events);
      expect(first!.data.state).toEqual({ owner: "kim", balance: 1 });
      expect(failure!.event).toBe("effect/http-api/stream/failure");
      // A typed failure, not a defect: the Cause of the rejection `validate` returned.
      expect(failure!.data).toEqual([{ _tag: "Fail", error: { _tag: "NotOwner" } }]);
      // The failure ends the stream.
      expect(rest).toEqual([]);
    }).pipe(Effect.provide(Served)),
  );

  it.live("an events endpoint streams history, a CaughtUp frame, then live events", () =>
    Effect.gen(function* () {
      yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-8", input: { amount: 2, at } },
      });
      yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-8", input: { amount: 3, at } },
      });
      const all = yield* listen("/Wallet/w-8/events", { owner: "kim" });
      const history = yield* Effect.forkChild(all.take(4));
      yield* send("POST", "/Deposit", {
        owner: "kim",
        body: { target: "w-8", input: { amount: 4, at } },
      });
      const frames = (yield* Fiber.join(history)).map(({ data }) =>
        data._tag === "CaughtUp" ? "caught up" : data.event.amount,
      );
      expect(frames).toEqual([2, 3, "caught up", 4]);

      // `after` resumes from a cursor: only what came after it, then the frame.
      const [, second] = (yield* Fiber.join(history)).map(({ data }) => data);
      const resumed = yield* listen(`/Wallet/w-8/events?after=${second.envelope.seq}`, {
        owner: "kim",
      });
      const tail = (yield* resumed.take(2)).map(({ data }) =>
        data._tag === "CaughtUp" ? "caught up" : data.event.amount,
      );
      expect(tail).toEqual([4, "caught up"]);
    }).pipe(Effect.provide(Served)),
  );

  it.live("a middleware's client half never replaces the HTTP caller's headers", () =>
    Effect.gen(function* () {
      // The server holds a credential for its own calls; an HTTP caller signs as itself.
      expect(
        yield* send("POST", "/Sign", { owner: "alice", body: { target: "l-1", input: {} } }),
      ).toEqual({
        status: 200,
        body: { reply: { owner: "alice" }, stream: "Ledger/l-1", version: 1 },
      });
      // A caller without one is refused, not signed in as the server.
      expect(yield* send("POST", "/Sign", { body: { target: "l-2", input: {} } })).toEqual({
        status: 401,
        body: { _tag: "Unauthenticated" },
      });
    }).pipe(
      Effect.provide(
        (() => {
          const LedgerHttp = DomainHttp.toHttpApi(LedgerApi);
          return serve(LedgerHttp.api, LedgerHttp.layer);
        })(),
      ),
    ),
  );

  it.live("serves the group inside your own HttpApi, under its prefix", () =>
    Effect.gen(function* () {
      const deposit = yield* send("POST", "/v1/Deposit", {
        owner: "sam",
        body: { target: "w-3", input: { amount: 5, at } },
      });
      expect(deposit.status).toBe(200);
      expect((yield* send("POST", "/Deposit", { owner: "sam", body: {} })).status).toBe(404);
    }).pipe(Effect.provide(serve(AppApi, WalletHttp.layerFor(AppApi)))),
  );

  it.live("a smaller Api publishes only its own calls", () =>
    Effect.gen(function* () {
      const deposit = yield* send("POST", "/Deposit", {
        owner: "sam",
        body: { target: "w-10", input: { amount: 2, at } },
      });
      expect(deposit.status).toBe(200);
      expect((yield* send("GET", "/Wallet/w-10", { owner: "sam" })).status).toBe(404);
      expect((yield* send("GET", "/Balance/w-10/watch", { owner: "sam" })).status).toBe(404);
    }).pipe(
      Effect.provide(
        (() => {
          const DepositOnlyHttp = DomainHttp.toHttpApi(DepositOnlyApi);
          return serve(DepositOnlyHttp.api, DepositOnlyHttp.layer);
        })(),
      ),
    ),
  );

  it("the OpenAPI document lists each endpoint with its schemas", () => {
    const spec = OpenApi.fromApi(WalletHttp.api);
    expect(Object.keys(spec.paths).sort()).toEqual([
      "/Balance/{key}",
      "/Balance/{key}/events",
      "/Balance/{key}/list",
      "/Balance/{key}/snapshot",
      "/Balance/{key}/watch",
      "/Deposit",
      "/Wallet/{key}",
      "/Wallet/{key}/events",
      "/Wallet/{key}/watch",
    ]);

    const deposit = spec.paths["/Deposit"]!.post!;
    expect(deposit.operationId).toBe("WalletApi.Deposit");
    const body = JSON.stringify(deposit.requestBody);
    for (const field of ["target", "amount", "at", "commandId"]) expect(body).toContain(field);
    expect(Object.keys(deposit.responses).sort()).toEqual(["200", "401", "422"]);
    expect(JSON.stringify(deposit.responses["422"])).toContain("OverLimit");

    const balance = spec.paths["/Balance/{key}"]!.get!;
    expect(balance.parameters.map((p) => [p.name, p.in]).sort()).toEqual([
      ["key", "path"],
      ["stream", "query"],
      ["version", "query"],
    ]);
    // Waiting for a write can time out: `ConsistencyTimeout` is a 422.
    expect(Object.keys(balance.responses).sort()).toEqual(["200", "401", "403", "422"]);
    expect(JSON.stringify(balance.responses["422"])).toContain("ConsistencyTimeout");
    // A live read is an event stream, with its failures before it starts.
    const watch = spec.paths["/Balance/{key}/watch"]!.get!;
    expect(Object.keys(watch.responses["200"]!.content ?? {})).toEqual(["text/event-stream"]);
    expect(Object.keys(watch.responses).sort()).toEqual(["200", "401", "403"]);
    const events = spec.paths["/Wallet/{key}/events"]!.get!;
    expect(events.parameters.map((p) => [p.name, p.in]).sort()).toEqual([
      ["after", "query"],
      ["key", "path"],
    ]);

    // The schemas the document refers to, as components.
    const components = JSON.stringify(spec.components.schemas);
    for (const tag of ["OverLimit", "Unauthenticated", "NotOwner"]) {
      expect(components).toContain(tag);
    }
  });

  it("publishes every call the Api serves: commands, views, streams, then aggregates", () => {
    expect(
      Object.values(WalletHttp.group.endpoints).map((e) => [e.identifier, e.method, e.path]),
    ).toEqual([
      ["Deposit", "POST", "/Deposit"],
      ["Balance.get", "GET", "/Balance/:key"],
      ["Balance.watch", "GET", "/Balance/:key/watch"],
      ["Balance.events", "GET", "/Balance/:key/events"],
      ["Balance.list", "GET", "/Balance/:key/list"],
      ["Balance.snapshot", "GET", "/Balance/:key/snapshot"],
      ["Wallet.get", "GET", "/Wallet/:key"],
      ["Wallet.watch", "GET", "/Wallet/:key/watch"],
      ["Wallet.events", "GET", "/Wallet/:key/events"],
    ]);
  });

  it.live("layerFor an HttpApi without the group fails the Layer with a DefinitionError", () =>
    Effect.gen(function* () {
      /** The defect building the surface's Layer dies with. */
      const defectOf = (surface: { readonly layer: Layer.Layer<any, never, any> }) =>
        Layer.build(surface.layer).pipe(
          Effect.provide(Hosted),
          Effect.scoped,
          Effect.exit,
          Effect.map((exit) => (Exit.isFailure(exit) ? Cause.squash(exit.cause) : undefined)),
        );

      // `layerFor` an HttpApi that does not hold the group.
      const elsewhere = yield* defectOf({ layer: WalletHttp.layerFor(HttpApi.make("Elsewhere")) });
      expect(elsewhere).toMatchObject({
        _tag: "DefinitionError",
        message: "Elsewhere does not hold the WalletApi group: add it first",
      });
    }),
  );
});