@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/examples/build-events/test/notifier.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Deferred, Effect, Layer } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { KeyValueStore } from "effect/persistence";
+
+import { Http } from "../src/Api.js";
+import { Notices } from "../src/notifier/Notices.js";
+import { notifier } from "../src/notifier/routes.js";
+import { routes } from "../src/routes.js";
+import { inMemory, settled } from "./support/memory.js";
+
+describe("the notifier, by webhook", () => {
+  it.effect("is told of each failed build its member may see", () =>
+    Effect.gen(function* () {
+      // Both services in memory: build-events POSTs to the notifier's routes, and the notifier
+      // calls build-events. Each one's client reaches the other, a cycle no layer builds, so
+      // the notifier's client waits for build-events' to be handed over.
+      const toBuildEvents = yield* Deferred.make<HttpClient.HttpClient>();
+
+      const handedOver = Layer.succeed(
+        HttpClient.HttpClient,
+        HttpClient.make((request) =>
+          Effect.flatMap(Deferred.await(toBuildEvents), (client) =>
+            client.execute(request)
+          )
+        )
+      );
+
+      const notifierRoutes = notifier({
+        buildEvents: "http://build-events.internal",
+        token: "grace",
+        publicUrl: "https://hooks.example.com",
+      }).pipe(Layer.provide(handedOver));
+
+      // The notices and the watch's cursor are provided around both, so the test reads the ones
+      // the notifier writes.
+      const services = Testing.layer(routes).pipe(
+        Layer.provide(inMemory(Testing.layer(notifierRoutes))),
+        Layer.provideMerge(
+          Layer.mergeAll(Notices.layerMemory, KeyValueStore.layerMemory)
+        )
+      );
+
+      yield* Effect.gen(function* () {
+        yield* Deferred.succeed(toBuildEvents, yield* HttpClient.HttpClient);
+
+        const notices = yield* Notices;
+        const cursors = yield* KeyValueStore.KeyValueStore;
+
+        // The notifier's watch keeps a position once it is subscribed.
+        yield* settled(cursors.has("failed-builds"));
+
+        const ada = yield* ActionHttp.client(Http, {
+          transformClient: HttpClient.mapRequest(
+            HttpClientRequest.bearerToken("ada")
+          ),
+        });
+
+        yield* ada.finishBuild({ pipeline: "api", status: "failed" });
+        yield* ada.finishBuild({ pipeline: "web", status: "passed" });
+        // Each build finished notifies `build.finished`: it is POSTed at once, no poll awaited.
+        yield* ada.finishBuild({ pipeline: "web", status: "failed" });
+        yield* settled(Effect.map(notices.all, (all) => all.length > 0));
+
+        // grace sees the web pipeline alone, and the notifier asked for failures alone.
+        expect(yield* notices.all).toStrictEqual([
+          { id: "build-3", pipeline: "web", status: "failed" },
+        ]);
+
+        yield* ada.finishBuild({ pipeline: "web", status: "failed" });
+        yield* settled(Effect.map(notices.all, (all) => all.length > 1));
+
+        // Once build-4 is read, build-3 is handled: a restart resumes after the third build.
+        expect(yield* cursors.get("failed-builds")).toMatch(/:3$/u);
+      }).pipe(Effect.provide(services));
+    })
+  );
+});

