sailfork / t3code-github / .repos/ alchemy-effect/ packages/ docker/ src/ Swarm.ts

import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import { Docker, dockerContextName } from "./Docker.ts";
import type { Providers } from "./Providers.ts";

export interface SwarmProps {
  /** Docker context name or context resource of the engine to initialize. */
  context?: Docker.ContextRef;
  /**
   * Address advertised to other swarm members, e.g. `"10.0.0.1"` or
   * `"eth0"`. Required by Docker when the host has several network
   * interfaces. Applied only when the swarm is first initialized.
   */
  advertiseAddr?: string;
  /**
   * Listen address for swarm traffic, e.g. `"0.0.0.0:2377"`. Applied only
   * when the swarm is first initialized.
   */
  listenAddr?: string;
  /**
   * Address pools for global-scope (overlay) networks, e.g.
   * `["10.20.0.0/16"]`. Applied only when the swarm is first initialized.
   */
  defaultAddrPool?: string[];
  /**
   * CIDR mask length for each subnet carved from `defaultAddrPool`.
   * Applied only when the swarm is first initialized.
   *
   * @default 24
   */
  subnetSize?: number;
}

export interface Swarm extends Resource<
  "Docker.Swarm",
  SwarmProps,
  {
    /** Swarm cluster id. */
    id: string;
    /** This node's id in the swarm (a manager). */
    nodeId: string;
    /** Docker context the swarm was initialized on. */
    context?: string;
    /** Number of manager nodes. */
    managers: number;
    /** Number of nodes in the swarm. */
    nodes: number;
  },
  never,
  Providers
> {}

/**
 * Swarm mode on a Docker engine — an idempotent `docker swarm init`.
 *
 * Turns the engine behind the given `context` (or the local engine) into a
 * single-node swarm: the node becomes a manager that can run `Docker.Service`
 * workloads. Regular (non-swarm) docker usage of the engine is unaffected.
 *
 * Pass the swarm as the `context` of a `Docker.Service` or overlay
 * `Docker.Network`: the workload then deploys after the swarm exists and
 * inherits its Docker context.
 *
 * An engine that is already in swarm mode is treated as foreign — adopt it
 * with `adopt(true)` (or `--adopt`) to manage it. Destroying the resource
 * dissolves the node's swarm membership (`docker swarm leave --force`),
 * which stops every service running on it — services managed by the same
 * stack are destroyed first via their dependency edges.
 *
 * Growing the cluster beyond one node is host-level setup: run
 * `docker swarm join --token <token> <manager-ip>:2377` on each additional
 * machine (`docker swarm join-token worker` on the manager prints the
 * command). Alchemy manages the swarm's workloads through the manager.
 * ### Creating a Swarm
 * **Example:** Local single-node swarm
 * ```typescript
 * const swarm = yield* Docker.Swarm("swarm");
 * ```
 *
 * **Example:** Remote engine over SSH
 * ```typescript
 * const vps = yield* Docker.Context("vps", {
 *   docker: "host=ssh://deploy@example.com",
 * });
 * const swarm = yield* Docker.Swarm("swarm", {
 *   context: vps,
 *   advertiseAddr: "10.0.0.1",
 * });
 * ```
 *
 * ### Using an Existing Swarm
 * **Example:** Reference without owning
 * ```typescript
 * // Services don't require a Swarm resource — point them at an engine that
 * // is already a manager and the swarm's lifecycle stays external: destroy
 * // removes the services, never the swarm.
 * const web = yield* Docker.Service("web", {
 *   context: vps,
 *   image: "nginx:alpine",
 * });
 * ```
 *
 * **Example:** Adopt an already-initialized engine
 * ```typescript
 * // Adoption makes the swarm part of the stack — destroy then dissolves
 * // the node's membership.
 * const swarm = yield* Docker.Swarm("swarm").pipe(adopt(true));
 * ```
 *
 * ### Deploying into the Swarm
 * **Example:** Service ordered after the swarm
 * ```typescript
 * const swarm = yield* Docker.Swarm("swarm");
 * const web = yield* Docker.Service("web", {
 *   context: swarm,
 *   image: "nginx:alpine",
 *   replicas: 2,
 *   ports: [{ external: 8080, internal: 80 }],
 * });
 * ```
 *
 * @resource
 * @product Swarm
 */
export const Swarm = Resource<Swarm>("Docker.Swarm");

export const SwarmProvider = () =>
  Provider.effect(
    Swarm,
    Effect.gen(function* () {
      const docker = yield* Docker;

      /** Active-manager info, or undefined when the engine isn't one. */
      const observe = Effect.fn(function* (context: string | undefined) {
        const info = yield* docker.swarm.info(context);
        if (info.LocalNodeState !== "active" || !info.ControlAvailable || !info.Cluster?.ID) {
          return undefined;
        }
        return info;
      });

      return Swarm.Provider.of({
        list: () => Effect.succeed([]),
        read: Effect.fn(function* ({ olds, output }) {
          const context = dockerContextName(olds?.context);
          const info = yield* observe(context);
          if (!info) return undefined;
          const attrs = toSwarmAttributes(info, context);
          if (output) return attrs;
          // A swarm carries no labels to brand, so an already-initialized
          // engine can never be proven ours — adoption is gated behind
          // `--adopt` / `adopt(true)`.
          return Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (dockerContextName(olds?.context) !== dockerContextName(news?.context)) {
            return { action: "replace" as const, deleteFirst: true };
          }
          // The remaining props only apply at `swarm init`; changing them on
          // a live swarm is a no-op rather than a destructive re-init.
          return { action: "noop" as const };
        }),
        reconcile: Effect.fn(function* ({ news }) {
          const context = dockerContextName(news?.context);
          const existing = yield* observe(context);
          if (existing) return toSwarmAttributes(existing, context);

          yield* docker.swarm
            .init({
              context,
              "advertise-addr": news?.advertiseAddr,
              "listen-addr": news?.listenAddr,
              "default-addr-pool": news?.defaultAddrPool,
              "default-addr-pool-mask-length": news?.subnetSize,
            })
            .pipe(
              // A concurrent init (or an interrupted prior reconcile) already
              // made this node a swarm member — converge on the observation.
              Effect.catchIf(
                (error) => /already part of a swarm/i.test(String(error)),
                () => Effect.void,
              ),
            );

          const info = yield* observe(context);
          if (!info) {
            return yield* Effect.die(
              new Error(
                "docker swarm init succeeded but the engine did not become an active swarm manager",
              ),
            );
          }
          return toSwarmAttributes(info, context);
        }),
        delete: Effect.fn(({ output }) =>
          docker.swarm.leave(true, output.context).pipe(
            Effect.catchIf(
              (error) => /not part of a swarm/i.test(String(error)),
              () => Effect.void,
            ),
            Effect.asVoid,
          ),
        ),
      });
    }),
  );

const toSwarmAttributes = (
  info: Docker.SwarmInfo,
  context: string | undefined,
): Swarm["Attributes"] => ({
  id: info.Cluster!.ID,
  nodeId: info.NodeID,
  context,
  managers: info.Managers ?? 1,
  nodes: info.Nodes ?? 1,
});