@gjermundgaraba/effect-actions 0.11.0 → 0.12.0

package/examples/kitchen-sink/src/seed.ts

@@ -0,0 +1,65 @@
+import { Buffer } from "node:buffer";
+import { NodeRuntime } from "@effect/platform-node";
+import { Config, Console, Effect, flow } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Http } from "./Api.js";
+
+// Entrypoint: `node --import tsx examples/kitchen-sink/src/seed.ts`, with the server running.
+// An Effect program calling the API with the binding's typed client: one method per action,
+// taking its input and answering its decoded success. DEMO ONLY: it files a first issue in
+// `acme` as `ada`, since the server's stores start empty.
+
+// A one-pixel PNG stands in for a screenshot.
+const screenshot = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
+  "base64",
+);
+
+const seed = Effect.gen(function* () {
+  const baseUrl = yield* Config.String("TRACKER_URL").pipe(
+    Config.withDefault("http://127.0.0.1:3000"),
+  );
+
+  const tracker = yield* ActionHttp.client(Http, {
+    baseUrl,
+    // Every request of this client: the token, and the header naming the workspace.
+    transformClient: HttpClient.mapRequest(
+      flow(
+        HttpClientRequest.bearerToken("ada"),
+        HttpClientRequest.setHeader("x-workspace", "acme"),
+      ),
+    ),
+  });
+
+  const issue = yield* tracker.createIssue({
+    title: "Crash on save",
+    body: "Saving an empty draft crashes the editor.",
+  });
+
+  // Over HTTP the image is JSON, its bytes in base64: the client encodes the `Uint8Array`.
+  const attachment = yield* tracker.attachImage({
+    issue: issue.id,
+    name: "crash.png",
+    image: { data: screenshot, mimeType: "image/png" },
+  });
+
+  yield* tracker.commentOnIssue({ id: issue.id, text: "Reproduced on 2.4.1." });
+
+  // No argument: `{}` is a valid input here, so `limit` takes its default and `status` none.
+  const { issues } = yield* tracker.listIssues();
+
+  yield* Console.log(`Filed ${issue.id} with attachment ${attachment.id}. Issues:`, issues);
+}).pipe(
+  // A declared error is a typed failure, the binding's and the verifier's included: each is
+  // handled by its tag. Anything else, such as an unreachable server, stays Effect's own.
+  Effect.catchTags({
+    RateLimited: ({ retryAfterSeconds }) =>
+      Console.error(`Write limit reached: retry in ${retryAfterSeconds}s.`),
+    QuotaExceeded: ({ retryAfterSeconds }) =>
+      Console.error(`Request quota spent: retry in ${retryAfterSeconds}s.`),
+    IssuerUnavailable: () => Console.error("The sign-in service is down: try again later."),
+  }),
+);
+
+seed.pipe(Effect.provide(FetchHttpClient.layer), NodeRuntime.runMain);

package/examples/kitchen-sink/src/server.ts

@@ -0,0 +1,62 @@
+import { createServer } from "node:http";
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { ByteSize, Config, Effect, Layer } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+import { RpcSerialization, RpcServer } from "effect/rpc";
+import { memory } from "./memory.js";
+import { adminRoutes, builders, publicRoutes, rpc } from "./routes.js";
+
+// Entrypoint: `node --import tsx examples/kitchen-sink/src/server.ts`.
+// The composition root of the server: two listeners over one set of builders and services.
+
+// The web app's rpcs over a WebSocket at `/rpc`: Node's HTTP server answers the upgrade. The
+// protocol is this entrypoint's choice, as the ports are. `rpc` leaves it open, so a test
+// serves the same layer over Effect's HTTP protocol.
+const socket = rpc.pipe(
+  Layer.provide(RpcServer.layerProtocolWebsocket({ path: "/rpc" })),
+  Layer.provide(RpcSerialization.layerJson),
+);
+
+const server = Layer.unwrap(
+  Effect.gen(function* () {
+    const publicPort = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
+    const adminPort = yield* Config.Port("ADMIN_PORT").pipe(Config.withDefault(3001));
+
+    const limit = ByteSize.mebibytes(1);
+
+    const listen = (port: number) =>
+      NodeHttpServer.layer(createServer, {
+        // This machine alone. A server others reach reads its host from config:
+        // `Config.String("HOST").pipe(Config.withDefault("127.0.0.1"))`.
+        host: "127.0.0.1",
+        port,
+        // A message on the WebSocket of `/rpc` is no request body, so the limit below does not
+        // bound it: Node's WebSocket server reads one of up to 100 MiB whole unless told
+        // otherwise. A larger one closes the socket (1009).
+        websocket: { maxPayload: Number(limit) },
+      });
+
+    return Layer.mergeAll(
+      // Two audiences, two listeners. Each `HttpRouter.serve` builds its routes in a layer
+      // graph of its own, with a router of its own: the public port can only ever reach the
+      // members' routes, and nothing built inside one is shared with the other. The socket
+      // is merged into the public port's graph, so it is a route of that router: the request
+      // policy, global to the router, refuses a foreign Origin's upgrade as it does a request,
+      // and the rpcs spend the quota the routes spend, built once.
+      HttpRouter.serve(Layer.merge(publicRoutes, socket)).pipe(Layer.provide(listen(publicPort))),
+      HttpRouter.serve(adminRoutes).pipe(Layer.provide(listen(adminPort))),
+    ).pipe(
+      // Request bodies have no size limit unless the host sets one. This covers every HTTP
+      // route of both ports, the MCP endpoint included.
+      Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, limit)),
+      // So what both ports share is provided outside both, once: the builders, then the
+      // services the builders, the verifiers and the quota are built from. A workspace an
+      // operator suspends on one port is thereby refused on the other.
+      Layer.provide(builders),
+      Layer.provide(memory),
+    );
+  }),
+);
+
+// NodeRuntime handles signals: the scoped layers stop both listeners and release the services.
+Layer.launch(server).pipe(NodeRuntime.runMain);

