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

import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, isResolved } from "alchemy/Diff";
import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import type { Resource } from "alchemy/Resource";
import {
  createContainerRuntimeContext,
  type HostRuntimeContext,
  type ServerHost,
} from "alchemy/Runtime/Process";
import { Stack } from "alchemy/Stack";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Equal from "effect/Equal";
import type { PlatformError } from "effect/PlatformError";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import type * as rolldown from "rolldown";
import { Docker, dockerEngineContextName, dockerPhysicalName } from "./Docker.ts";
import { healthcheckCommand, isHealthcheckDisabled } from "./HealthcheckCommand.ts";
import type { Providers } from "./Providers.ts";
import { makeServiceImage } from "./ServiceImage.ts";

export interface ServicePropsBase extends PlatformProps {
  /**
   * Service name.
   *
   * @default Generated from stack, stage, logical id, and instance id.
   */
  name?: string;
  /**
   * The engine the service is deployed to: a Docker context name, a
   * `Docker.Context` resource, or a `Docker.Swarm` — passing the swarm also
   * orders the service after the swarm is initialized.
   */
  context?: Docker.EngineRef;
  /** Entrypoint command passed after the image. */
  command?: string[];
  /** Additional args appended after `command`. */
  args?: string[];
  /** Environment variables. Use Redacted for secrets. */
  environment?: Record<string, string | Redacted.Redacted<string>>;
  /**
   * Environment variables injected by the platform (bound `Config` values and
   * future bindings). Merged after `environment`; usually not set directly.
   */
  env?: Record<string, any>;
  /** Overlay networks attached to this service. */
  networks?: Array<string | Service.NetworkAttachment>;
  /** Published port mappings. */
  ports?: Service.PortMapping[];
  /**
   * Service discovery endpoint mode.
   *
   * @default "vip"
   */
  endpointMode?: "vip" | "dnsrr";
  /**
   * Desired number of service replicas.
   *
   * @default 1
   */
  replicas?: number;
  /** Placement controls for task scheduling. */
  placement?: Service.Placement;
  /** Deprecated alias for `placement.constraints`. */
  constraints?: string[];
  /** Rolling update strategy for service updates. */
  updateConfig?: Service.RolloutConfig;
  /** Rollback strategy applied when updates fail. */
  rollbackConfig?: Service.RolloutConfig;
  /** Task restart behavior. */
  restartPolicy?: Service.RestartPolicy;
  /** Container healthcheck for service tasks. */
  healthcheck?: Service.Healthcheck;
  /** Grace period before force-killing a task during shutdown, e.g. `"30s"`. */
  stopGracePeriod?: string;
  /** Volume or bind mounts. */
  volumes?: Service.VolumeMapping[];
  /** Swarm secrets mounted into task containers. */
  secrets?: Service.SecretRef[];
  /** Swarm configs mounted into task containers. */
  configs?: Service.ConfigRef[];
  /**
   * Mount task root filesystem read-only.
   *
   * @default false
   */
  readOnlyRootFs?: boolean;
  /**
   * Service labels. Alchemy's internal ownership labels are added
   * automatically.
   */
  labels?: Record<string, string>;
}

/**
 * Run a pre-built image: a registry reference or a Docker image resource
 * (`Docker.Image` / `Docker.RemoteImage`).
 */
export interface ImageServiceProps extends ServicePropsBase {
  /** Docker image reference or Docker image resource. */
  image: Service.Image;
  main?: undefined;
}

/**
 * Bundle an inline Effect program (`main`) into a generated image built
 * against the service's Docker context. The optional `image` is the
 * environment base (`FROM`) and must be able to run the bun runtime.
 */
export interface BundledServiceProps extends ServicePropsBase {
  /**
   * Module entrypoint for the bundled program. This should typically be
   * `import.meta.url` (or `import.meta.filename`) from an inline Effect
   * program.
   */
  main: string;
  /**
   * Environment image used as the generated Dockerfile's `FROM`. Must be
   * able to run the bun runtime.
   *
   * @default "oven/bun:1"
   */
  image?: string;
  /**
   * Container port the bundled HTTP server listens on. Baked into the image
   * as `ENV PORT` + `EXPOSE`; publish it to the swarm ingress with `ports`.
   */
  port?: number;
  /**
   * Named export to load from `main`.
   *
   * @default "default"
   */
  handler?: string;
  /** Bundler configuration for the entrypoint. */
  build?: {
    input?: Partial<rolldown.InputOptions>;
    output?: Partial<rolldown.OutputOptions>;
  };
}

/**
 * Service props — the image comes from exactly one of two sources, flat on
 * the props: `image` (a pre-built reference) or `main` (a bundled Effect
 * program).
 */
export type ServiceProps = ImageServiceProps | BundledServiceProps;

export declare namespace Service {
  type Image = string | { imageRef: string };

  interface PortMapping {
    /** Published port on the swarm node. Omit to let Swarm assign one dynamically. */
    external?: number;
    /** Container port receiving traffic. */
    internal: number;
    /**
     * Protocol used for the mapping.
     *
     * @default "tcp"
     */
    protocol?: "tcp" | "udp";
    /**
     * Publish through the swarm routing mesh (`ingress`) or directly on each
     * node (`host`).
     *
     * @default "ingress"
     */
    mode?: "ingress" | "host";
  }

  interface VolumeMapping {
    /** Host path or named volume source. */
    hostPath: string;
    /** Container path. */
    containerPath: string;
    /**
     * Mount read-only.
     *
     * @default false
     */
    readOnly?: boolean;
  }