package/examples/build-events/test/routes.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Effect, Fiber, Layer, Stream } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { TestClock } from "effect/testing";
+
+import { BuildFinished, FinishBuild } from "../src/builds/Builds.js";
+import { DeployRequested, RequestDeploy } from "../src/deploys/Deploys.js";
+import { Login } from "../src/identity/Identity.js";
+import { routes } from "../src/routes.js";
+import { inMemory } from "./support/memory.js";
+
+// What the wire adds: the real routes, behind their real authentication, answering in memory.
+// No port is opened. The subscriber is the token each client sends, as in production.
+const served = Testing.layer(routes).pipe(Layer.provide(inMemory()));
+
+const as = (token: string) => ({
+  authentication: Login,
+  transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+});
+
+describe("the service, over MCP", () => {
+  it.effect(
+    "pushes each build a member may see, as a tool call finishes it",
+    () =>
+      Effect.gen(function* () {
+        // A client lists the contracts it uses: the action it calls, the event it watches.
+        const ada = yield* ActionMcp.client([FinishBuild], as("ada"));
+        const grace = yield* ActionMcp.client([BuildFinished], as("grace"));
+
+        const watched = yield* grace
+          .watch(BuildFinished)
+          .pipe(Stream.take(1), Stream.runCollect, Effect.forkChild);
+
+        // The watch starts from now: let it take its first position before builds finish.
+        yield* TestClock.adjust("0 millis");
+        yield* ada.finishBuild({ pipeline: "api", status: "passed" });
+        // Each build finished notifies `build.finished`: the server asks the store at once, and
+        // pushes what it answers.
+        yield* ada.finishBuild({ pipeline: "web", status: "passed" });
+
+        expect(yield* Fiber.join(watched)).toMatchObject([
+          { _tag: "Occurrence", data: { id: "build-2", pipeline: "web" } },
+        ]);
+      }).pipe(Effect.provide(served))
+  );
+
+  it.effect(
+    "delivers deploy requests to a member that polls, standing them by meanwhile",
+    () =>
+      Effect.gen(function* () {
+        const ada = yield* ActionMcp.client([RequestDeploy], as("ada"));
+        const grace = yield* ActionMcp.client([DeployRequested], as("grace"));
+
+        // `mode: "poll"` asks with `events/poll`, as a client that cannot hold a stream does.
+        const polled = yield* grace
+          .watch(
+            DeployRequested,
+            { environment: "production" },
+            { mode: "poll" }
+          )
+          .pipe(Stream.take(1), Stream.runCollect, Effect.forkChild);
+
+        yield* TestClock.adjust("0 millis");
+
+        const deploy = yield* ada.requestDeploy({
+          environment: "production",
+          version: "1.0.9",
+        });
+
+        yield* TestClock.adjust("5 seconds");
+
+        // Between polls, grace stands by: the server holds the subscription hook for 5 minutes
+        // after each poll, keyed by grace's principal.
+        expect(deploy.approvers).toStrictEqual(["grace"]);
+        expect(yield* Fiber.join(polled)).toMatchObject([
+          {
+            _tag: "Occurrence",
+            data: { version: "1.0.9", approvers: ["grace"] },
+          },
+        ]);
+      }).pipe(Effect.provide(served))
+  );
+
+  it.effect("refuses a watch without a member's token", () =>
+    Effect.gen(function* () {
+      const stranger = yield* ActionMcp.client([BuildFinished], as("mallory"));
+
+      expect(
+        yield* Effect.flip(Stream.runDrain(stranger.watch(BuildFinished)))
+      ).toBeInstanceOf(Action.Unauthenticated);
+    }).pipe(Effect.provide(served))
+  );
+});