package/examples/kitchen-sink/src/stdio.ts

@@ -0,0 +1,34 @@
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { Effect } from "effect";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Tools } from "./Actions.js";
+import { attachments } from "./attachments/handlers.js";
+import { identity } from "./identity/handlers.js";
+import { CurrentMember } from "./identity/Identity.js";
+import { members } from "./identity/members.js";
+import { features } from "./issues/guide.js";
+import { issues } from "./issues/handlers.js";
+import { limiter, stores } from "./memory.js";
+import { status } from "./workspaces/handlers.js";
+import { WorkspaceRegistry } from "./workspaces/registry.js";
+
+// Entrypoint: an MCP server a local agent starts as a subprocess, such as
+// `claude mcp add tracker -- node --import tsx examples/kitchen-sink/src/stdio.ts`.
+// It lists the implementations it serves itself, and imports nothing of the HTTP router. They
+// are those of the `/mcp` endpoint, with its tools and features and the same `authorize`.
+// stdio is a local surface: it takes no `authentication`, since no token arrives.
+ActionMcp.runStdio([status, identity, issues, attachments], {
+  name: "tracker",
+  version: "1.0.0",
+  actions: Tools,
+  features,
+}).pipe(
+  // The host names the caller itself, around every call. DEMO ONLY: a real host reads who
+  // started it, from its own login or configuration.
+  Effect.provideService(CurrentMember, members.ada),
+  Effect.provide([NodeStdio.layer, stores, limiter, WorkspaceRegistry.layerMemory]),
+  // stdout carries the protocol alone, so logs and failures go to stderr. Applied last.
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
+);

package/examples/kitchen-sink/src/workspaces/Workspaces.ts

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+export const Workspace = Schema.Struct({
+  slug: Schema.String,
+  name: Schema.String,
+  suspended: Schema.Boolean,
+});
+
+export type Workspace = typeof Workspace.Type;
+
+export class WorkspaceNotFound extends Schema.TaggedError<WorkspaceNotFound>()(
+  "WorkspaceNotFound",
+  { slug: Schema.String },
+  { httpApiStatus: 404 },
+) {}
+
+// Public: `caller: Action.Anyone`. It answers before anyone has signed in, on every surface,
+// so it tells nothing that depends on the caller.
+export const GetStatus = Action.make("getStatus", {
+  description:
+    "Report whether the tracker is up, since which start, and how many workspaces it serves.",
+  // `instance` names one start of the process: it changes on a restart, and with it the demo's
+  // memory stores are empty again.
+  success: { service: Schema.String, instance: Schema.String, workspaces: Schema.Finite },
+  readOnly: true,
+  caller: Action.Anyone,
+});

package/examples/kitchen-sink/src/workspaces/handlers.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { WorkspaceRegistry } from "./registry.js";
+import { GetStatus } from "./Workspaces.js";
+
+// One action, one handler, built once: the builder yields the registry at startup, and names
+// this start of the process. Both ports serve this implementation, so what the builder makes
+// tells whether they share one run of it (see `builders` in routes.ts). A public action takes
+// no `authorize`: nothing would run it.
+export const status = Action.implement(
+  GetStatus,
+  Effect.gen(function* () {
+    const registry = yield* WorkspaceRegistry;
+    const instance = crypto.randomUUID();
+
+    return () =>
+      Effect.map(registry.list, (workspaces) => ({
+        service: "tracker",
+        instance,
+        workspaces: workspaces.length,
+      }));
+  }),
+);

package/examples/kitchen-sink/src/workspaces/registry.ts