  interface NetworkAttachment {
    /** Network name. */
    name: string;
    /** Network aliases for the service's tasks. */
    aliases?: string[];
  }

  interface Placement {
    /** Placement constraints, e.g. `"node.role==worker"`. */
    constraints?: string[];
    /** Placement preferences, e.g. `"spread=node.labels.zone"`. */
    preferences?: string[];
    /** Maximum number of replicas per swarm node. */
    maxReplicasPerNode?: number;
  }

  interface RolloutConfig {
    /** Number of tasks updated simultaneously. */
    parallelism?: number;
    /** Delay between task updates, e.g. `"10s"`. */
    delay?: string;
    /** Duration to monitor each updated task for failure, e.g. `"30s"`. */
    monitor?: string;
    /** Action on update failure. */
    failureAction?: "pause" | "continue" | "rollback";
    /** Failure ratio tolerated during an update. */
    maxFailureRatio?: number;
    /** Operation order during updates. */
    order?: "stop-first" | "start-first";
  }

  interface RestartPolicy {
    /** Condition under which tasks restart. */
    condition?: "none" | "on-failure" | "any";
    /** Delay between restart attempts, e.g. `"5s"`. */
    delay?: string;
    /** Maximum restart attempts before giving up. */
    maxAttempts?: number;
    /** Window used to evaluate the restart policy, e.g. `"120s"`. */
    window?: string;
  }

  interface Healthcheck {
    /**
     * Command to run for health checks. A string runs in the container's
     * shell. An array follows Docker's healthcheck `Test` form:
     * `["CMD-SHELL", "pg_isready -U app"]`, `["CMD", "pg_isready", "-U", "app"]`,
     * or `["NONE"]` to disable the image's healthcheck.
     */
    cmd: string[] | string;
    /** Time between checks, e.g. `"30s"`. */
    interval?: string;
    /** Maximum time a check may run, e.g. `"5s"`. */
    timeout?: string;
    /** Consecutive failures before unhealthy. */
    retries?: number;
    /** Startup grace period, e.g. `"30s"`. */
    startPeriod?: string;
  }

  interface SecretRef {
    /** Swarm secret name. */
    source: string;
    /** Target file name in `/run/secrets/`. Defaults to `source`. */
    target?: string;
    /** File owner uid. */
    uid?: string;
    /** File owner gid. */
    gid?: string;
    /** File mode, e.g. `0o400`. */
    mode?: number | string;
  }

  interface ConfigRef {
    /** Swarm config name. */
    source: string;
    /** Target path in the container. Defaults to `/<source>`. */
    target?: string;
    /** File owner uid. */
    uid?: string;
    /** File owner gid. */
    gid?: string;
    /** File mode, e.g. `0o444`. */
    mode?: number | string;
  }
}

export interface Service extends Resource<
  "Docker.Service",
  ServiceProps,
  {
    /** Swarm service id. */
    id: string;
    /** Swarm service name. */
    name: string;
    /** Docker context the service is deployed to. */
    context?: string;
    /** Image reference the service runs. */
    image: string;
    /** Desired number of replicas. */
    replicas: number;
    /** Network ids the service's tasks attach to. */
    networks: string[];
    /** Published port mappings reported by Swarm. */
    ports: Service.PortMapping[];
    /** Service labels reported by Swarm. */
    labels: Record<string, string>;
    /** Service discovery endpoint mode. */
    endpointMode: "vip" | "dnsrr";
    /** Creation timestamp in milliseconds since epoch. */
    createdAt: number;
    /** Last update timestamp in milliseconds since epoch. */
    updatedAt: number;
    /** Content hash of the bundled program's image (`main` form only). */
    code?: {
      /** Content hash of the bundled program's image. */
      hash: string;
    };
  },
  never,
  Providers
> {}

/** Services available to an effectful `Service` impl at init time. */
export type ServiceServices = ServerHost;

/**
 * The impl shape for an effectful `Service`: a long-running server returning
 * `{ fetch }` (plus optional RPC methods).
 */
export type ServiceShape = Main<ServiceServices>;

export interface ServiceRuntimeContext extends HostRuntimeContext {
  readonly Type: "Docker.Service";
}

