@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/examples/build-events/src/builds/handlers.ts

@@ -0,0 +1,58 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import {
+  BuildFinished,
+  FinishBuild,
+  PipelineStatus,
+  StartBuild,
+} from "./Builds.js";
+import type { Build } from "./Builds.js";
+import { BuildStore } from "./store.js";
+
+// DEMO ONLY: each step passes at once. A runner's steps take their time, which is why a caller
+// wants to see them.
+const steps = ["install", "build", "test"];
+
+export const builds = Action.implement(
+  [FinishBuild, StartBuild],
+  Effect.gen(function* () {
+    const store = yield* BuildStore;
+    const events = yield* Event.Events;
+
+    // `build.finished` is a check source over the store: write the build there first, then wake
+    // its subscribers, who read it now rather than at their next poll. `pipeline.status` is a
+    // current source: the notify moves its pipeline's revision, so its subscribers alone read it.
+    const finished = (build: Effect.Effect<Build>) =>
+      Effect.tap(build, ({ pipeline }) =>
+        Effect.andThen(
+          events.notify(BuildFinished),
+          events.notify(PipelineStatus, { key: pipeline })
+        )
+      );
+
+    return {
+      finishBuild: ({ pipeline, status }) =>
+        finished(store.finish(pipeline, status, [status])),
+      // `progress` never waits for the caller: the build runs at its own pace.
+      startBuild: ({ pipeline }, { progress }) =>
+        Effect.andThen(
+          Effect.forEach(
+            steps,
+            (step, done) => progress({ step, done, total: steps.length }),
+            {
+              discard: true,
+            }
+          ),
+          finished(
+            store.finish(pipeline, "passed", [
+              ...steps.map((step) => `${step}: passed`),
+              "passed",
+            ])
+          )
+        ),
+    };
+  }),
+  { authorize: Action.allowAll }
+);

package/examples/build-events/src/builds/log.ts

@@ -0,0 +1,30 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect, Stream } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { TailLog } from "./Builds.js";
+import { BuildStore } from "./store.js";
+
+export const logs = Action.implement(
+  TailLog,
+  Effect.gen(function* () {
+    const store = yield* BuildStore;
+
+    // The handler returns a `Stream`, run in a scope of its own that closes when the caller
+    // stops reading, so what it acquires is released then.
+    return ({ buildId }) =>
+      Stream.unwrap(
+        Effect.gen(function* () {
+          const member = yield* CurrentMember;
+          // A failure before the first line, `BuildNotFound` here, fails the call as an action
+          // answering one value fails, a 404 over HTTP; one after a line ends the stream, the
+          // lines before it already read.
+          const log = yield* store.logOf(member.pipelines, buildId);
+
+          return Stream.fromIterable(log.map((line) => ({ line })));
+        })
+      );
+  }),
+  // Which builds a member may read is the store's check, by pipeline.
+  { authorize: Action.allowAll }
+);

package/examples/build-events/src/builds/status.ts

@@ -0,0 +1,28 @@
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { PipelineStatus } from "./Builds.js";
+import { BuildStore } from "./store.js";
+
+// A current source: the value as it is, which the library sends first and again after each
+// notify reaching the subscriber's key, keeping the revision that tells them apart, so the store
+// keeps no cursor for it. The key is the pipeline: a build of another wakes no one here.
+export const statusEvents = Event.implement(
+  PipelineStatus,
+  Effect.gen(function* () {
+    const store = yield* BuildStore;
+
+    return {
+      current: ({ pipeline }) =>
+        Effect.gen(function* () {
+          const member = yield* CurrentMember;
+
+          return { status: yield* store.statusOf(member.pipelines, pipeline) };
+        }),
+      key: ({ pipeline }) => pipeline,
+    };
+  }),
+  // Every member may watch; which pipelines each sees is the store's check.
+  { authorize: Event.allowAll }
+);

package/examples/build-events/src/builds/store.ts

