@alchemy.run/effect-cluster 0.0.0-stage → 2.0.0-beta.86

package/src/Cloudflare/DurableObjectPool.ts

@@ -0,0 +1,198 @@
+import type * as Cloudflare from "@alchemy.run/cloudflare";
+import { Worker as CloudflareWorker } from "@alchemy.run/cloudflare/Workers";
+import { dotAlchemyDirectory } from "alchemy/AlchemyContext";
+import * as Output from "alchemy/Output";
+import { Random } from "alchemy/Random";
+import { Self } from "alchemy/Self";
+import type { Stack } from "alchemy/Stack";
+import type * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Redacted from "effect/Redacted";
+import type { Entity } from "../Entity.ts";
+import { registerRouteBinder, routeType } from "../internal/Gateway.ts";
+import type { HostedClass } from "../internal/HostedRuntime.ts";
+import { HOSTED_TYPES, stackDnsLabel } from "../internal/Naming.ts";
+import { PoolHost } from "../internal/PoolHostService.ts";
+import { Pool as PoolResource, type PoolEntity } from "../Pool.ts";
+import type { Providers } from "../Providers.ts";
+import { poolWorker } from "./PoolWorker.ts";
+
+// A Worker that calls a class this pool hosts gets a service binding to
+// the pool's Worker: Workers can't fetch another Worker's workers.dev URL.
+registerRouteBinder((key, worker) =>
+  Effect.gen(function* () {
+    if (globalThis.__ALCHEMY_RUNTIME__) return;
+    const caller = Option.getOrUndefined(
+      yield* Effect.serviceOption(
+        (CloudflareWorker as unknown as { Self: Context.Key<CloudflareWorker, CloudflareWorker> })
+          .Self,
+      ),
+    );
+    if (caller === undefined) return;
+    yield* caller.bind`${key}`({
+      bindings: [{ type: "service", name: key, service: worker as string }],
+    });
+  }),
+);
+
+export interface DurableObjectPoolOptions {
+  /**
+   * The name the pool is known by, used for its Worker's entry.
+   * @default ${stack}-${stage}-${id}
+   */
+  name?: string;
+}
+
+/** An external program needs runners that run Node, which Workers don't. */
+export class ExternalProgramOnWorkers extends Data.TaggedError("Cluster.ExternalProgramOnWorkers")<{
+  readonly message: string;
+}> {}
+
+/**
+ * Write the Worker's entry module: it imports every class the pool hosts
+ * and default-exports the pool Worker with them, so the Worker's own
+ * bundler bundles them all.
+ */
+const writeEntry = Effect.fn(function* (id: string, workerId: string, pool: PoolResource) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dir = path.resolve(yield* dotAlchemyDirectory, "cluster", yield* stackDnsLabel(id));
+  return Output.mapEffect((entities: PoolEntity[]) =>
+    Effect.gen(function* () {
+      yield* fs.makeDirectory(dir, { recursive: true });
+      const file = path.join(dir, "worker.ts");
+      const source = [
+        `import { poolWorker } from "@alchemy.run/effect-cluster/Cloudflare/PoolWorker";`,
+        ...entities.map(
+          (entity, i) =>
+            `import { ${entity.handler} as e${i} } from ${JSON.stringify(
+              entity.module.startsWith("file:") ? new URL(entity.module).pathname : entity.module,
+            )};`,
+        ),
+        `export default poolWorker(${JSON.stringify(workerId)}, undefined, [${entities
+          .map((entity, i) => `{ name: ${JSON.stringify(entity.name)}, value: e${i} }`)
+          .join(", ")}]);`,
+        "",
+      ].join("\n");
+      yield* fs.writeFileString(file, source);
+      return file;
+    }).pipe(Effect.orDie),
+  )(pool.entities);
+});
+
+/**
+ * Run an Effect Cluster on Cloudflare: one Worker that hosts every class
+ * given this pool on Durable Objects. Each entity instance is a Durable
+ * Object named by its type and id, so there are no shards, no runners to
+ * place it on, and no database: the object's own SQLite holds its persisted
+ * messages. Each workflow execution is a Durable Object too, and each
+ * singleton and cron one that its alarm keeps awake.
+ *
+ * Callers anywhere reach the entities through the Worker's gateway; inside
+ * the Worker, one entity calls another's object directly.
+ *
+ * ### Running entities on Cloudflare
+ * **Example:** Runners on Durable Objects
+ * ```typescript
+ * export const Default = ClusterCloudflare.DurableObjectPool("Default");
+ * ```
+ *
+ * @primitive
+ */
+export const DurableObjectPool = (
+  id: string,
+  options: DurableObjectPoolOptions = {},
+): Layer.Layer<PoolHost, never, Stack | Providers | Cloudflare.Providers> =>
+  Layer.effect(
+    PoolHost,
+    Effect.gen(function* () {
+      // What was provided to the pool, like an entity's RPC middleware,
+      // goes with every class they host.
+      const services = yield* Effect.context<never>();
+      const self = Option.getOrUndefined(yield* Effect.serviceOption(Self));
+      const hostsSelf = self !== undefined && HOSTED_TYPES.has(self.Type);
+      if (globalThis.__ALCHEMY_RUNTIME__) {
+        if (hostsSelf) yield* (self as unknown as HostedClass).provideServices(services);
+        return {
+          host: (hosted) => hosted.provideServices(services),
+          deployExternal: () => Effect.void,
+        } satisfies PoolHost["Service"];
+      }
+      const name = options.name ?? (yield* stackDnsLabel(id));
+      const workerId = `${id}Pool`;
+      const context = yield* Effect.context<Stack | Providers | Cloudflare.Providers>();
+
+      /** Put `hosted` on the pool, and bind the gateway onto `resource`. */
+      const deploy = Effect.fn(function* (
+        hosted: PoolEntity,
+        env: Record<string, unknown>,
+        resource: Entity,
+      ) {
+        const pool = yield* PoolResource(id, { name });
+        const token = yield* Random(`${id}GatewayToken`, {
+          bytes: 32,
+        }) as unknown as Effect.Effect<Random, never, Providers>;
+        yield* pool.bind`${hosted.name}`({ entities: [hosted], env });
+        const worker = yield* poolWorker(
+          workerId,
+          {
+            main: (yield* writeEntry(id, workerId, pool)) as unknown as string,
+            compatibility: { flags: ["nodejs_compat"] },
+            env: {
+              // The classes' own environment, which only the deploy knows
+              // the keys of: one secret, unpacked when the Worker starts.
+              CLUSTER_ENV: pool.env.pipe(
+                Output.map((values) => Redacted.make(JSON.stringify(values))),
+              ),
+              CLUSTER_POOL: name,
+              CLUSTER_GATEWAY_TOKEN: token.text,
+            } as unknown as Record<string, string>,
+          },
+          [],
+        );
+        // Callers that are Workers reach the gateway through a service binding.
+        routeType(hosted.name, worker.workerName);
+        // What callers need to reach the entity through the gateway.
+        yield* resource.bind`Pool`({
+          pool: name,
+          gateway: worker.url as unknown as string,
+          token: token.text,
+        });
+      }, Effect.provide(context));
+
+      const host = (hosted: HostedClass) =>
+        Effect.andThen(
+          hosted.provideServices(services),
+          hosted.registerPool((env) =>
+            deploy(
+              {
+                name: hosted.LogicalId,
+                module: hosted.Props.main,
+                handler: hosted.Props.handler ?? "default",
+              },
+              env,
+              hosted as unknown as Entity,
+            ),
+          ),
+        );
+
+      if (hostsSelf) yield* host(self as unknown as HostedClass);
+
+      return {
+        host,
+        deployExternal: ({ type }) =>
+          Effect.die(
+            new ExternalProgramOnWorkers({
+              message:
+                `Cluster.Entity '${type}' runs an existing Effect Cluster program, which needs Node: ` +
+                `give it a pool on another host, like ClusterDocker.SwarmPool or ClusterAWS.EcsPool.`,
+            }),
+          ),
+      } satisfies PoolHost["Service"];
+    }),
+  );