/**
 * A Docker Swarm service: N replicas of a container kept alive by the swarm,
 * deployed through the active (or a named) Docker context.
 *
 * The target engine must be a swarm manager — `Service` wraps
 * `docker service`, swarm mode's orchestration API. Declare the swarm with
 * `Docker.Swarm` and pass it as `context` so the service deploys after the
 * swarm exists; for a plain single container on a non-swarm daemon use
 * `Docker.Container` instead.
 *
 * The service's image comes from one of two sources:
 *
 * - `image` — run a pre-built reference (a registry ref, or a `Docker.Image`
 *   / `Docker.RemoteImage` resource).
 * - `main` — bundle an inline Effect program into a generated bun image,
 *   built directly against the service's Docker context. The impl returns
 *   `{ fetch }` and may register background loops via `ServerHost.run` —
 *   the same effectful platform shape as `AWS.ECS.Service`.
 *
 * The bundled image is content-addressed and only rebuilt when the program
 * (or its generated Dockerfile) changes. It is built on the target engine's
 * local store — single-node swarms run it as-is; multi-node swarms need the
 * image on a registry every node can reach (build with `Docker.Image` +
 * `registry` and pass the pushed ref as `image` instead).
 *
 * Only replicated services are supported. Changes to the image, replicas,
 * environment, labels, networks, ports, mounts, secrets, configs, constraints,
 * healthcheck, and rollout or restart policies are applied in place with
 * `docker service update`, so swarm rolls tasks over following `updateConfig`.
 * An update that swarm rolls back or pauses fails the deploy with
 * `DockerServiceUpdateFailed`. Changing the name, context, command, args,
 * endpoint mode, placement preferences, or read-only root filesystem, or
 * removing a policy setting, replaces the service (delete-then-create).
 * ### Creating Services
 * **Example:** Replicated Nginx
 * ```typescript
 * const swarm = yield* Docker.Swarm("swarm");
 * const web = yield* Docker.Service("web", {
 *   context: swarm,
 *   image: "nginx:alpine",
 *   replicas: 3,
 *   ports: [{ external: 8080, internal: 80 }],
 * });
 * ```
 *
 * **Example:** Run a Built Image
 * ```typescript
 * const image = yield* Docker.Image("app-image", {
 *   build: { context: "./app" },
 * });
 * const app = yield* Docker.Service("app", {
 *   context: swarm,
 *   image,
 *   replicas: 2,
 * });
 * ```
 *
 * ### Effectful Services
 * **Example:** Inline Effect Server
 * ```typescript
 * const swarm = yield* Docker.Swarm("swarm");
 * const api = yield* Docker.Service(
 *   "Api",
 *   {
 *     context: swarm,
 *     main: import.meta.url,
 *     port: 3000,
 *     ports: [{ external: 8080, internal: 3000 }],
 *     replicas: 2,
 *   },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.gen(function* () {
 *         return yield* HttpServerResponse.json({ ok: true });
 *       }),
 *     };
 *   }),
 * );
 * ```
 *
 * **Example:** Background Loops with ServerHost
 * ```typescript
 * // Class props may be an Effect, so the service can yield the swarm it
 * // deploys into (declared once at module level).
 * const Swarm = Docker.Swarm("swarm");
 *
 * export default class Worker extends Docker.Service<Worker>()(
 *   "Worker",
 *   Effect.gen(function* () {
 *     const swarm = yield* Swarm;
 *     return { context: swarm, main: import.meta.url, port: 3000 };
 *   }),
 *   Effect.gen(function* () {
 *     const host = yield* ServerHost;
 *     yield* host.run(
 *       pollQueue.pipe(Effect.repeat(Schedule.spaced("5 seconds")), Effect.asVoid),
 *     );
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Bundling & Tree-shaking
 * `main` is bundled with rolldown at deploy time. Unused code is
 * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
 * pure so unused parts prune more aggressively. Your app is not
 * marked pure.
 *
 * **Example:** Mark additional packages as pure
 * Only list packages with no top-level side effects.
 * ```typescript
 * {
 *   main: import.meta.url,
 *   build: {
 *     pure: { packages: ["my-lib", "@my-scope/*"] },
 *   },
 * }
 * ```
 *
 * **Example:** Turn it off
 * ```typescript
 * {
 *   main: import.meta.url,
 *   build: { pure: false },
 * }
 * ```
 *
 * ### Docker Contexts
 * **Example:** Deploy to a Remote Swarm 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",
 * });
 * const app = yield* Docker.Service("app", {
 *   context: swarm,
 *   image: "nginx:alpine",
 *   replicas: 3,
 * });
 * ```
 *
 * ### Networks & Volumes
 * **Example:** Overlay Network with Aliases
 * ```typescript
 * const network = yield* Docker.Network("app-net", {
 *   context: swarm,
 *   driver: "overlay",
 * });
 * const db = yield* Docker.Service("db", {
 *   context: swarm,
 *   image: "postgres:18-alpine",
 *   networks: [{ name: network.name, aliases: ["postgres"] }],
 *   volumes: [{ hostPath: "pg-data", containerPath: "/var/lib/postgresql/data" }],
 * });
 * ```
 *
 * ### Rollouts & Placement
 * **Example:** Rolling Update with Rollback
 * ```typescript
 * const app = yield* Docker.Service("app", {
 *   image: "ghcr.io/acme/app:latest",
 *   replicas: 4,
 *   updateConfig: {
 *     parallelism: 1,
 *     delay: "10s",
 *     failureAction: "rollback",
 *     order: "start-first",
 *   },
 *   placement: {
 *     constraints: ["node.role==worker"],
 *     maxReplicasPerNode: 2,
 *   },
 * });
 * ```
 *
 * ### Secrets & Configs
 * **Example:** Mount Swarm Secrets
 * ```typescript
 * const app = yield* Docker.Service("app", {
 *   image: "ghcr.io/acme/app:latest",
 *   secrets: [{ source: "db-password", target: "db_password", mode: 0o400 }],
 *   configs: [{ source: "app-config", target: "/etc/app/config.yaml" }],
 * });
 * ```
 *
 * @resource
 * @product Swarm
 */
export const Service: Platform<Service, ServiceServices, ServiceShape, ServiceRuntimeContext> =
  Platform("Docker.Service", {
    createRuntimeContext: createContainerRuntimeContext("Docker.Service") as (
      id: string,
    ) => ServiceRuntimeContext,
  });

/** True when the props declare a bundled `main` program. */
const isBundledService = (props: ServiceProps): props is BundledServiceProps =>
  typeof (props as BundledServiceProps).main === "string";