@@ -0,0 +1,130 @@
+import { Context, Effect, Layer } from "effect";
+
+import { BuildNotFound } from "./Builds.js";
+import type { Build } from "./Builds.js";
+
+/** One page of the builds finished since a cursor. */
+export interface Finished {
+  readonly builds: readonly Build[];
+  readonly cursor: string;
+  readonly hasMore: boolean;
+  /** Whether builds before the page may be missing: the cursor was not one of this store's. */
+  readonly truncated: boolean;
+  /** The store's epoch: a build's id is unique within it, and a restarted memory store starts another. */
+  readonly epoch: string;
+}
+
+// The position a cursor of `epoch` names, among `length` builds; none for another epoch's cursor
+// or one that is not a cursor at all.
+const positionOf = (
+  epoch: string,
+  cursor: string,
+  length: number
+): number | undefined => {
+  const [of, at] = cursor.split(":");
+  const position = Number(at);
+
+  return of === epoch &&
+    Number.isInteger(position) &&
+    position >= 0 &&
+    position <= length
+    ? position
+    : undefined;
+};
+
+/**
+ * Where finished builds are recorded, in the order they finished. Which pipelines a member may
+ * see is checked here, in the data access, so no subscription can skip it.
+ */
+export class BuildStore extends Context.Service<
+  BuildStore,
+  {
+    /** Record a build that finished, with the lines its log holds. */
+    readonly finish: (
+      pipeline: string,
+      status: Build["status"],
+      log: readonly string[]
+    ) => Effect.Effect<Build>;
+    /** The log of build `buildId`, which must be one of `pipelines`. */
+    readonly logOf: (
+      pipelines: readonly string[],
+      buildId: string
+    ) => Effect.Effect<readonly string[], BuildNotFound>;
+    /**
+     * The builds of `pipelines` finished after `cursor`, at most `limit`; a `null` cursor is
+     * the current position, with none.
+     */
+    readonly finishedSince: (
+      pipelines: readonly string[],
+      cursor: string | null,
+      limit: number
+    ) => Effect.Effect<Finished>;
+    /** How `pipeline`'s last build ended, `null` before any did or where it is not of `pipelines`. */
+    readonly statusOf: (
+      pipelines: readonly string[],
+      pipeline: string
+    ) => Effect.Effect<Build["status"] | null>;
+  }
+>()("build-events/BuildStore") {
+  // DEMO ONLY: builds live in this process's memory, so a restart forgets them and numbers them
+  // from 1 again. Its cursors carry an epoch of their own, so one from before the restart, or one
+  // it never gave, is answered from the start as `truncated`: the subscriber is sent a gap, never
+  // a silent loss. In a database the cursor is the position in its own change feed, such as a
+  // sequence column, so a subscriber resumes after a restart.
+  static readonly layerMemory = Layer.sync(BuildStore, () => {
+    const epoch = crypto.randomUUID();
+    const finished: Build[] = [];
+    const logs = new Map<string, readonly string[]>();
+
+    return BuildStore.of({
+      finish: (pipeline, status, log) =>
+        Effect.sync(() => {
+          const build = {
+            id: `build-${finished.length + 1}`,
+            pipeline,
+            status,
+          };
+
+          finished.push(build);
+          logs.set(build.id, log);
+
+          return build;
+        }),
+      logOf: (pipelines, buildId) => {
+        const build = finished.find(({ id }) => id === buildId);
+        const log = logs.get(buildId);
+
+        return build === undefined ||
+          log === undefined ||
+          !pipelines.includes(build.pipeline)
+          ? Effect.fail(new BuildNotFound({ buildId }))
+          : Effect.succeed(log);
+      },
+      finishedSince: (pipelines, cursor, limit) =>
+        Effect.sync(() => {
+          const at =
+            cursor === null
+              ? finished.length
+              : positionOf(epoch, cursor, finished.length);
+
+          const from = at ?? 0;
+          const next = finished.slice(from, from + limit);
+
+          return {
+            builds: next.filter((build) => pipelines.includes(build.pipeline)),
+            cursor: `${epoch}:${from + next.length}`,
+            hasMore: from + next.length < finished.length,
+            truncated: at === undefined,
+            epoch,
+          };
+        }),
+      statusOf: (pipelines, pipeline) =>
+        Effect.sync(() =>
+          pipelines.includes(pipeline)
+            ? (finished.findLast((build) => build.pipeline === pipeline)
+                ?.status ?? null)
+            : null
+        ),
+    });
+  });
+}

package/examples/build-events/src/cli.ts

@@ -0,0 +1,18 @@
+import {
+  NodeHttpClient,
+  NodeRuntime,
+  NodeServices,
+} from "@effect/platform-node";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { Effect } from "effect";
+import { Command } from "effect/cli";
+
+import { commands } from "./commands.js";
+
+// Entrypoint: `BUILDS_TOKEN=grace node --import tsx examples/build-events/src/cli.ts watch
+// build.finished`, with server.ts running.
+Command.run(commands, { version: "1.0.0" }).pipe(
+  Effect.provide([NodeHttpClient.layerUndici, NodeServices.layer]),
+  ActionCli.logToStderr,
+  NodeRuntime.runMain()
+);