package/src/Cloudflare/PoolWorker.ts

@@ -0,0 +1,124 @@
+/**
+ * The Worker a `ClusterCloudflare.DurableObjectPool` Layer deploys. While deploying it
+ * declares the Durable Object classes every cluster uses; inside the
+ * deployed Worker it also builds each class the pool hosts, registers
+ * them for those objects, and serves the gateway callers reach them through.
+ *
+ * The pool Layer declares it, and the entry module it generates for the
+ * Worker's bundle default-exports it with the hosted classes imported.
+ *
+ * @internal
+ */
+import * as Cloudflare from "@alchemy.run/cloudflare/Workers";
+import type { InputProps } from "alchemy/Input";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { RpcSerialization, RpcServer } from "effect/rpc";
+import * as Scope from "effect/Scope";
+import { authorized, gatewayServer } from "../internal/Gateway.ts";
+import {
+  type HostedDefinition,
+  hostClasses,
+  makeObjectSharding,
+  type Namespace,
+  type ScheduledObjectStub,
+  wakeScheduled,
+} from "../internal/ObjectSharding.ts";
+import {
+  EntityObject,
+  host,
+  ScheduledObject,
+  WorkflowObject,
+  workflowEngine,
+} from "./internal/Objects.ts";
+
+export type { HostedDefinition } from "../internal/ObjectSharding.ts";
+
+/**
+ * The pool's Worker `id`. `definitions` are the classes it hosts, which
+ * only the deployed Worker builds; `props` are its props, which only the
+ * deploy reads.
+ */
+export const poolWorker = (
+  id: string,
+  props: InputProps<Cloudflare.WorkerProps> | undefined,
+  definitions: ReadonlyArray<HostedDefinition>,
+) =>
+  Cloudflare.Worker(
+    id,
+    props ?? {},
+    Effect.gen(function* () {
+      const entities = yield* EntityObject;
+      const scheduled = yield* ScheduledObject;
+      const workflows = yield* WorkflowObject;
+      // A Cron Trigger wakes every singleton and cron each minute, in case
+      // their alarms stopped.
+      yield* Cloudflare.cron("* * * * *", () => wakeScheduled(scheduled));
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        return { fetch: Effect.succeed(HttpServerResponse.empty({ status: 404 })) };
+      }
+      // A class that fails to build fails every call, with its cause in the
+      // Worker's logs rather than in a response anyone can read.
+      return yield* serve(definitions, entities, scheduled, workflows).pipe(
+        Effect.tapCause((cause) => Effect.logError("Effect Cluster pool failed to start", cause)),
+        Effect.catchCause(() =>
+          Effect.succeed({
+            fetch: Effect.succeed(
+              HttpServerResponse.text(
+                "Effect Cluster pool failed to start; see the Worker's logs.",
+                {
+                  status: 503,
+                },
+              ),
+            ),
+          }),
+        ),
+      );
+    }).pipe(Effect.provide(Cloudflare.CronEventSourceLive)),
+  );
+
+const serve = Effect.fn(function* (
+  definitions: ReadonlyArray<HostedDefinition>,
+  entities: unknown,
+  scheduled: Namespace<ScheduledObjectStub>,
+  workflows: unknown,
+) {
+  // The classes' own environment, which the deploy packs into one secret.
+  const packed = yield* Config.String("CLUSTER_ENV").pipe(Config.withDefault(""));
+  if (packed) yield* Effect.sync(() => Object.assign(globalThis.process.env, JSON.parse(packed)));
+  // Built in the isolate's own scope: once, and never closed (workerd has
+  // no teardown hook). Workflows run on the Durable Object engine.
+  const hosted = yield* hostClasses({
+    definitions,
+    scope: Scope.makeUnsafe(),
+    sharding: makeObjectSharding(() => entities as never, host),
+    engine: workflowEngine(() => workflows as never),
+  });
+
+  const token = Redacted.value(yield* Config.Redacted("CLUSTER_GATEWAY_TOKEN"));
+  const { group, handlers } = gatewayServer(
+    hosted.entities.map((entry) => entry.entity),
+    new Map(hosted.workflows.map((entry) => [entry.workflow._tag, entry.workflow])),
+  );
+  let woken = false;
+  return {
+    fetch: authorized(token)(
+      Effect.gen(function* () {
+        // The first call this isolate serves starts the singletons and
+        // crons, so they run without waiting for the Cron Trigger.
+        if (!woken) {
+          woken = true;
+          yield* wakeScheduled(scheduled);
+        }
+        const app = yield* RpcServer.toHttpEffect(group).pipe(
+          Effect.provide(Layer.mergeAll(handlers, RpcSerialization.layerJson)),
+          Effect.provideContext(hosted.services),
+        );
+        return yield* app;
+      }),
+    ),
+  };
+});