package/examples/build-events/test/rpc.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Effect, Fiber, Layer, Stream } from "effect";
+import { RpcClient, RpcSerialization } from "effect/rpc";
+import { TestClock } from "effect/testing";
+
+import { BuildFinished } from "../src/builds/Builds.js";
+import { routes } from "../src/routes.js";
+import { Rpc } from "../src/Rpc.js";
+import { inMemory } from "./support/memory.js";
+
+// Effect's RPC client over HTTP to the real routes in memory, with the serialization the
+// server frames streams with.
+const served = RpcClient.layerProtocolHttp({ url: "/rpc" }).pipe(
+  Layer.provide(RpcSerialization.layerNdjson),
+  Layer.provide(Testing.layer(routes)),
+  Layer.provide(inMemory())
+);
+
+// An rpc's credential is its own headers: each call or watch says who is calling.
+const as = (token: string) =>
+  RpcClient.withHeaders({ authorization: `Bearer ${token}` });
+
+describe("the service, over RPC", () => {
+  it.effect("streams each build a member may see, as a call finishes it", () =>
+    Effect.gen(function* () {
+      const client = yield* ActionRpc.client(Rpc);
+
+      const watched = yield* client
+        .watch(BuildFinished)
+        .pipe(Stream.take(1), Stream.runCollect, as("grace"), Effect.forkChild);
+
+      // The watch starts from now: let it take its first position before builds finish.
+      yield* TestClock.adjust("0 millis");
+      yield* client
+        .finishBuild({ pipeline: "api", status: "passed" })
+        .pipe(as("ada"));
+      yield* client
+        .finishBuild({ pipeline: "web", status: "passed" })
+        .pipe(as("ada"));
+
+      expect(yield* Fiber.join(watched)).toMatchObject([
+        { _tag: "Occurrence", data: { id: "build-2", pipeline: "web" } },
+      ]);
+    }).pipe(Effect.scoped, Effect.provide(served))
+  );
+
+  it.effect(
+    "refuses a watch without a member's token, as its typed failure",
+    () =>
+      Effect.gen(function* () {
+        const client = yield* ActionRpc.client(Rpc);
+
+        expect(
+          yield* Effect.flip(Stream.runDrain(client.watch(BuildFinished))).pipe(
+            as("mallory")
+          )
+        ).toBeInstanceOf(Action.Unauthenticated);
+      }).pipe(Effect.scoped, Effect.provide(served))
+  );
+
+  it.effect(
+    "streams each step of a build a member starts, then the build",
+    () =>
+      Effect.gen(function* () {
+        const client = yield* ActionRpc.client(Rpc);
+        const steps: string[] = [];
+
+        const build = yield* client
+          .startBuild(
+            { pipeline: "api" },
+            { onProgress: ({ step }) => Effect.sync(() => steps.push(step)) }
+          )
+          .pipe(as("ada"));
+
+        expect([steps, build]).toStrictEqual([
+          ["install", "build", "test"],
+          { id: "build-1", pipeline: "api", status: "passed" },
+        ]);
+      }).pipe(Effect.scoped, Effect.provide(served))
+  );
+});

package/examples/build-events/test/support/as.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+
+import { CurrentMember } from "../../src/identity/Identity.js";
+import { members } from "../../src/identity/members.js";
+
+// The caller of one call or subscription, as a server provides it per request.
+export const as = (member: keyof typeof members) =>
+  Effect.provideService(CurrentMember, members[member]);

package/examples/build-events/test/support/memory.ts

@@ -0,0 +1,43 @@
+import { setImmediate } from "node:timers/promises";
+
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Effect, Layer } from "effect";
+import type { HttpClient } from "effect/http";
+import { Dns } from "effect/net";
+import { KeyValueStore } from "effect/persistence";
+
+import { BuildStore } from "../../src/builds/store.js";
+import { Approvers } from "../../src/deploys/approvers.js";
+
+const unreached = async () => new Response(null, { status: 503 });
+
+// What the routes need, in memory: the stores, the events announced, and for webhook delivery a client, a resolver
+// and a store for the subscriptions. `subscribers` answers each POST in place of a member's server, and
+// hooks.example.com resolves to a public address: delivery refuses a private or loopback one.
+export const inMemory = <R = never>(
+  subscribers: Layer.Layer<HttpClient.HttpClient, never, R> = Testing.layer(
+    unreached
+  )
+) =>
+  Layer.mergeAll(
+    BuildStore.layerMemory,
+    Approvers.layerMemory,
+    Event.layerMemory,
+    subscribers,
+    Dns.layerStatic({ hosts: { "hooks.example.com": ["93.184.216.34"] } }),
+    KeyValueStore.layerMemory
+  );
+
+// Waits for `done` while requests in memory resolve: a subscription made through them runs on
+// promises the test clock does not drive.
+export const settled = <E, R>(done: Effect.Effect<boolean, E, R>) =>
+  Effect.repeat(
+    Effect.andThen(
+      Effect.promise(async () => {
+        await setImmediate();
+      }),
+      done
+    ),
+    { until: (finished) => finished, times: 200 }
+  );