package/examples/build-events/src/commands.ts

@@ -0,0 +1,32 @@
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Config, Effect } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+
+import { Http } from "./Api.js";
+
+// The binding's client, connected to where the server is and as which member, both read from
+// config when a command runs.
+const api = Effect.gen(function* () {
+  const baseUrl = yield* Config.String("BUILDS_URL").pipe(
+    Config.withDefault("http://127.0.0.1:3000")
+  );
+
+  const token = yield* Config.Redacted("BUILDS_TOKEN");
+
+  return yield* ActionHttp.client(Http, {
+    baseUrl,
+    transformClient: HttpClient.mapRequest(
+      HttpClientRequest.bearerToken(token)
+    ),
+  });
+});
+
+// A command per action, and `watch <event>` per event type: `builds watch build.finished
+// --pipeline api` holds the event's stream open and prints each occurrence as a line of JSON,
+// its `cursor` included, until it is stopped. `--cursor <cursor>` resumes after that line;
+// omitted, the watch starts from now. The lines pipe into `jq` or a script as they come.
+// `builds start-build --pipeline api` prints each step as a line of JSON on stderr as it
+// starts, and the build on stdout, which a pipe reads alone. `builds tail-log --build-id
+// build-1` prints each line of its log as a line of JSON as it arrives.
+export const commands = ActionCli.remote(Http, { name: "builds", client: api });

package/examples/build-events/src/deploys/Deploys.ts

@@ -0,0 +1,44 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Schema } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+
+export const Environment = Schema.Literals(["staging", "production"]).annotate({
+  description: "Where to deploy.",
+});
+
+export type Environment = typeof Environment.Type;
+
+export const Deploy = Schema.Struct({
+  id: Schema.String,
+  environment: Environment,
+  version: Schema.String,
+  requestedBy: Schema.String,
+  approvers: Schema.Array(Schema.String).annotate({
+    description:
+      "The members watching its environment when it was requested, asked to approve it.",
+  }),
+});
+
+export type Deploy = typeof Deploy.Type;
+
+export const RequestDeploy = Action.make("requestDeploy", {
+  description: "Ask for a version to be deployed to an environment.",
+  input: { environment: Environment, version: Schema.String },
+  success: Deploy,
+  readOnly: false,
+  caller: CurrentMember,
+});
+
+export const DeployRequested = Event.make("deploy.requested", {
+  description:
+    "Someone asked for a deploy. Watching an environment stands you by to approve its deploys.",
+  input: {
+    environment: Schema.optional(Environment).annotate({
+      description: "Only deploys to here.",
+    }),
+  },
+  payload: Deploy,
+  caller: CurrentMember,
+});

package/examples/build-events/src/deploys/approvers.ts

@@ -0,0 +1,55 @@
+import { Context, Effect, Layer } from "effect";
+import type { Scope } from "effect";
+
+import type { Environment } from "./Deploys.js";
+
+/** Who stands by to approve deploys, and to which environment. */
+export class Approvers extends Context.Service<
+  Approvers,
+  {
+    /** Stands `member` by to approve deploys to `environment`, every one where undefined, until the scope closes. */
+    readonly standBy: (
+      environment: Environment | undefined,
+      member: string
+    ) => Effect.Effect<void, never, Scope.Scope>;
+    readonly standingBy: (
+      environment: Environment
+    ) => Effect.Effect<readonly string[]>;
+  }
+>()("build-events/Approvers") {
+  // DEMO ONLY: approvers live in this process's memory, where a real one is a rota in a store.
+  static readonly layerMemory = Layer.sync(Approvers, () => {
+    const approvers: Array<{
+      readonly environment: Environment | undefined;
+      readonly member: string;
+    }> = [];
+
+    return Approvers.of({
+      standBy: (environment, member) =>
+        Effect.acquireRelease(
+          Effect.sync(() => {
+            const standing = { environment, member };
+
+            approvers.push(standing);
+
+            return standing;
+          }),
+          (standing) =>
+            Effect.sync(() => approvers.splice(approvers.indexOf(standing), 1))
+        ),
+      standingBy: (environment) =>
+        Effect.sync(() => [
+          ...new Set(
+            approvers
+              .values()
+              .filter(
+                (each) =>
+                  each.environment === undefined ||
+                  each.environment === environment
+              )
+              .map((each) => each.member)
+          ),
+        ]),
+    });
+  });
+}