@@ -0,0 +1,46 @@
+import { Context, Effect, Layer } from "effect";
+import { type Workspace, WorkspaceNotFound } from "./Workspaces.js";
+
+/**
+ * The tenants. Operators list and suspend them on the admin port; authentication reads the
+ * suspension on the public one, so both servers must share this one service.
+ */
+export class WorkspaceRegistry extends Context.Service<
+  WorkspaceRegistry,
+  {
+    readonly list: Effect.Effect<ReadonlyArray<Workspace>>;
+    readonly get: (slug: string) => Effect.Effect<Workspace, WorkspaceNotFound>;
+    readonly setSuspended: (
+      slug: string,
+      suspended: boolean,
+    ) => Effect.Effect<Workspace, WorkspaceNotFound>;
+  }
+>()("tracker/WorkspaceRegistry") {
+  // DEMO ONLY: two workspaces in memory. A real registry is another Layer of this service.
+  static readonly layerMemory = Layer.sync(WorkspaceRegistry, () => {
+    const workspaces = new Map<string, Workspace>([
+      ["acme", { slug: "acme", name: "Acme", suspended: false }],
+      ["globex", { slug: "globex", name: "Globex", suspended: false }],
+    ]);
+
+    const get = Effect.fn("WorkspaceRegistry.get")(function* (slug: string) {
+      const workspace = workspaces.get(slug);
+
+      if (workspace === undefined) return yield* new WorkspaceNotFound({ slug });
+
+      return workspace;
+    });
+
+    return WorkspaceRegistry.of({
+      list: Effect.sync(() => Array.from(workspaces.values())),
+      get,
+      setSuspended: Effect.fn("WorkspaceRegistry.setSuspended")(function* (slug, suspended) {
+        const workspace = { ...(yield* get(slug)), suspended };
+
+        workspaces.set(slug, workspace);
+
+        return workspace;
+      }),
+    });
+  });
+}

package/examples/kitchen-sink/src/workspaces/tenant.ts

@@ -0,0 +1,17 @@
+import { Context, Effect, Option } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+
+/**
+ * The workspace a request addresses, from its `X-Workspace` header. It is request context, not
+ * an identity: the verifier reads it to decide which of an account's memberships the caller
+ * acts in. Handlers never read it; they read the workspace of the authenticated member.
+ */
+export class Tenant extends Context.Service<Tenant, Option.Option<string>>()("tracker/Tenant") {}
+
+// Native router middleware. It provides `Tenant` to whatever it is provided to, per request:
+// to the verifier too, when it is provided after the authentication (see routes.ts).
+export const resolveTenant = HttpRouter.middleware<{ provides: Tenant }>()((route) =>
+  Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) =>
+    Effect.provideService(route, Tenant, Option.fromNullishOr(request.headers["x-workspace"])),
+  ),
+);

package/examples/kitchen-sink/test/admin/admin.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Operator } from "../../src/admin/Admin.js";
+import { Grants } from "../../src/admin/grants.js";
+import { admin } from "../../src/admin/handlers.js";
+import { AdminHttp } from "../../src/Api.js";
+import { memory } from "../../src/memory.js";
+import { adminRoutes } from "../../src/routes.js";
+import { WorkspaceRegistry } from "../../src/workspaces/registry.js";
+
+const served = Testing.layer(adminRoutes).pipe(Layer.provide(memory));
+
+const key = (operatorKey: string) => ({
+  transformClient: HttpClient.mapRequest(
+    HttpClientRequest.setHeader("x-operator-key", operatorKey),
+  ),
+});
+
+describe("the operators", () => {
+  it.effect("are authorized by the grants stored for their key", () =>
+    Effect.gen(function* () {
+      const support = yield* ActionHttp.client(AdminHttp, key("support-key"));
+      const ops = yield* ActionHttp.client(AdminHttp, key("ops-key"));
+
+      expect((yield* support.listWorkspaces()).workspaces).toHaveLength(2);
+
+      // A key cannot step up, so the refusal names no scope: a plain 403.
+      const refused = yield* Effect.flip(support.suspendWorkspace({ workspace: "acme" }));
+
+      expect(refused).toBeInstanceOf(Action.Forbidden);
+      expect(refused).not.toHaveProperty("scopes");
+      expect(refused.message).toBe("Requires the workspaces:suspend grant.");
+      expect(yield* ops.suspendWorkspace({ workspace: "acme" })).toMatchObject({ suspended: true });
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("are not the members: a member's token is no credential here", () =>
+    Effect.gen(function* () {
+      const member = yield* ActionHttp.client(AdminHttp, {
+        transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken("ada")),
+      });
+
+      expect(yield* Effect.flip(member.listWorkspaces())).toBeInstanceOf(Action.Unauthenticated);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("include the console's trusted operator, admitted by the same rule in process", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(admin);
+      const suspend = client.suspendWorkspace({ workspace: "globex" });
+
+      // No grants are stored for either: only the operator a host supplies is trusted.
+      expect(
+        yield* suspend.pipe(Effect.provideService(Operator, { id: "console", trusted: true })),
+      ).toMatchObject({ suspended: true });
+      expect(
+        yield* Effect.flip(
+          suspend.pipe(Effect.provideService(Operator, { id: "intern", trusted: false })),
+        ),
+      ).toBeInstanceOf(Action.Forbidden);
+    }).pipe(Effect.provide([WorkspaceRegistry.layerMemory, Grants.layerDemo])),
+  );
+});