package/src/Cloudflare/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @alchemy.run/effect-cluster/Cloudflare — run an Effect Cluster's entities,
+ * workflows, singletons and crons on Cloudflare Durable Objects. Requires
+ * `@alchemy.run/cloudflare`.
+ */
+export * from "./DurableObjectPool.ts";

package/src/Cloudflare/internal/Objects.ts

@@ -0,0 +1,160 @@
+/**
+ * The Durable Object classes a `ClusterCloudflare.DurableObjectPool` Worker
+ * exports. Every entity type shares one class, `ClusterEntity`, whose objects
+ * are named by `(type, id)`; every workflow shares `ClusterWorkflow`, one
+ * object per execution; every singleton and cron shares `ClusterScheduled`,
+ * one object per name. What each object runs is host-neutral (see
+ * `internal/ObjectSharding.ts`); this module gives it workerd's storage.
+ *
+ * @internal
+ */
+import * as Cloudflare from "@alchemy.run/cloudflare/Workers";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import { makeDurableObjectEngine, type ObjectImpl } from "alchemy/Workers/DurableObjectEngine";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Predicate from "effect/Predicate";
+import { InstanceStorage } from "../../Host.ts";
+import type { EntityStorage } from "../../internal/EntityRuntime.ts";
+import {
+  type EntityObjectStub,
+  makeEntityObject,
+  makeScheduledObject,
+  type Namespace,
+  NotHosted,
+  type ObjectHost,
+  registry,
+  type ScheduledObjectStub,
+  workflowClassOf,
+  workflowObjectName,
+} from "../../internal/ObjectSharding.ts";
+
+/** Cloudflare, as a host of the cluster's objects. */
+export const host: ObjectHost = {
+  group: "cloudflare",
+  // workerd marks a transient failure `retryable`, and an `overloaded`
+  // object wants less traffic, not more.
+  isRetryable: (error) =>
+    Predicate.hasProperty(error, "cause") &&
+    Predicate.hasProperty(error.cause, "retryable") &&
+    error.cause.retryable === true &&
+    !(Predicate.hasProperty(error.cause, "overloaded") && error.cause.overloaded === true),
+};
+
+/** The most bytes workerd's SQLite stores in one value. */
+const MAX_ENCODED_BYTES = 2 * 1024 * 1024;
+
+/** workerd's own storage: its SQL is synchronous. */
+interface NativeStorage {
+  readonly sql: {
+    readonly exec: (
+      query: string,
+      ...bindings: ReadonlyArray<unknown>
+    ) => { readonly toArray: () => Array<unknown> };
+  };
+  readonly transactionSync: <A>(run: () => A) => A;
+  readonly getAlarm: () => Promise<number | null>;
+  readonly setAlarm: (at: number) => Promise<void>;
+}
+
+const objectName = (state: Cloudflare.DurableObjectState["Service"]) => state.id.name ?? "";
+
+/**
+ * The object's storage, called directly: a statement is one synchronous
+ * call, so the mailbox costs no event-loop turns.
+ */
+const storageOf = (state: Cloudflare.DurableObjectState["Service"]): EntityStorage => {
+  const storage = state.raw.storage as unknown as NativeStorage;
+  return {
+    exec: <T>(query: string, ...bindings: ReadonlyArray<unknown>) =>
+      Effect.sync(() => storage.sql.exec(query, ...bindings).toArray() as Array<T>),
+    // Every statement is synchronous, so the transaction is too.
+    transaction: (effect) =>
+      Effect.sync(() => storage.transactionSync(() => Effect.runSync(effect))),
+    getAlarm: Effect.promise(() => storage.getAlarm()),
+    setAlarm: (at) => Effect.promise(() => storage.setAlarm(at)),
+  };
+};
+
+/** Every entity instance: one object per `(type, id)`. */
+export const EntityObject = Cloudflare.DurableObject<EntityObjectStub>()(
+  "ClusterEntity",
+  Effect.gen(function* () {
+    const state = yield* Cloudflare.DurableObjectState;
+    return Effect.gen(function* () {
+      const runtime = yield* Effect.context<RuntimeContext>();
+      return yield* makeEntityObject({
+        name: objectName(state),
+        host,
+        storage: storageOf(state),
+        // The object's own key-value storage, for platforms built on
+        // entities (a Domain model's) to keep each instance's data in.
+        runtime: Context.add(
+          runtime,
+          InstanceStorage,
+          state.storage as unknown as InstanceStorage["Service"],
+        ) as Context.Context<RuntimeContext>,
+        maxEncodedBytes: MAX_ENCODED_BYTES,
+        waitUntil: (effect) => state.waitUntil(effect).pipe(Effect.provideContext(runtime)),
+      });
+    });
+  }),
+);
+
+/** Every singleton and cron: one object per name. */
+export const ScheduledObject = Cloudflare.DurableObject<ScheduledObjectStub>()(
+  "ClusterScheduled",
+  Effect.gen(function* () {
+    const state = yield* Cloudflare.DurableObjectState;
+    return Effect.gen(function* () {
+      const runtime = yield* Effect.context<RuntimeContext>();
+      return yield* makeScheduledObject({
+        name: objectName(state),
+        storage: storageOf(state),
+        runtime,
+      });
+    });
+  }),
+);
+
+/**
+ * Every workflow execution: one object per `(workflow, execution)`, running
+ * Alchemy's Durable Object workflow engine. The engine declares a class per
+ * workflow; here each of those is a view onto this one class, so the Worker
+ * exports the same classes whatever workflows it hosts.
+ */
+export const WorkflowObject = Cloudflare.DurableObject<Record<string, never>>()(
+  "ClusterWorkflow",
+  Effect.gen(function* () {
+    const state = yield* Cloudflare.DurableObjectState;
+    return Effect.gen(function* () {
+      const className = workflowClassOf(objectName(state));
+      const impl = registry.workflows.get(className) as
+        | ObjectImpl<Cloudflare.DurableObjectState>
+        | undefined;
+      if (impl === undefined) {
+        return yield* Effect.die(
+          new NotHosted({ message: `This Worker hosts no Cluster.Workflow '${className}'.` }),
+        );
+      }
+      const object = yield* impl.pipe(Effect.provideService(Cloudflare.DurableObjectState, state));
+      return (yield* object.pipe(
+        Effect.provideService(Cloudflare.DurableObjectState, state),
+      )) as Record<string, never>;
+    });
+  }),
+);
+
+/** The workflow engine, its executions on {@link WorkflowObject}. */
+export const workflowEngine = (objects: () => Namespace<unknown>) =>
+  makeDurableObjectEngine<never, Cloudflare.DurableObjectState>({
+    declare: (className, impl) =>
+      Effect.sync(() => {
+        registry.workflows.set(className, impl);
+        return {
+          getByName: (executionId: string) =>
+            objects().getByName(workflowObjectName(className, executionId)) as never,
+        };
+      }),
+    state: Cloudflare.DurableObjectState,
+  });