/**
 * A `docker service update` that swarm rolled back or paused instead of
 * completing. `--detach=false` exits 0 on a rollback and 1 on a pause, so the
 * provider reads the service's `UpdateStatus` after the update.
 */
export class DockerServiceUpdateFailed extends Data.TaggedError("DockerServiceUpdateFailed")<{
  readonly service: string;
  readonly state: string;
  readonly reason: string;
}> {
  override get message() {
    return `Update of service "${this.service}" ended in ${this.state}: ${this.reason}`;
  }
}

type ServiceInspect = {
  ID: string;
  CreatedAt?: string;
  UpdatedAt?: string;
  UpdateStatus?: {
    State?: string;
    Message?: string;
  };
  Spec: {
    Name: string;
    Labels?: Record<string, string> | null;
    TaskTemplate?: {
      ContainerSpec?: {
        Image?: string;
        Env?: string[] | null;
        Mounts?: Array<{ Target?: string }> | null;
        Secrets?: Array<{ SecretName?: string }> | null;
        Configs?: Array<{ ConfigName?: string }> | null;
      };
      Networks?: Array<{ Target?: string }>;
      Placement?: {
        Constraints?: string[];
      };
    };
    Mode?: {
      Replicated?: {
        Replicas?: number;
      };
      Global?: Record<string, never>;
    };
    EndpointSpec?: {
      Mode?: "vip" | "dnsrr";
      Ports?: Array<{
        PublishedPort?: number;
        TargetPort?: number;
        Protocol?: "tcp" | "udp";
        PublishMode?: "ingress" | "host";
      }>;
    };
  };
};