package/examples/build-events/test/webhooks.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Effect, Layer, Queue, Schema } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+
+import { Http } from "../src/Api.js";
+import { routes } from "../src/routes.js";
+import { inMemory } from "./support/memory.js";
+
+// The subscriber's secret: `whsec_` and 24 to 64 random bytes in base64. The server signs each
+// POST with it, and the subscriber checks each POST it receives against it.
+const secret = `whsec_${Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("base64")}`;
+
+// A subscriber's check, as Standard Webhooks defines it: an HMAC-SHA256 of the id, the
+// timestamp and the body exactly as received, among the space-separated `v1,` signatures.
+const signed = async (request: Request, body: string) => {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    Buffer.from(secret.slice("whsec_".length), "base64"),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+
+  const signedContent = [
+    request.headers.get("webhook-id"),
+    request.headers.get("webhook-timestamp"),
+    body,
+  ].join(".");
+
+  const expected = Buffer.from(
+    await crypto.subtle.sign(
+      "HMAC",
+      key,
+      new TextEncoder().encode(signedContent)
+    )
+  ).toString("base64");
+
+  return (request.headers.get("webhook-signature") ?? "")
+    .split(" ")
+    .includes(`v1,${expected}`);
+};
+
+const Delivered = Schema.fromJsonString(
+  Schema.Record(Schema.String, Schema.Json)
+);
+
+interface Received {
+  readonly body: typeof Delivered.Type;
+  readonly signed: boolean;
+}
+
+// grace's server: it answers the verification POST by echoing its challenge, which proves it
+// asked for these deliveries, and acknowledges each delivery with a 2xx.
+const subscriber =
+  (received: Queue.Enqueue<Received>) => async (request: Request) => {
+    const text = await request.text();
+    const body = Schema.decodeSync(Delivered)(text);
+
+    Queue.offerUnsafe(received, { body, signed: await signed(request, text) });
+
+    return body["type"] === "verification"
+      ? Response.json({ challenge: body["challenge"] })
+      : new Response(null);
+  };
+
+const served = (received: Queue.Enqueue<Received>) =>
+  Testing.layer(routes).pipe(
+    Layer.provide(inMemory(Testing.layer(subscriber(received))))
+  );
+
+const Subscribed = Schema.Struct({
+  id: Schema.String,
+  refreshBefore: Schema.NullOr(Schema.String),
+  deliveryStatus: Schema.optional(
+    Schema.Struct({
+      active: Schema.Boolean,
+      lastError: Schema.NullOr(Schema.String),
+    })
+  ),
+});
+
+const subscribe = Effect.flatMap(HttpClient.HttpClient, (client) =>
+  client.execute(
+    HttpClientRequest.post("/api/events/build.finished/subscribe").pipe(
+      HttpClientRequest.bearerToken("grace"),
+      HttpClientRequest.bodyJsonUnsafe({
+        input: { status: "passed" },
+        delivery: { url: "https://hooks.example.com/grace", secret },
+      })
+    )
+  )
+).pipe(
+  Effect.flatMap((response) => response.json),
+  Effect.flatMap(Schema.decodeUnknownEffect(Subscribed))
+);
+
+describe("the service, by webhook", () => {
+  it.effect("POSTs each build a member may see to its callback, signed", () =>
+    Effect.flatMap(Queue.unbounded<Received>(), (received) =>
+      Effect.gen(function* () {
+        const ada = yield* ActionHttp.client(Http, {
+          transformClient: HttpClient.mapRequest(
+            HttpClientRequest.bearerToken("ada")
+          ),
+        });
+
+        // The answer names the subscription, which each POST's `x-mcp-subscription-id`
+        // carries, and when to subscribe again to keep it: one not refreshed by then ends.
+        const subscription = yield* subscribe;
+        const verification = yield* Queue.take(received);
+
+        yield* ada.finishBuild({ pipeline: "api", status: "passed" });
+        // Each build finished notifies `build.finished`: the server asks the store at once, and
+        // POSTs what it answers.
+        yield* ada.finishBuild({ pipeline: "web", status: "passed" });
+
+        // grace sees only the web pipeline.
+        const delivery = yield* Queue.take(received);
+
+        // The same request again refreshes the subscription, and answers how it is going.
+        const refreshed = yield* subscribe;
+
+        expect(verification).toMatchObject({
+          body: { type: "verification" },
+          signed: true,
+        });
+        expect(delivery).toMatchObject({
+          body: {
+            name: "build.finished",
+            data: { id: "build-2", pipeline: "web" },
+          },
+          signed: true,
+        });
+        expect(refreshed).toMatchObject({
+          id: subscription.id,
+          deliveryStatus: { active: true, lastError: null },
+        });
+      }).pipe(Effect.provide(served(received)))
+    )
+  );
+});