package/src/Cron.ts

@@ -0,0 +1,202 @@
+import type { InputProps } from "alchemy/Input";
+import type { Named } from "alchemy/Named";
+import type { PlatformIdentity, PlatformServices } from "alchemy/Platform";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type { Self } from "alchemy/Self";
+import type { ClusterCron } from "effect/cluster";
+import type * as ConfigError from "effect/Config";
+import type * as Context from "effect/Context";
+import * as Cron_ from "effect/Cron";
+import * as Data from "effect/Data";
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import * as Result from "effect/Result";
+import type { Scope } from "effect/Scope";
+import {
+  type HostedProps,
+  type HostedResource,
+  makeHostedPlatform,
+} from "./internal/HostedPlatform.ts";
+import type { Providers } from "./Providers.ts";
+
+export const CronTypeId = "Cluster.Cron";
+export type CronTypeId = typeof CronTypeId;
+
+/** When a cron runs: its Layer's props, like Effect's `ClusterCron.make` options. */
+export interface CronProps extends HostedProps {
+  /**
+   * The schedule, as a cron expression with an optional leading seconds
+   * field: `"0 3 * * *"`, `"*\/10 * * * * *"`.
+   */
+  cron: string;
+  /** The time zone the expression is read in. @default UTC */
+  timeZone?: string;
+  /**
+   * Compute each run from the previous run's scheduled time rather than
+   * from when it finished.
+   * @default false
+   */
+  calculateNextRunFromPrevious?: boolean;
+  /** Skip a run that is due longer ago than this, as after an outage. */
+  skipIfOlderThan?: Duration.Input;
+}
+
+export interface ClusterCronResource extends HostedResource<CronTypeId, CronProps> {}
+
+/**
+ * A cron as a runner runs it: its schedule, the job its Construction phase
+ * returned, and the services that phase ran with.
+ * @internal
+ */
+export interface HostedCron {
+  readonly kind: "cron";
+  readonly name: string;
+  readonly cron: Cron_.Cron;
+  readonly options: Pick<CronProps, "calculateNextRunFromPrevious" | "skipIfOlderThan">;
+  readonly run: Effect.Effect<void, unknown, Scope | ClusterCron.CurrentScheduledTime>;
+  readonly context: Context.Context<never>;
+}
+
+/** A cron expression that doesn't parse. */
+export class InvalidCron extends Data.TaggedError("Cluster.InvalidCron")<{
+  readonly message: string;
+}> {}
+
+type CronServices =
+  | ClusterCronResource
+  | Providers
+  | RuntimeContext
+  | Self
+  | Self<ClusterCronResource>;
+
+const { platform, provider, declare } = makeHostedPlatform<CronTypeId, HostedCron, CronProps>(
+  CronTypeId,
+  (id, run, context, props) => ({
+    kind: "cron",
+    name: id,
+    // Checked while deploying, so it parses.
+    cron: (Cron_.parse(props.cron, props.timeZone) as Result.Success<Cron_.Cron, never>).success,
+    options: {
+      calculateNextRunFromPrevious: props.calculateNextRunFromPrevious,
+      skipIfOlderThan: props.skipIfOlderThan,
+    },
+    run: run as HostedCron["run"],
+    context,
+  }),
+  // A schedule that doesn't parse fails the deploy, not the runner.
+  (id, _context, props) => {
+    const cron = Cron_.parse(props.cron, props.timeZone);
+    return Result.isSuccess(cron)
+      ? Effect.void
+      : Effect.die(new InvalidCron({ message: `Cluster.Cron '${id}': ${cron.failure.message}` }));
+  },
+);
+
+/** The resource type behind every cron, which the providers register. @internal */
+export const CronResource = platform;
+export const CronProvider = provider;
+
+/** A declared cron, implemented by `.make(props, impl)`. */
+export type CronTag<Self, Name extends string> = Named<Name> &
+  PlatformIdentity<Name> & {
+    /**
+     * The cron's implementation, as a Layer: its schedule, and an Effect
+     * that resolves bindings once per runner and returns the job to run.
+     * Provide a pool Layer to `impl` to deploy it; provide the returned
+     * Layer to the Stack.
+     */
+    make<InitReq = never>(
+      props: InputProps<CronProps>,
+      impl: Effect.Effect<
+        Effect.Effect<void, unknown, Scope | ClusterCron.CurrentScheduledTime>,
+        ConfigError.ConfigError,
+        InitReq
+      >,
+    ): Layer.Layer<Self, never, Providers | Exclude<InitReq, CronServices | PlatformServices>>;
+    new (_: never): {};
+  };
+
+/** A cron declared with its implementation: the class is what deploys it. */
+export type CronInline<Name extends string, Req> = Effect.Effect<ClusterCronResource, never, Req> &
+  Named<Name> &
+  PlatformIdentity<Name> & {
+    new (_: never): {};
+  };
+
+/** The class surface of {@link Cron}. */
+export interface CronClass {
+  // `Self` names the class (`extends Cluster.Cron<Nightly>()`).
+  <Self>(): {
+    /**
+     * Declared with its implementation: an Effect that resolves bindings
+     * once per runner and returns the job. Provide a pool Layer to
+     * `impl` to deploy it; `yield*` the class in the Stack.
+     */
+    <const Name extends string, InitReq = never>(
+      name: Name,
+      props: InputProps<CronProps>,
+      impl: Effect.Effect<
+        Effect.Effect<void, unknown, Scope | ClusterCron.CurrentScheduledTime>,
+        ConfigError.ConfigError,
+        InitReq
+      >,
+    ): CronInline<Name, Providers | Exclude<InitReq, CronServices | PlatformServices>>;
+    /** A bare declaration, implemented by `.make(props, impl)`. */
+    <const Name extends string>(name: Name): CronTag<Self, Name>;
+  };
+}
+
+/**
+ * A **Cron** on an Effect Cluster: a job that runs on a schedule, once per
+ * scheduled time across the cluster, on whichever runner owns it. Each run
+ * is a persisted message, so a run due while its runner restarts still
+ * happens.
+ *
+ * Declare it by name, with its schedule, as Effect's `ClusterCron.make`
+ * takes it, and its implementation: an Effect that resolves bindings once
+ * per runner and returns the job. The job can read the time it was
+ * scheduled for with `ClusterCron.CurrentScheduledTime`. Providing a pool
+ * Layer to the implementation is what deploys it. Or declare it bare and
+ * implement it with `.make(props, impl)`, as a Layer.
+ *
+ * ### Declaring a cron
+ * **Example:** A nightly job
+ * ```typescript
+ * // src/Nightly.ts
+ * export default class Nightly extends Cluster.Cron<Nightly>()(
+ *   "Nightly",
+ *   { main: import.meta.url, cron: "0 3 * * *", skipIfOlderThan: "1 hour" },
+ *   Effect.gen(function* () {
+ *     const counters = yield* Counter;
+ *     return Effect.gen(function* () {
+ *       const counter = yield* counters.getByName("nightly");
+ *       yield* counter.Increment({ amount: 1 });
+ *     }).pipe(Effect.orDie);
+ *   }).pipe(Effect.provide(Default)),
+ * ) {}
+ * ```
+ *
+ * **Example:** Declared bare, and implemented as a Layer
+ * ```typescript
+ * // src/Nightly.ts
+ * export class Nightly extends Cluster.Cron<Nightly>()("Nightly") {}
+ *
+ * // src/NightlyLive.ts
+ * export default Nightly.make(
+ *   { main: import.meta.url, cron: "0 3 * * *", skipIfOlderThan: "1 hour" },
+ *   Effect.gen(function* () {
+ *     const counters = yield* Counter;
+ *     return Effect.gen(function* () {
+ *       const counter = yield* counters.getByName("nightly");
+ *       yield* counter.Increment({ amount: 1 });
+ *     }).pipe(Effect.orDie);
+ *   }).pipe(Effect.provide(Default)),
+ * );
+ * ```
+ *
+ * @resource
+ */
+export const Cron: CronClass = (() =>
+  (name: string, props?: InputProps<CronProps>, impl?: unknown) =>
+    declare(name, {}, props, impl)) as unknown as CronClass;