export const ServiceProvider = () =>
  Provider.effect(
    Service,
    Effect.gen(function* () {
      const docker = yield* Docker;
      const stack = yield* Stack;
      const serviceImage = yield* makeServiceImage;

      // The bundled program's bootstrap reads these to rebuild the Stack at
      // container runtime (same contract as the ECS bootstrap).
      const alchemyEnv = {
        ALCHEMY_STACK_NAME: stack.name,
        ALCHEMY_STAGE: stack.stage,
        ALCHEMY_PHASE: "runtime",
      };

      const inspect = (id: string, context?: string) =>
        docker.service.inspect(id, context).pipe(
          Effect.map((result) => normalizeServiceInspect(result)),
          Effect.catchReason("PlatformError", "NotFound", () => Effect.undefined),
        );

      /**
       * Resolve the image the service should run: build the bundled `main`
       * program (content-addressed, skipped when already present in the
       * target engine) or normalize the pre-built reference.
       */
      const resolveImage = Effect.fn(function* (
        id: string,
        props: ServiceProps,
        name: string,
        context: string | undefined,
        session: { note: (message: string) => Effect.Effect<void> },
      ) {
        if (isBundledService(props)) {
          return yield* serviceImage.resolve({
            id,
            source: props,
            name,
            context,
            isExternal: props.isExternal,
            session,
          });
        }
        return {
          imageRef: normalizeImageRef(props.image),
          codeHash: undefined,
        };
      });

      return Service.Provider.of({
        list: () => Effect.succeed([]),
        read: Effect.fn(function* ({ id, instanceId, olds, output }) {
          const name = yield* servicePhysicalName(id, olds, instanceId);
          const context = dockerEngineContextName(olds?.context);
          const live = yield* inspect(name, context);
          if (!live) return undefined;
          ensureReplicatedMode(live);
          const attrs = toServiceAttributes(live, context, output?.code);
          if (output) return attrs;
          const owned = yield* hasAlchemyTags(id, live.Spec.Labels ?? undefined);
          return owned ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, instanceId, news, olds, output }) {
          if (!isResolved(news)) return undefined;

          const oldDesired = yield* normalizeDesired(id, olds, instanceId);
          const newDesired = yield* normalizeDesired(id, news, instanceId);

          if (!Equal.equals(oldDesired, newDesired)) {
            return requiresReplacement(oldDesired, newDesired)
              ? { action: "replace" as const, deleteFirst: true }
              : { action: "update" as const };
          }

          // Bundled program: the image identity is the content hash — a code
          // or bootstrap change rolls the service onto the new image.
          if (isBundledService(news)) {
            const hash = yield* serviceImage.hash({
              source: news,
              isExternal: news.isExternal,
            });
            if (hash !== output?.code?.hash) {
              return { action: "update" as const };
            }
          }

          return { action: "noop" as const };
        }),
        reconcile: Effect.fn(function* ({ id, instanceId, news, olds, output, session }) {
          const desired = yield* normalizeDesired(id, news, instanceId);
          const resolved = yield* resolveImage(id, news, desired.name, desired.context, session);
          const image = resolved.imageRef;
          const code = resolved.codeHash ? { hash: resolved.codeHash } : undefined;
          const environment = isBundledService(news)
            ? { ...alchemyEnv, ...desired.environment }
            : desired.environment;

          if (output && olds) {
            const oldDesired = yield* normalizeDesired(id, olds, instanceId);
            if (
              deepEqual(oldDesired, desired) &&
              (resolved.codeHash === undefined || resolved.codeHash === output.code?.hash)
            ) {
              const current = yield* inspect(output.id, desired.context);
              if (current) {
                ensureReplicatedMode(current);
                return toServiceAttributes(current, desired.context, code);
              }
            }
          }

          if (output) {
            const current = yield* inspect(output.id, desired.context);
            if (current) {
              ensureReplicatedMode(current);
              const internalTags = yield* createInternalTags(id);
              const allDesiredLabels = { ...internalTags, ...desired.labels };
              const currentLabels = current.Spec.Labels ?? {};
              const labelsToRemove = Object.keys(currentLabels).filter(
                (k) => !(k in allDesiredLabels),
              );
              // `service update` only adds and removes list entries, so the
              // removals are computed from the observed spec rather than olds.
              const spec = current.Spec.TaskTemplate?.ContainerSpec;
              const envToRemove = (spec?.Env ?? [])
                .map((entry) => entry.split("=", 1)[0]!)
                .filter((key) => !(key in environment));
              const currentConstraints = current.Spec.TaskTemplate?.Placement?.Constraints ?? [];
              const constraintsToRemove = currentConstraints.filter(
                (c) => !desired.constraints.includes(c),
              );
              // `--constraint-add` appends without de-duplicating.
              const constraintsToAdd = desired.constraints.filter(
                (c) => !currentConstraints.includes(c),
              );
              const desiredTargets = new Set(desired.volumes.map((v) => v.containerPath));
              const mountsToRemove = (spec?.Mounts ?? []).flatMap((m) =>
                m.Target && !desiredTargets.has(m.Target) ? [m.Target] : [],
              );
              const desiredPorts = new Set(desired.ports.map(formatPublish));
              const portsToRemove = (current.Spec.EndpointSpec?.Ports ?? []).flatMap((p) =>
                p.TargetPort !== undefined &&
                !desiredPorts.has(
                  formatPublish({
                    external: p.PublishedPort,
                    internal: p.TargetPort,
                    protocol: p.Protocol,
                    mode: p.PublishMode,
                  }),
                )
                  ? // `--publish-rm` matches target, protocol and publish mode.
                    [
                      `target=${p.TargetPort},protocol=${p.Protocol ?? "tcp"},mode=${p.PublishMode ?? "ingress"}`,
                    ]
                  : [],
              );
              // A rollback exits 0 but a paused rollout exits 1, so the
              // outcome is read from `UpdateStatus` either way.
              const updateError = yield* docker.service
                .update({
                  context: desired.context,
                  id: output.id,
                  image,
                  replicas: desired.replicas,
                  "endpoint-mode": desired.endpointMode,
                  // Attaching a network the service is already on fails, so
                  // every attachment is detached and the desired set re-added.
                  "network-rm": (current.Spec.TaskTemplate?.Networks ?? []).flatMap((n) =>
                    n.Target ? [n.Target] : [],
                  ),
                  "network-add": desired.networks.map(formatNetwork),
                  "constraint-rm": constraintsToRemove,
                  "constraint-add": constraintsToAdd,
                  "replicas-max-per-node": desired.maxReplicasPerNode,
                  "update-parallelism": desired.updateConfig?.parallelism,
                  "update-delay": desired.updateConfig?.delay,
                  "update-monitor": desired.updateConfig?.monitor,
                  "update-failure-action": desired.updateConfig?.failureAction,
                  "update-max-failure-ratio": desired.updateConfig?.maxFailureRatio,
                  "update-order": desired.updateConfig?.order,
                  "rollback-parallelism": desired.rollbackConfig?.parallelism,
                  "rollback-delay": desired.rollbackConfig?.delay,
                  "rollback-monitor": desired.rollbackConfig?.monitor,
                  "rollback-failure-action": desired.rollbackConfig?.failureAction,
                  "rollback-max-failure-ratio": desired.rollbackConfig?.maxFailureRatio,
                  "rollback-order": desired.rollbackConfig?.order,
                  "restart-condition": desired.restartPolicy?.condition,
                  "restart-delay": desired.restartPolicy?.delay,
                  "restart-max-attempts": desired.restartPolicy?.maxAttempts,
                  "restart-window": desired.restartPolicy?.window,
                  "health-cmd": desired.healthcheck
                    ? healthcheckCommand(desired.healthcheck.cmd)
                    : undefined,
                  "no-healthcheck":
                    desired.healthcheck !== undefined &&
                    isHealthcheckDisabled(desired.healthcheck.cmd),
                  "health-interval": desired.healthcheck?.interval,
                  "health-timeout": desired.healthcheck?.timeout,
                  "health-retries": desired.healthcheck?.retries,
                  "health-start-period": desired.healthcheck?.startPeriod,
                  "stop-grace-period": desired.stopGracePeriod,
                  "mount-rm": mountsToRemove,
                  "mount-add": desired.volumes.map(formatMount),
                  // Re-adding a ref that is still attached conflicts on its
                  // target, so every attached ref is removed and the desired
                  // set re-added in the same update.
                  "secret-rm": (spec?.Secrets ?? []).flatMap((s) =>
                    s.SecretName ? [s.SecretName] : [],
                  ),
                  "secret-add": desired.secrets.map(formatRef),
                  "config-rm": (spec?.Configs ?? []).flatMap((c) =>
                    c.ConfigName ? [c.ConfigName] : [],
                  ),
                  "config-add": desired.configs.map(formatRef),
                  "read-only": desired.readOnlyRootFs || undefined,
                  "publish-rm": portsToRemove,
                  "publish-add": desired.ports.map(formatPublish),
                  "label-add": allDesiredLabels,
                  "label-rm": labelsToRemove,
                  "env-rm": envToRemove,
                  "env-add": environment,
                  args:
                    desired.command.length > 0
                      ? desired.command.concat(desired.args).join(" ")
                      : undefined,
                })
                .pipe(
                  Effect.as(undefined),
                  Effect.catchTag("PlatformError", (error) => Effect.succeed(error)),
                );

              const updated = yield* inspectOrDie(inspect, output.id, desired.context);
              // Swarm clears `UpdateStatus` whenever it accepts an update, so
              // any status here belongs to this update.
              const status = updated.UpdateStatus;
              if (
                status?.State === "rollback_completed" ||
                status?.State === "rollback_paused" ||
                status?.State === "paused"
              ) {
                return yield* new DockerServiceUpdateFailed({
                  service: updated.Spec.Name,
                  state: status.State,
                  reason: status.Message ?? "",
                });
              }
              if (updateError) {
                return yield* updateError;
              }

              // Best-effort: the service now runs the new content-addressed
              // image, so drop the one built for the previous bundle.
              if (output.code && output.code.hash !== resolved.codeHash) {
                yield* docker.image
                  .remove(output.image, true, desired.context)
                  .pipe(Effect.catchCause(() => Effect.void));
              }

              return toServiceAttributes(updated, desired.context, code);
            }
          }

          const existingByName = yield* inspect(desired.name, desired.context);
          if (existingByName) {
            ensureReplicatedMode(existingByName);
            return toServiceAttributes(existingByName, desired.context, code);
          }

          const internalTags = yield* createInternalTags(id);
          const allDesiredLabels = { ...internalTags, ...desired.labels };
          yield* docker.service.create({
            context: desired.context,
            name: desired.name,
            image,
            replicas: desired.replicas,
            "endpoint-mode": desired.endpointMode,
            network: desired.networks.map(formatNetwork),
            constraint: desired.constraints,
            "replicas-max-per-node": desired.maxReplicasPerNode,
            "placement-pref": desired.preferences,
            "update-parallelism": desired.updateConfig?.parallelism,
            "update-delay": desired.updateConfig?.delay,
            "update-monitor": desired.updateConfig?.monitor,
            "update-failure-action": desired.updateConfig?.failureAction,
            "update-max-failure-ratio": desired.updateConfig?.maxFailureRatio,
            "update-order": desired.updateConfig?.order,
            "rollback-parallelism": desired.rollbackConfig?.parallelism,
            "rollback-delay": desired.rollbackConfig?.delay,
            "rollback-monitor": desired.rollbackConfig?.monitor,
            "rollback-failure-action": desired.rollbackConfig?.failureAction,
            "rollback-max-failure-ratio": desired.rollbackConfig?.maxFailureRatio,
            "rollback-order": desired.rollbackConfig?.order,
            "restart-condition": desired.restartPolicy?.condition,
            "restart-delay": desired.restartPolicy?.delay,
            "restart-max-attempts": desired.restartPolicy?.maxAttempts,
            "restart-window": desired.restartPolicy?.window,
            "health-cmd": desired.healthcheck
              ? healthcheckCommand(desired.healthcheck.cmd)
              : undefined,
            "no-healthcheck":
              desired.healthcheck !== undefined && isHealthcheckDisabled(desired.healthcheck.cmd),
            "health-interval": desired.healthcheck?.interval,
            "health-timeout": desired.healthcheck?.timeout,
            "health-retries": desired.healthcheck?.retries,
            "health-start-period": desired.healthcheck?.startPeriod,
            "stop-grace-period": desired.stopGracePeriod,
            mount: desired.volumes.map(formatMount),
            secret: desired.secrets.map(formatRef),
            config: desired.configs.map(formatRef),
            "read-only": desired.readOnlyRootFs || undefined,
            publish: desired.ports.map(formatPublish),
            label: allDesiredLabels,
            env: environment,
            command: desired.command,
            args: desired.args,
          });
          return toServiceAttributes(
            yield* inspectOrDie(inspect, desired.name, desired.context),
            desired.context,
            code,
          );
        }),
        delete: Effect.fn(({ output }) =>
          docker
            .run([
              ...(output.context ? ["--context", output.context] : []),
              "service",
              "scale",
              "--detach=false",
              `${output.id}=0`,
            ])
            .pipe(
              Effect.flatMap(() => docker.service.remove(output.id, output.context)),
              Effect.flatMap(() =>
                waitForServiceContainersReleased(docker, output.id, output.context),
              ),
              Effect.catchReason("PlatformError", "NotFound", () => Effect.void),
              // Best-effort: drop the content-addressed image built for a
              // bundled program so replaced/destroyed services don't strand
              // local image tags.
              Effect.andThen(
                output.code
                  ? docker.image
                      .remove(output.image, true, output.context)
                      .pipe(Effect.catchCause(() => Effect.void))
                  : Effect.void,
              ),
            ),
        ),
      });
    }),
  );