package/examples/build-events/src/deploys/events.ts

@@ -0,0 +1,32 @@
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { Approvers } from "./approvers.js";
+import { DeployRequested } from "./Deploys.js";
+
+// A log source, for occurrences nothing else keeps: the library keeps each one `requestDeploy`
+// publishes, for 10 minutes and at most 10,000 of them by default, and gives each subscriber
+// what its `match` accepts. A subscriber resuming from a cursor gets what the log still holds:
+// after a restart, or once its occurrences are dropped, a gap first. An upstream you can ask
+// "what since?", such as a table, is a check source.
+export const deployEvents = Event.implement(
+  DeployRequested,
+  Effect.gen(function* () {
+    const approvers = yield* Approvers;
+
+    return {
+      log: {},
+      match: ({ environment }, deploy) =>
+        environment === undefined || deploy.environment === environment,
+      // Set up while each subscription lasts, as the subscriber: a stream's as long as it is
+      // read, a poll's until 5 minutes after its last poll. It may run again for one
+      // subscription, after a restart, so standing by twice must be harmless.
+      subscription: ({ environment }) =>
+        Effect.flatMap(CurrentMember, (member) =>
+          approvers.standBy(environment, member.id)
+        ),
+    };
+  }),
+  { authorize: Event.allowAll }
+);

package/examples/build-events/src/deploys/handlers.ts

@@ -0,0 +1,38 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { Approvers } from "./approvers.js";
+import { DeployRequested, RequestDeploy } from "./Deploys.js";
+
+export const deploys = Action.implement(
+  RequestDeploy,
+  Effect.gen(function* () {
+    const approvers = yield* Approvers;
+    const events = yield* Event.Events;
+
+    return ({ environment, version }) =>
+      Effect.gen(function* () {
+        const member = yield* CurrentMember;
+
+        const deploy = {
+          id: crypto.randomUUID(),
+          environment,
+          version,
+          requestedBy: member.id,
+          approvers: yield* approvers.standingBy(environment),
+        };
+
+        // Nothing else keeps a deploy request, so `deploy.requested` is a log source: the
+        // library keeps what is published here, and delivers it to each subscriber at once.
+        yield* events.publish(DeployRequested, {
+          eventId: deploy.id,
+          data: deploy,
+        });
+
+        return deploy;
+      });
+  }),
+  { authorize: Action.allowAll }
+);

package/examples/build-events/src/identity/Identity.ts

@@ -0,0 +1,29 @@
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Context, Schema } from "effect";
+
+/** A member, and the pipelines whose builds it may see. */
+export const Member = Schema.Struct({
+  id: Schema.String,
+  pipelines: Schema.Array(Schema.String),
+});
+
+export type Member = typeof Member.Type;
+
+/**
+ * Who is subscribing or calling. Every event and action here declares it, `caller:
+ * CurrentMember`; authentication provides it per request.
+ */
+export class CurrentMember extends Context.Service<CurrentMember, Member>()(
+  "build-events/CurrentMember"
+) {}
+
+// How a remote caller proves it is a member: a bearer token. Clients import this descriptor
+// with the contracts; its verifier stays on the server. `principal` names a member as one
+// subscriber: a poll arrives as a request among others, and a surface keys what it holds
+// between polls, deploy.requested's standing by, by it. Without it, MCP and HTTP refuse to
+// serve that event, and no event is offered by webhook. `schema` keeps a webhook subscriber's
+// identity, so the deliveries a restart restores run as that member.
+export const Login = Authentication.make("build-events.Login", CurrentMember, {
+  principal: (member) => member.id,
+  schema: Member,
+});

package/examples/build-events/src/identity/members.ts

@@ -0,0 +1,7 @@
+import type { Member } from "./Identity.js";
+
+// DEMO ONLY: the members who may sign in, each under a token that is their name.
+export const members = {
+  ada: { id: "ada", pipelines: ["api", "web"] },
+  grace: { id: "grace", pipelines: ["web"] },
+} as const satisfies Readonly<Record<string, Member>>;

package/examples/build-events/src/identity/verifier.ts