/** Swarm rejects service names longer than 63 characters. */
const servicePhysicalName = (
  id: string,
  props: { name?: string } | undefined,
  instanceId: string,
) => dockerPhysicalName(id, props, instanceId, 63);

const normalizeDesired = (id: string, props: ServiceProps, instanceId: string) =>
  servicePhysicalName(id, props, instanceId).pipe(
    Effect.map((name) => ({
      name,
      context: dockerEngineContextName(props.context),
      // The bundled form's image identity is its content hash (compared
      // separately in diff) — the `image` prop is only the environment base
      // there, and it participates in the hash.
      image: isBundledService(props) ? undefined : normalizeImageRef(props.image),
      command: props.command ?? [],
      args: props.args ?? [],
      environment: {
        ...normalizeEnvironment(props.environment),
        ...normalizeBoundEnv(props.env),
      },
      networks: normalizeNetworks(props.networks),
      ports: normalizePorts(props.ports),
      endpointMode: props.endpointMode ?? "vip",
      replicas: normalizeReplicas(props.replicas),
      constraints: [...(props.constraints ?? []), ...(props.placement?.constraints ?? [])],
      maxReplicasPerNode: props.placement?.maxReplicasPerNode,
      preferences: props.placement?.preferences ?? [],
      updateConfig: props.updateConfig,
      rollbackConfig: props.rollbackConfig,
      restartPolicy: props.restartPolicy,
      healthcheck: props.healthcheck,
      stopGracePeriod: props.stopGracePeriod,
      volumes: props.volumes ?? [],
      secrets: props.secrets ?? [],
      configs: props.configs ?? [],
      readOnlyRootFs: props.readOnlyRootFs ?? false,
      labels: props.labels ?? {},
    })),
  );