@@ -0,0 +1,22 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Effect, Redacted } from "effect";
+
+import { Login } from "./Identity.js";
+import { members } from "./members.js";
+
+const isMember = (token: string): token is keyof typeof members =>
+  Object.hasOwn(members, token);
+
+// DEMO ONLY: a token is a member's name. A real verifier checks a signed token with your
+// authorization server's library. An unknown token is the built-in `Unauthenticated`, which
+// every client decodes, a watch's included.
+export const authenticate = Authentication.layer(Login, (token) => {
+  const name = Redacted.value(token);
+
+  return isMember(name)
+    ? Effect.succeed(members[name])
+    : Effect.fail(
+        new Action.Unauthenticated({ message: "Unknown demo token." })
+      );
+});

package/examples/build-events/src/notifier/Notices.ts

@@ -0,0 +1,26 @@
+import { Context, Effect, Layer } from "effect";
+
+import type { Build } from "../builds/Builds.js";
+
+/** The failed builds the notifier was told of, in the order it was told. */
+export class Notices extends Context.Service<
+  Notices,
+  {
+    readonly add: (build: Build) => Effect.Effect<void>;
+    readonly all: Effect.Effect<readonly Build[]>;
+  }
+>()("build-events/Notices") {
+  // DEMO ONLY: notices live in this process's memory; a notifier sends each on, to a chat or a
+  // pager, as it arrives.
+  static readonly layerMemory = Layer.sync(Notices, () => {
+    const notices: Build[] = [];
+
+    return Notices.of({
+      add: (build) =>
+        Effect.sync(() => {
+          notices.push(build);
+        }),
+      all: Effect.sync(() => [...notices]),
+    });
+  });
+}

package/examples/build-events/src/notifier/routes.ts

@@ -0,0 +1,71 @@
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Webhook from "@gjermundgaraba/effect-actions/Webhook";
+import { Effect, Layer, Predicate, Stream } from "effect";
+import type { Redacted } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { KeyValueStore } from "effect/persistence";
+
+import { Http } from "../Api.js";
+import { BuildFinished } from "../builds/Builds.js";
+import { Notices } from "./Notices.js";
+
+/** Where build-events is, who the notifier signs in as there, and where it is reached itself. */
+export interface NotifierOptions {
+  readonly buildEvents: string;
+  readonly token: string | Redacted.Redacted;
+  /** This process's public https origin, which build-events POSTs to. */
+  readonly publicUrl: string;
+}
+
+// The route build-events POSTs each failed build to, where the watch below reads them: the
+// watch's delivery appends its path to this process's public URL.
+const receiver = Webhook.layerReceiver({ path: "/hooks/builds" });
+
+// A second service, the notifier: it watches build.finished for failures by webhook, the
+// server POSTing each to it, rather than holding a stream open to build-events.
+const watcher = ({ buildEvents, token, publicUrl }: NotifierOptions) =>
+  Layer.effectDiscard(
+    Effect.gen(function* () {
+      const notices = yield* Notices;
+
+      const builds = yield* ActionHttp.client(Http, {
+        baseUrl: buildEvents,
+        transformClient: HttpClient.mapRequest(
+          HttpClientRequest.bearerToken(token)
+        ),
+      });
+
+      yield* Effect.forkScoped(
+        builds
+          .watch(
+            BuildFinished,
+            { status: "failed" },
+            {
+              mode: Webhook.delivery({ baseUrl: publicUrl }),
+              // Where it reached is kept, so a restart resumes there; failures the server no
+              // longer keeps arrive as a Gap instead.
+              resume: {
+                store: yield* KeyValueStore.KeyValueStore,
+                key: "failed-builds",
+              },
+            }
+          )
+          .pipe(
+            // A Gap says failures were missed, which no notice can name: it is logged, for an
+            // operator to look the builds up.
+            Stream.runForEach((received) =>
+              Predicate.isTagged(received, "Occurrence")
+                ? notices.add(received.data)
+                : Effect.logWarning("Failed builds were missed", received)
+            ),
+            // A failure no reconnect outlasts, such as a wrong PUBLIC_URL or a revoked token,
+            // ends the watch: it is logged here, for a deployment to alert on or restart by.
+            Effect.tapCause(Effect.logError)
+          )
+      );
+    })
+  );
+
+/** The notifier's routes: the receiver, and the watch reading from that same receiver. */
+export const notifier = (options: NotifierOptions) =>
+  watcher(options).pipe(Layer.provideMerge(receiver));