type DesiredService = Effect.Success<ReturnType<typeof normalizeDesired>>;

/**
 * Fields `docker service update` changes in place. Swarm rolls the tasks
 * onto the new spec following `updateConfig`, so `order: "start-first"` and
 * `failureAction: "rollback"` apply.
 */
const inPlaceFields = new Set<keyof DesiredService>([
  "image",
  "replicas",
  "environment",
  "labels",
  "networks",
  "constraints",
  "maxReplicasPerNode",
  "updateConfig",
  "rollbackConfig",
  "restartPolicy",
  "healthcheck",
  "stopGracePeriod",
  "volumes",
  "secrets",
  "configs",
  "ports",
]);

/**
 * Settings `service update` can change but not reset to the engine default:
 * removing one, or a field inside one, replaces the service.
 */
const resettableFields = new Set<keyof DesiredService>([
  "maxReplicasPerNode",
  "updateConfig",
  "rollbackConfig",
  "restartPolicy",
  "healthcheck",
  "stopGracePeriod",
]);

const clearsSetting = (olds: unknown, news: unknown): boolean => {
  if (olds === undefined) return false;
  if (news === undefined) return true;
  if (typeof olds !== "object" || olds === null) return false;
  return Object.entries(olds).some(
    ([key, value]) => value !== undefined && (news as Record<string, unknown>)[key] === undefined,
  );
};

/**
 * `--publish-rm` matches target, protocol and mode, and `--publish-add` skips
 * a port already in the spec. Dropping one of several ports that share a
 * target therefore drops the kept ones too, so that change replaces.
 */
const dropsSharedTargetPort = (olds: DesiredService, news: DesiredService): boolean => {
  const kept = new Set(news.ports.map(formatPublish));
  const key = (port: Service.PortMapping) => `${port.internal}/${port.protocol}/${port.mode}`;
  const removedKeys = new Set(olds.ports.filter((p) => !kept.has(formatPublish(p))).map(key));
  return olds.ports.some((p) => kept.has(formatPublish(p)) && removedKeys.has(key(p)));
};

const requiresReplacement = (olds: DesiredService, news: DesiredService): boolean =>
  dropsSharedTargetPort(olds, news) ||
  (Object.keys(news) as Array<keyof DesiredService>).some(
    (key) =>
      !deepEqual(olds[key], news[key]) &&
      (!inPlaceFields.has(key) ||
        (resettableFields.has(key) && clearsSetting(olds[key], news[key]))),
  );

const normalizeImageRef = (image: Service.Image): string =>
  typeof image === "string" ? image : image.imageRef;

const normalizeEnvironment = (
  environment: Record<string, string | Redacted.Redacted<string>> | undefined,
) =>
  Object.fromEntries(
    Object.entries(environment ?? {}).map(([key, value]) => [
      key,
      Redacted.isRedacted(value) ? Redacted.value(value) : value,
    ]),
  );

/**
 * Platform-injected env (`props.env`) after Output resolution: values are
 * usually marker-packed strings, but tolerate Redacted and structured values.
 */
const normalizeBoundEnv = (env: Record<string, any> | undefined): Record<string, string> =>
  Object.fromEntries(
    Object.entries(env ?? {}).map(([key, value]) => [
      key,
      typeof value === "string"
        ? value
        : Redacted.isRedacted(value)
          ? Redacted.value(value as Redacted.Redacted<string>)
          : JSON.stringify(value),
    ]),
  );

const normalizePorts = (ports: Service.PortMapping[] | undefined): Service.PortMapping[] =>
  (ports ?? []).map((port) => ({
    external: port.external,
    internal: port.internal,
    protocol: port.protocol ?? "tcp",
    mode: port.mode ?? "ingress",
  }));

const normalizeReplicas = (replicas: number | undefined): number => {
  const value = replicas ?? 1;
  if (!Number.isInteger(value) || value < 0) {
    throw new Error("Service.replicas must be an integer >= 0");
  }
  return value;
};

const normalizeNetworks = (
  networks: Array<string | Service.NetworkAttachment> | undefined,
): Service.NetworkAttachment[] =>
  (networks ?? []).map((network) =>
    typeof network === "string"
      ? { name: network }
      : { name: network.name, aliases: network.aliases },
  );

const formatMount = (volume: Service.VolumeMapping): string =>
  [
    `type=${/^(\/|\.\/|\.\.\/|~)/.test(volume.hostPath) ? "bind" : "volume"}`,
    `source=${volume.hostPath}`,
    `target=${volume.containerPath}`,
    ...(volume.readOnly ? ["readonly=true"] : []),
  ].join(",");

const formatNetwork = (network: Service.NetworkAttachment): string =>
  [`name=${network.name}`, ...(network.aliases ?? []).map((a) => `alias=${a}`)].join(",");

const formatRef = (ref: Service.SecretRef | Service.ConfigRef): string =>
  Object.entries(ref)
    .filter(([, value]) => value !== undefined)
    .map(([key, value]) => `${key}=${value}`)
    .join(",");

const formatPublish = (port: Service.PortMapping): string =>
  [
    ...(port.external !== undefined ? [`published=${port.external}`] : []),
    `target=${port.internal}`,
    `protocol=${port.protocol ?? "tcp"}`,
    `mode=${port.mode ?? "ingress"}`,
  ].join(",");

const toServiceAttributes = (
  service: ServiceInspect,
  context?: string,
  code?: { hash: string },
): Service["Attributes"] => ({
  id: service.ID,
  name: service.Spec.Name,
  context,
  image: service.Spec.TaskTemplate?.ContainerSpec?.Image ?? "",
  replicas: service.Spec.Mode?.Replicated?.Replicas ?? 1,
  networks: (service.Spec.TaskTemplate?.Networks ?? []).flatMap((n) =>
    n.Target ? [n.Target] : [],
  ),
  ports: (service.Spec.EndpointSpec?.Ports ?? []).flatMap((port) => {
    if (port.PublishedPort === undefined || port.TargetPort === undefined) {
      return [];
    }
    return [
      {
        external: port.PublishedPort,
        internal: port.TargetPort,
        protocol: port.Protocol ?? "tcp",
        mode: port.PublishMode ?? "ingress",
      },
    ];
  }),
  labels: service.Spec.Labels ?? {},
  endpointMode: service.Spec.EndpointSpec?.Mode ?? "vip",
  createdAt: Date.parse(service.CreatedAt ?? "") || Date.now(),
  updatedAt: Date.parse(service.UpdatedAt ?? "") || Date.now(),
  code,
});

const ensureReplicatedMode = (service: ServiceInspect): void => {
  if (service.Spec.Mode?.Global !== undefined) {
    throw new Error(
      `Docker.Service only supports replicated services. Service "${service.Spec.Name}" is global.`,
    );
  }
};

const parseInspectArray = <T>(json: string): T => {
  const parsed = JSON.parse(json) as T[];
  if (parsed.length === 0) {
    throw new Error("docker inspect returned no objects");
  }
  return parsed[0]!;
};

const normalizeServiceInspect = (value: unknown): ServiceInspect => {
  if (typeof value === "object" && value !== null && "stdout" in value) {
    const stdout = (value as { stdout?: unknown }).stdout;
    if (typeof stdout === "string") {
      return parseInspectArray<ServiceInspect>(stdout);
    }
  }
  return value as ServiceInspect;
};

const inspectOrDie = <T>(
  inspect: (nameOrId: string, context?: string) => Effect.Effect<T | undefined, any>,
  nameOrId: string,
  context?: string,
) =>
  inspect(nameOrId, context).pipe(
    Effect.flatMap((value) =>
      value ? Effect.succeed(value) : Effect.die(`Expected ${nameOrId} to exist after create`),
    ),
  );

const waitForServiceContainersReleased = (
  docker: Docker["Service"],
  serviceId: string,
  context?: string,
): Effect.Effect<void, PlatformError> => {
  const maxAttempts = 10;
  const noContainers = Symbol.for("Docker.Service.NoContainers");

  const poll = listServiceContainerIds(docker, serviceId, context).pipe(
    Effect.flatMap((containerIds) =>
      containerIds.length === 0 ? Effect.fail(noContainers) : Effect.succeed(containerIds),
    ),
  );

  return poll.pipe(
    Effect.repeat(Schedule.spaced("1 second").pipe(Schedule.upTo({ times: maxAttempts - 1 }))),
    Effect.catchIf(
      (error): error is typeof noContainers => error === noContainers,
      () => Effect.void,
    ),
    Effect.andThen(listServiceContainerIds(docker, serviceId, context)),
    Effect.flatMap((containerIds) =>
      containerIds.length === 0
        ? Effect.void
        : // Best effort cleanup for lingering task containers that keep volumes attached.
          Effect.forEach(
            containerIds,
            (containerId) =>
              docker
                .run([
                  ...(context ? ["--context", context] : []),
                  "container",
                  "rm",
                  "-f",
                  containerId,
                ])
                .pipe(Effect.catchCause(() => Effect.void)),
            { concurrency: "unbounded" },
          ).pipe(Effect.as(undefined)),
    ),
  );
};

const listServiceContainerIds = (
  docker: Docker["Service"],
  serviceId: string,
  context?: string,
): Effect.Effect<string[], PlatformError> =>
  docker
    .run([
      ...(context ? ["--context", context] : []),
      "ps",
      "-a",
      "--filter",
      `label=com.docker.swarm.service.id=${serviceId}`,
      "--format",
      "{{.ID}}",
    ])
    .pipe(
      Effect.map((result) =>
        result.stdout
          .split("\n")
          .map((line) => line.trim())
          .filter((line) => line.length > 0),
      ),
    );