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

import { DockerLive, Docker } from "@alchemy.run/docker/Docker";
import type {
  FlyMachineConfig,
  FlyMachineGuest,
  FlyMachineMount,
  FlyMachineService,
  FlyStatic,
  Machine as FlyMachine,
} from "@distilled.cloud/fly-io/machines";
import * as machines from "@distilled.cloud/fly-io/machines";
import { AlchemyContext } from "alchemy/AlchemyContext";
import * as Bundle from "alchemy/Bundle/Bundle";
import { deepEqual, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { Platform, type Main, type MainRpc, type PlatformProps } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import { makeRandom } from "alchemy/Random";
import type { Resource } from "alchemy/Resource";
import type { ServerHost } from "alchemy/Runtime/Process";
import { packEnvValue } from "alchemy/RuntimeContext";
import { Stack } from "alchemy/Stack";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Redacted from "effect/Redacted";
import { App, deleteApp, ensureApp } from "./App.ts";
import { boundTargetEnvKeys } from "./BindService.ts";
import { attachBucketSecrets } from "./Bucket.ts";
import {
  deploymentPolicy,
  validateDeployment,
  type MachineDeploy,
  type MachineShutdown,
  type MachineCheck,
} from "./Deployment.ts";
import { resolveOrgSlug } from "./Environment.ts";
import {
  collectBindingState,
  createFlyHostedSupport,
  createFlyHostRuntimeContext,
  defaultHttpServices,
  DEFAULT_PORT,
  toEnvRecord,
  type FlyBuildOptions,
  type FlyHostRuntimeContext,
  type HostedProgramProps,
} from "./hosted.ts";
import { ensureFlycastAddress, hasPublicAddress, syncOwnedAppAddresses } from "./IpAssignment.ts";
import type { MachineGuest, MachineImageRef, MachineService } from "./Machine.ts";
import {
  alchemyMetadataKeys,
  createFlyAppName,
  createFlyResourceName,
  diffMachineMetadata,
  matchesAlchemyPhysicalName,
  sanitizeFlyAppName,
} from "./Metadata.ts";
import type { BoundTarget, MountedDisk, ServiceBinding } from "./MountVolume.ts";
import { bindingPortOf, findPortConflict, portsOfFly } from "./ports.ts";
import { attachPostgresSecrets } from "./Postgres.ts";
import type { Providers } from "./Providers.ts";
import { attachRedisSecrets } from "./Redis.ts";
import { type Region, regionList } from "./Region.ts";
import {
  deleteReplicaSet,
  hasPublishedService,
  listReplicaSets,
  observeReplicaSet,
  reconcileReplicas,
  resolveCount,
  sameServices,
  toFlyService,
  volumeIdsOf,
  type Replica,
  type ReplicaSet,
} from "./replicas.ts";
import { BINDING_PORT_ENV, DEFAULT_BINDING_PORT, RPC_ORG_ENV, RPC_TOKEN_ENV } from "./rpc.ts";

/**
 * A resource-valued prop: the resource itself, or an Effect that produces
 * it (so `yield* App(...)` and `App(...)` both type-check).
 */
type Ref<T> = T | Effect.Effect<T, never, Providers>;

const DEFAULT_REGION = "iad";
const DEFAULT_CPU_KIND = "shared";
const DEFAULT_CPUS = 1;
const DEFAULT_MEMORY_MB = 256;

export interface ServiceProps extends PlatformProps {
  /** Deployment strategy and readiness deadline. Defaults to in-place rolling updates. */
  deploy?: MachineDeploy;
  /** Graceful process shutdown. Defaults to SIGTERM / 30 seconds when blue/green is enabled. */
  shutdown?: MachineShutdown;
  /** Named readiness checks for workers without public services. */
  checks?: Record<string, MachineCheck>;
  /**
   * Run inside an existing {@link App} instead of the Service's own App.
   * The Service then shares that App's hostname, addresses, and secrets,
   * and Alchemy does not manage addresses for it. Accepts a `Fly.App` or
   * an Effect that produces one. Changing it, or adding or removing it,
   * replaces the Service.
   *
   * By default each Service owns its App, so it gets its own
   * `{name}.fly.dev` hostname, addresses, logs, and metrics.
   */
  app?: Ref<App>;
  /**
   * Whether the Service is reachable from the internet. A public Service
   * gets a shared IPv4 and an IPv6 and serves `https://{name}.fly.dev`. A
   * private Service is reachable only from other Apps in the organization,
   * at `http://{name}.flycast`. Every address is free. Only applies when
   * the Service owns its App (no `app`).
   *
   * @default true
   */
  public?: boolean;
  /**
   * Private network the Service's App joins. Only Apps on the same
   * network can reach it, over `privateUrl` or `.internal`; every other
   * App in the organization, including those on the default network,
   * cannot resolve it. Services on one network reach each other freely.
   * Use {@link stackNetwork} for a network unique to the stack and stage.
   * Fly creates the network with the first App that names it. Changing
   * it replaces the Service. Only applies when the Service owns its App
   * (no `app`).
   *
   * @default the organization's default network, shared by every App
   */
  network?: string;
  /**
   * Plain-HTTP port Alchemy publishes for callers that bind this Service
   * with {@link bindService}, when the Service publishes no plain-HTTP port
   * of its own (a public Service's defaults are an HTTPS redirect on 80 and
   * HTTPS on 443). Fly issues no certificate for `.flycast`, so bound
   * callers use plain HTTP inside Fly's WireGuard-encrypted private network.
   * Requests on this port must come from Fly's private network. Change it
   * when the port collides with another Service in the same App.
   *
   * @default 7780
   */
  bindingPort?: number;
  /**
   * Caller token for bound callers. Set automatically from an
   * `Alchemy.Random` child resource; do not pass it.
   * @internal
   */
  rpcToken?: Redacted.Redacted<string>;
  /**
   * Module entrypoint bundled with rolldown and baked into a Docker
   * image pushed to `registry.fly.io`. Typically `import.meta.url`.
   * A content-hash change updates the workload using the selected deployment strategy.
   */
  main: string;
  /**
   * Region or regions to run in (`"iad"`, `["iad", "lhr"]`). The
   * Service runs `count` Machines in each region behind one hostname;
   * Fly's proxy sends each request to the nearest healthy Machine.
   * Adding or removing a region updates the Service in place: Machines
   * in a removed region are deleted, new regions get new Machines.
   *
   * @default "iad"
   */
  region?: Region | Region[];
  /**
   * Number of Machines to provision in each region, including
   * stopped/suspended idle capacity. Fly's proxy load-balances
   * `{app}.fly.dev` across available replicas.
   * Blue/green checks a representative and the required running floor while
   * preserving idle nonrepresentatives. Each replica gets its own Volume
   * from every `MountVolume` binding; attached volumes require rolling updates.
   *
   * @default 1
   */
  count?: number;
  /**
   * Guest size. Defaults to shared-cpu-1x 256 MB.
   */
  guest?: MachineGuest;
  /**
   * Port the hosted HTTP server listens on. Written to `PORT` and used
   * as the Fly proxy `internal_port`.
   *
   * @default 3000
   */
  port?: number;
  /**
   * Named export to load from `main`.
   *
   * @default "default"
   */
  handler?: string;
  /**
   * Additional environment variables for the hosted process. Merged
   * after binding-injected `env`.
   */
  env?: Record<string, any>;
  /**
   * Bundler configuration for `main`: rolldown `input`/`output`
   * overrides, pure-annotation options (`pure`), and `install` for
   * packages that must ship as real `node_modules` (see {@link FlyBuildOptions}).
   */
  build?: FlyBuildOptions;
  /**
   * Environment image used as the generated Dockerfile's `FROM`. Must
   * be able to run Node (websites and Effect-native Services use Node
   * in production).
   *
   * @default "node:26-slim"
   */
  image?: string;
  /**
   * Fly proxy services. Defaults to HTTP 80 + HTTPS 443 → {@link port}.
   */
  services?: MachineService[];
  /**
   * Name of the Service's App, which is its `{name}.fly.dev` and
   * `{name}.flycast` hostname. Globally unique across Fly. If omitted, a
   * unique name is generated from the stack, stage and logical ID.
   * Changing it replaces the Service.
   *
   * When `app` is set, this is instead the Machine name (unique per App;
   * in blue/green mode a base for generation-qualified physical names).
   */
  name?: string;
  /**
   * Extra host directories copied into the Machine image next to the
   * bundled entry (e.g. a website `clientDirectory` at `/app/dist`).
   * Hashed into `code.hash` so asset changes update the image.
   * Destination is relative to `/app`.
   */
  extraFiles?: ReadonlyArray<{ source: string; dest: string }>;
  /**
   * Fly proxy static-file maps. Matching GET paths skip the process and
   * are served from the image (`guestPath`) or a Tigris bucket
   * (`tigrisBucket`). Website composites publish hashed client assets
   * this way.
   */
  statics?: ReadonlyArray<{
    /** Path inside the image, or key prefix in {@link tigrisBucket}. */
    guestPath: string;
    /** URL prefix, e.g. `"/"`. */
    urlPrefix: string;
    /** Tigris bucket name. When set, files come from the bucket. */
    tigrisBucket?: string;
    /** Directory index file (`index.html`) for Tigris statics. */
    indexDocument?: string;
  }>;
}

/** A port the Service publishes on Fly's proxy. */
export interface ServiceEndpoint {
  /**
   * Hostname the port is published on: `{appName}.fly.dev`, or
   * `{appName}.flycast` for a private Service.
   */
  host: string;
  /** Port on Fly's proxy. */
  port: number;
  /** Port the process listens on inside the Machine. */
  internalPort: number | undefined;
  /** `tcp` or `udp`. */
  protocol: string;
  /** Fly proxy handlers (`tls`, `http`, `pg_tls`, …). Empty for raw TCP or UDP. */
  handlers: string[];
  /**
   * URL when the port speaks HTTP: `https://` for `tls` + `http`, `http://`
   * for plain `http`, with `:{port}` unless it is 443 or 80. `undefined`
   * for other protocols, and for TLS ports on `.flycast` (Fly issues no
   * certificate there).
   */
  url: string | undefined;
}

export type Service = Resource<
  "Fly.Service",
  ServiceProps,
  {
    /** Whether recovery must finish an interrupted deployment. */
    rolloutPending?: boolean;
    /** Fly App name the Machines run in. */
    appName: string;
    /** Whether the Service created and manages {@link appName}. */
    ownsApp?: boolean;
    /**
     * Private network the Service's Machines are on: `network`, or the
     * shared App's network. `undefined` for the organization's default.
     */
    network?: string;
    /** Token bound callers send with RPC calls. */
    rpcToken?: Redacted.Redacted<string>;
    /** Fly Machine id of replica 0. */
    machineId: string;
    /** Fly Machine ids of every replica. */
    machineIds: string[];
    /** Logical base for generation-qualified Machine names. */
    baseName?: string;
    /** Machine name of replica 0 (unique per App). Changes during blue/green deployment. */
    name: string;
    /** Region of the first Machine. */
    region: string;
    /** Every region the Service's Machines run in. */
    regions: string[];
    /** Observed state of replica 0 (`created`, `started`, `stopped`, …). */
    state: string;
    /**
     * Main public HTTP endpoint: the first published `tls` + `http` port
     * as `https://{appName}.fly.dev[:port]`, else the first plain `http`
     * port as `http://{appName}.fly.dev[:port]`. `https://{appName}.fly.dev`
     * for the default services. `undefined` for a private Service or when
     * no port speaks HTTP. When `app` is set, the App's addresses are
     * managed elsewhere, so this is where the Service answers once the App
     * is reachable. See {@link endpoints} for every published port.
     */
    url: string | undefined;
    /**
     * Every port the Service publishes, in declaration order. Ports that
     * only redirect HTTP to HTTPS (`forceHttps`) and port ranges are
     * omitted. Empty when nothing is published.
     */
    endpoints: ServiceEndpoint[];
    /**
     * Address bound callers use over Fly's private network:
     * `http://{appName}.flycast`, with the port when it is not 80. It is
     * the Service's first plain-HTTP port, or {@link ServiceProps.bindingPort}
     * when it has none. Reachable only from Apps on the Service's network.
     * `undefined` when nothing is published.
     */
    privateUrl: string | undefined;
    /** Parsed image reference from Fly. */
    imageRef: MachineImageRef | undefined;
    /** Number of Machines in each region. */
    count: number;
    /** Disks mounted on replica 0. */
    mounts: MountedDisk[];
    /** Every replica in the set. */
    replicas: Replica[];
    /** Content hash of the bundled program's image. */
    code: { hash: string };
  },
  ServiceBinding,
  Providers
>;

export const isService = (value: unknown): value is Service =>
  typeof value === "object" &&
  value !== null &&
  (value as { Type?: string }).Type === "Fly.Service";

export type ServiceServices = ServerHost;

/**
 * What a Service's program returns: `fetch` for HTTP, `run` for a
 * background loop, and any other methods, which bound callers invoke
 * with {@link bindService}.
 */
export type ServiceShape =
  | Main<ServiceServices>
  | (Exclude<Main<ServiceServices>, void> & MainRpc<ServiceServices>);

export type ServiceRuntimeContext = FlyHostRuntimeContext;

/**
 * A Service is an Effect program running on Fly.io Machines in its own
 * Fly App. It gets its own `{name}.fly.dev` hostname, addresses, logs,
 * and metrics, the way each Cloudflare Worker is its own endpoint. Set
 * `count` to scale it up or down.
 *
 * @see https://fly.io/docs/machines/api/machines-resource/
 *
 * ### Declare a Service
 * A Service is a class. Props describe the Machine. The Effect is the
 * program that runs on it.
 *
 * The Service creates its Fly App, and deleting the Service deletes it.
 * `main: import.meta.url` is the bundle entrypoint. Alchemy bundles this
 * file with Rolldown, builds a Docker image (default `node:26-slim`), and
 * pushes it to `registry.fly.io/{app}:{id}-{hash}`.
 *
 * **Example:** Class + main
 * ```typescript
 * // src/api.ts
 * import * as Fly from "@alchemy.run/fly";
 * import * as Effect from "effect/Effect";
 *
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     return {};
 *   }),
 * ) {}
 * ```
 *
 * ### Serve HTTP with fetch
 * Return `fetch` from the init Effect to boot an HTTP server. Omit
 * `fetch` for a background service.
 *
 * **Example:** Hello
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Pin a region
 * Fly Machines live in a region. Default is `iad`. See
 * [Regions](/fly/compute/regions) for the list of codes.
 *
 * **Example:** Region
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, region: "iad" },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Run in several regions
 * Pass a list to run the same program in several regions behind one
 * hostname. `count` Machines run in each region, and Fly's proxy sends
 * each request to the nearest healthy one. `regions` on the Service
 * lists where it runs.
 *
 * **Example:** Two regions, two Machines each
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, region: ["iad", "lhr"], count: 2 },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * Adding or removing a region updates the Service in place and keeps
 * its App and hostname. Machines already in a kept region stay; a
 * removed region's Machines are deleted. Each Machine's Volume from
 * `MountVolume` is created in that Machine's region.
 *
 * ### Set the port
 * `port` is the port the process listens on inside the Machine.
 * Alchemy writes it to `PORT`. Default is `3000`.
 *
 * **Example:** Port 3000
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, region: "iad", port: 3000 },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### The public URL
 * A Service is public by default. Alchemy allocates a shared IPv4 and
 * an IPv6 on its App (both free) and `api.url` is
 * `https://{appName}.fly.dev`.
 *
 * **Example:** Stack output
 * ```typescript
 * export default Alchemy.Stack(
 *   "MyApp",
 *   { providers: Fly.providers(), state: Alchemy.localState() },
 *   Effect.gen(function* () {
 *     const api = yield* Api;
 *     return { url: api.url };
 *   }),
 * );
 * ```
 *
 * `url` is `undefined` when you pass `services: []` (nothing is
 * published).
 *
 * ### Every published port
 * `url` is one endpoint. A Service that publishes several ports has one
 * endpoint per port at the same hostname, listed in `endpoints` with
 * its port, handlers, and a URL when the port speaks HTTP. Ports that
 * only redirect to HTTPS are left out.
 *
 * **Example:** An admin UI on 8443 and raw TCP on 7000
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   {
 *     main: import.meta.url,
 *     services: [
 *       {
 *         internalPort: 3000,
 *         ports: [
 *           { port: 80, handlers: ["http"], forceHttps: true },
 *           { port: 443, handlers: ["tls", "http"] },
 *         ],
 *       },
 *       { internalPort: 9000, ports: [{ port: 8443, handlers: ["tls", "http"] }] },
 *       { internalPort: 7000, ports: [{ port: 7000 }] },
 *     ],
 *   },
 *   Effect.gen(function* () {
 *     return {};
 *   }),
 * ) {}
 *
 * api.url; // "https://{appName}.fly.dev"
 * api.endpoints.map((endpoint) => endpoint.url);
 * // ["https://{appName}.fly.dev", "https://{appName}.fly.dev:8443", undefined]
 * ```
 *
 * :::note[Plain HTTP on other ports needs IPv6]
 * The free shared IPv4 serves TLS on any port but plain HTTP only on
 * port 80. A plain-HTTP port such as 8080 answers over IPv6 only.
 * :::
 *
 * ### Private Services
 * `public: false` keeps a Service off the internet. It gets only a
 * Flycast address and publishes plain HTTP on port 80 (Fly issues no
 * certificate for `.flycast`). `url` is `undefined`, and `privateUrl` is
 * `http://{appName}.flycast`. Calls go through Fly's proxy, so service
 * checks, `autostart`, and blue/green cutover still apply.
 *
 * Turning `public` on or off updates the Service in place. Its App and
 * hostname stay the same.
 *
 * ### Call another Service
 * A Service can return methods next to `fetch`. Another Service calls
 * them by binding it with {@link bindService}, which returns a typed
 * client. Binding makes the caller deploy after the Service, and only
 * callers that bind a Service receive its caller token, so only they
 * can call its methods.
 *
 * **Example:** A private Service with methods
 * ```typescript
 * export default class Users extends Fly.Service<Users>()(
 *   "Users",
 *   { main: import.meta.url, public: false },
 *   Effect.gen(function* () {
 *     return {
 *       list: () => Effect.succeed(USERS),
 *       get: (id: string) =>
 *         Effect.succeed(USERS.find((user) => user.id === id)),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * **Example:** Bind it from another Service
 * ```typescript
 * export default class Gateway extends Fly.Service<Gateway>()(
 *   "Gateway",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const users = yield* Fly.bindService(Users);
 *     return {
 *       fetch: Effect.gen(function* () {
 *         return yield* HttpServerResponse.json(yield* users.list());
 *       }).pipe(Effect.orDie),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * Calls use plain HTTP to `privateUrl` inside Fly's WireGuard-encrypted
 * private network. The Service accepts a method call only with its
 * caller token and a `Fly-Src` signature from Fly's proxy for the same
 * organization, so the public internet can never call it. A public
 * Service publishes an extra plain-HTTP port for bound callers,
 * `bindingPort` (default 7780), since its own ports are an HTTPS
 * redirect and HTTPS. `client.fetch` sends a request to the Service's
 * `fetch` routes, and {@link bindEndpoint} targets one published port.
 * Two Services can bind each other; declare them as tag classes and
 * provide their `.make` layers (see the
 * [Connect Services guide](/fly/compute/connecting-services)).
 *
 * ### Isolate Services on a private network
 * Fly's default private network spans the whole organization, so any
 * App in it can reach a private Service's address. Put a stack's
 * Services on their own network with `network`. {@link stackNetwork}
 * names one per stack and stage. Apps on other networks, including the
 * default one, cannot resolve them, and binding a Service on another
 * network fails the caller's deploy with `Fly.ServiceUnreachable`
 * before anything is created. A public Service on the network still
 * serves `url`, which makes it the stack's single entry point.
 *
 * **Example:** Private backend behind a public gateway
 * ```typescript
 * export class Users extends Fly.Service<Users>()(
 *   "Users",
 *   Effect.gen(function* () {
 *     return {
 *       main: import.meta.url,
 *       public: false,
 *       network: yield* Fly.stackNetwork,
 *     };
 *   }),
 *   Effect.gen(function* () {
 *     return { list: () => Effect.succeed(USERS) };
 *   }),
 * ) {}
 *
 * export class Gateway extends Fly.Service<Gateway>()(
 *   "Gateway",
 *   Effect.gen(function* () {
 *     return { main: import.meta.url, network: yield* Fly.stackNetwork };
 *   }),
 *   Effect.gen(function* () {
 *     const users = yield* Fly.bindService(Users);
 *     return {
 *       fetch: Effect.gen(function* () {
 *         return yield* HttpServerResponse.json(yield* users.list());
 *       }).pipe(Effect.orDie),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * :::caution[Changing `network` replaces the Service]
 * Fly cannot move an App between networks. Alchemy creates the Service
 * on the new network, then deletes the old App.
 * :::
 *
 * ### Fly's proxy is the load balancer
 * There is no LoadBalancer resource. Fly runs an Anycast proxy at
 * the edge.
 *
 * **Example:** Published ports
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, region: "iad", port: 3000 },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * Unless you override `services`, Alchemy publishes HTTP 80 and
 * HTTPS 443 on that proxy and points them at `port` inside each
 * Machine (`internal_port`). A request to
 * `https://{appName}.fly.dev` lands on Fly's edge. Fly terminates
 * TLS on 443, picks one started Machine that published this service,
 * and forwards to `port` where `fetch` runs.
 *
 * ### Configure routing health checks
 * The generated service includes a TCP check on `port`. To customize
 * it, provide `services` and configure each service's `checks` property.
 * With rolling updates, reconcile waits for each started replica's checks
 * before updating the next replica. Missing or non-passing results are
 * polled within `deploy.healthTimeout` (60 seconds by default), then fail
 * deployment with `Fly.ReplicaChecksNotPassing`. Later replicas remain
 * unchanged; earlier updates are not rolled back. A single rolling replica
 * can be unavailable. Blue/green checks replacements before retiring the
 * old set, with representative/floor readiness for idle capacity.
 *
 * **Example:** HTTP readiness check
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   {
 *     main: import.meta.url,
 *     port: 3000,
 *     services: [
 *       {
 *         protocol: "tcp",
 *         internalPort: 3000,
 *         ports: [
 *           { port: 80, handlers: ["http"], forceHttps: true },
 *           { port: 443, handlers: ["tls", "http"] },
 *         ],
 *         checks: [
 *           {
 *             type: "http",
 *             port: 3000,
 *             method: "GET",
 *             path: "/health",
 *             protocol: "http",
 *             interval: "15s",
 *             timeout: "2s",
 *             gracePeriod: "30s",
 *           },
 *         ],
 *       },
 *     ],
 *   },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Scale with count
 * `count` is how many Machines to provision, including idle capacity.
 * Default is `1`. Replicas publish the same proxy service behind
 * `{appName}.fly.dev`; Fly's proxy picks an available Machine per request.
 * Each replica gets its own Volume from every {@link MountVolume} binding;
 * attached volumes require rolling updates.
 *
 * **Example:** Three replicas
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, region: "iad", count: 3, port: 3000 },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Config
 * Yield `Config` in init. Alchemy reads the value from the env of
 * whoever deploys and writes it onto the Machine, so there is no need
 * to copy it into `env`.
 *
 * `Config.Redacted("API_KEY")` is `Redacted<string>`. Unwrap with
 * `Redacted.value` only where you need the raw string.
 *
 * Alchemy also injects `PORT` (when `port` is set) and stack metadata.
 * For a secret Fly should own and inject into every Machine on an App,
 * run the Service in an {@link App} (`app`) and use {@link Secret}.
 *
 * **Example:** Config.Redacted
 * ```typescript
 * import * as Config from "effect/Config";
 * import * as Redacted from "effect/Redacted";
 *
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, port: 3000 },
 *   Effect.gen(function* () {
 *     const apiKey = yield* Config.Redacted("API_KEY");
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const token = Redacted.value(apiKey);
 *         return HttpServerResponse.text("ok");
 *       }),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Mount a disk
 * Bind {@link MountVolume} inside init. App and region come from the
 * Service. `count: 3` creates three Volumes, one per replica. Provide
 * {@link MountVolumeLive}.
 *
 * **Example:** Per-replica disk
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, region: "iad", count: 3, port: 3000 },
 *   Effect.gen(function* () {
 *     const disk = yield* Fly.MountVolume({ path: "/data", sizeGb: 1 });
 *     const fs = yield* FileSystem.FileSystem;
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const text = yield* fs.readFileString(`${disk.path}/hello.txt`);
 *         return HttpServerResponse.text(text);
 *       }),
 *     };
 *   }).pipe(Effect.provide(Fly.MountVolumeLive)),
 * ) {}
 * ```
 *
 * ### Guest size
 * `guest` is CPU kind, CPU count, and memory. Default is shared-cpu,
 * 1 CPU, 256 MB. Set `gpuKind` and `gpus` for a GPU. Guest updates in
 * place.
 *
 * **Example:** Bigger guest
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   {
 *     main: import.meta.url,
 *     region: "iad",
 *     port: 3000,
 *     guest: { cpuKind: "shared", cpus: 2, memoryMb: 512 },
 *   },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### A stable hostname
 * `name` names the Service's App, so it is the `{name}.fly.dev`
 * hostname. App names are globally unique across Fly. Omit `name` and
 * Alchemy generates one from the stack, stage, and logical ID.
 *
 * **Example:** Explicit name
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, name: "api", port: 3000 },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * :::caution[Changing `name` replaces the Service]
 * Fly cannot rename an App. Alchemy creates the Service under the new
 * name, then deletes the old App.
 * :::
 *
 * ### Named export
 * `handler` is the named export to load from `main`. Default is
 * `"default"`.
 *
 * **Example:** Custom handler
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { main: import.meta.url, handler: "api", port: 3000 },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Base image
 * `image` is the generated Dockerfile's `FROM`. Default is
 * `node:26-slim`. A content-hash change of `main` updates the
 * Machine in place.
 *
 * **Example:** Override FROM
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   {
 *     main: import.meta.url,
 *     image: "node:26",
 *     port: 3000,
 *   },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Custom proxy services
 * `services` defaults to HTTP 80 (redirecting to HTTPS) + HTTPS 443
 * toward `port`, or plain HTTP 80 for a private Service. Pass a custom
 * list to change handlers or autostop. Pass `[]` so Fly does not
 * publish a proxy.
 *
 * **Example:** Unpublished process
 * ```typescript
 * export default class Worker extends Fly.Service<Worker>()(
 *   "Worker",
 *   { main: import.meta.url, region: "iad", services: [] },
 *   Effect.gen(function* () {
 *     return {};
 *   }),
 * ) {}
 * ```
 *
 * ### Background services
 * Omit `port` and `fetch`. Pass `services: []`. Use `ServerHost.run`
 * for a long-running loop. If the process exits, Fly restarts it.
 *
 * **Example:** ServerHost.run
 * ```typescript
 * import { ServerHost } from "alchemy/Runtime/Process";
 *
 * export default class Worker extends Fly.Service<Worker>()(
 *   "Worker",
 *   { main: import.meta.url, region: "iad", services: [] },
 *   Effect.gen(function* () {
 *     const host = yield* ServerHost;
 *
 *     yield* host.run(
 *       Effect.gen(function* () {
 *         return yield* Effect.never;
 *       }).pipe(Effect.orDie),
 *     );
 *   }),
 * ) {}
 * ```
 *
 * ### Bundle config
 * `build` is Rolldown `input` / `output` overrides plus
 * pure-annotation options. Use it when `main` needs extra entry
 * points or externals.
 *
 * **Example:** Externals
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   {
 *     main: import.meta.url,
 *     port: 3000,
 *     build: { input: { external: ["sharp"] } },
 *   },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * **Example:** Install a native package unbundled
 * `build.install` runs `npm install` in the image for packages that
 * cannot be bundled, such as native addons — same `build.install` as
 * Lambda.
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   {
 *     main: import.meta.url,
 *     port: 3000,
 *     build: { install: ["sharp"] },
 *   },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Group Services in one App
 * Pass `app` to run a Service inside an existing {@link App} instead of
 * its own. The Services share the App's hostname, addresses, and
 * {@link Secret}s, and a {@link Certificate} on the App covers them.
 * Alchemy manages no addresses for a Service in a shared App: allocate
 * an {@link IpAssignment} on the App. `url` and `endpoints` follow the
 * Service's own ports, so Services in one App tell themselves apart by
 * port (`https://{appName}.fly.dev` and `https://{appName}.fly.dev:8443`).
 * `public` does not apply.
 *
 * **Example:** API and worker sharing a secret
 * ```typescript
 * export const Site = Fly.App("Site");
 *
 * class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { app: Site, main: import.meta.url, port: 3000 },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 *
 * class Worker extends Fly.Service<Worker>()(
 *   "Worker",
 *   { app: Site, main: import.meta.url, services: [] },
 *   Effect.gen(function* () {
 *     return {};
 *   }),
 * ) {}
 * ```
 *
 * Fly's proxy routes an App's traffic by port only, so each Service in
 * the App needs its own ports, including its own `bindingPort` when
 * Alchemy adds one. Two Services on the same port and protocol fail with
 * `Fly.ServicePortConflict` before any Machine is created: at plan time
 * when the App already exists, otherwise when the App deploys. Grouped
 * Services can be bound like any other; they cannot bind each other in
 * a cycle.
 *
 * ### Blue/green deployments
 * Opt into healthy replacement Machines instead of in-place updates.
 * The default TCP service check proves the server is listening; supply
 * service HTTP checks when readiness also depends on application state.
 *
 * **Example:** Single-replica HTTP replacement
 * ```typescript
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   {
 *     main: import.meta.url,
 *     deploy: { strategy: "bluegreen" },
 *     shutdown: { timeout: "30 seconds" },
 *   },
 *   Effect.succeed({ fetch: Effect.succeed(HttpServerResponse.text("ready")) }),
 * ) {}
 * ```
 *
 * Keep one Service declaration. The old process retains its own shutdown
 * signal and deadline when the replacement's policy changes. Managed
 * SIGTERM/SIGINT shutdown drains HTTP while runtime resource finalizers run;
 * shared dependencies remain alive until both settle or the deadline expires.
 * Applications own stop-acquisition barriers, separately scoped jobs, and
 * bounded drain or checkpoint logic using ordinary finalizers, not a new
 * shutdown hook. External servers own their signal handling. An old bootstrap
 * cannot gain handlers retroactively. Volumes are incompatible with blue/green;
 * physical IDs and names change. Service-bound secret versions are floors,
 * not vault snapshots, and native Machine leases are not deployment-wide locks.
 * Leases do not serialize vault writers or every simultaneous first deployment;
 * serialize CI invocations for the same resource.
 *
 * Stop and suspend autostop policies preserve idle nonrepresentatives while
 * a representative and the required running floor pass readiness. Requested
 * idle policy is restored before old retirement; a new instance needs fresh
 * checks. Suspension is not SIGTERM shutdown and does not run ordinary
 * shutdown finalizers. Replacements do not inherit suspended process memory.
 * See the [deployment guide](/fly/compute/deployments) for recovery,
 * idle capacity, application responsibilities, and verification limits.
 *
 * @resource
 * @product Service
 */
export const Service: Platform<Service, ServiceServices, ServiceShape, ServiceRuntimeContext> =
  Platform("Fly.Service", {
    createRuntimeContext: createFlyHostRuntimeContext("Fly.Service"),
    // `{ app: Site }` at module scope is an Effect. Yield it here so the
    // App is registered and `news.app` is resolved attributes at
    // reconcile (same DX as `yield* App(...)` inside Effect.gen).
    transformProps: (id, props) =>
      Effect.gen(function* () {
        if (globalThis.__ALCHEMY_RUNTIME__) return props;
        const app = Effect.isEffect(props.app)
          ? yield* props.app as Effect.Effect<App, never, Providers>
          : props.app;
        // Only callers that bind this Service receive the token.
        const rpcToken = yield* makeRandom(`${id}RpcToken`);
        if (app !== undefined) {
          // Report the ports this Service publishes so the App can reject
          // two Services on the same port before either one is deployed.
          yield* app.bind(id, {
            service: id,
            services: props.services,
            bindingPort: props.bindingPort,
          });
        }
        return { ...props, app, rpcToken } as typeof props;
      }),
  });

export class ServiceNotCreated extends Data.TaggedError("Fly.ServiceNotCreated")<{
  resourceName: string;
  appName: string;
}> {}

export class InvalidServiceProps extends Data.TaggedError("Fly.InvalidServiceProps")<{
  message: string;
}> {}

export class ServiceAppNotResolved extends Data.TaggedError("Fly.ServiceAppNotResolved")<{
  message: string;
}> {}

const appNameOf = (value: unknown): string | undefined => {
  if (value == null || typeof value !== "object") return undefined;
  const name = (value as { appName?: unknown }).appName;
  return typeof name === "string" && name.length > 0 ? name : undefined;
};

const compactRecord = (
  record: Record<string, string | undefined> | null | undefined,
): Record<string, string> =>
  Object.fromEntries(
    Object.entries(record ?? {}).flatMap(([key, value]) =>
      value === undefined ? [] : [[key, value]],
    ),
  );

const toEnv = toEnvRecord;

const resolveMachineName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (name !== undefined) return sanitizeFlyAppName(name);
    if (existing !== undefined) return existing;
    return yield* createFlyResourceName(id);
  });

const toFlyGuest = (guest: MachineGuest | undefined): FlyMachineGuest => {
  const fly: FlyMachineGuest = {
    cpu_kind: guest?.cpuKind ?? DEFAULT_CPU_KIND,
    cpus: guest?.cpus ?? DEFAULT_CPUS,
    memory_mb: guest?.memoryMb ?? DEFAULT_MEMORY_MB,
  };
  if (guest?.gpuKind !== undefined) fly.gpu_kind = guest.gpuKind;
  if (guest?.gpus !== undefined) fly.gpus = guest.gpus;
  return fly;
};

const desiredEnv = (
  props: ServiceProps,
  bindingEnv: Record<string, any>,
  alchemyEnv: Record<string, string>,
  port: number,
): Record<string, string> => ({
  ...toEnv(bindingEnv),
  ...alchemyEnv,
  PORT: String(port),
  ...toEnv(props.env),
});

const toFlyStatics = (
  statics:
    | ReadonlyArray<{
        guestPath: string;
        urlPrefix: string;
        tigrisBucket?: string;
        indexDocument?: string;
      }>
    | undefined,
): FlyStatic[] | undefined => {
  if (statics === undefined || statics.length === 0) return undefined;
  return statics.map((entry) => ({
    guest_path: entry.guestPath,
    url_prefix: entry.urlPrefix,
    ...(entry.tigrisBucket !== undefined ? { tigris_bucket: entry.tigrisBucket } : {}),
    ...(entry.indexDocument !== undefined ? { index_document: entry.indexDocument } : {}),
  }));
};

const buildConfig = (input: {
  image: string;
  guest: FlyMachineGuest;
  env: Record<string, string>;
  services: FlyMachineService[];
  mounts: FlyMachineMount[];
  metadata: Record<string, string>;
  statics?: FlyStatic[];
}): FlyMachineConfig => ({
  image: input.image,
  guest: input.guest,
  env: Object.keys(input.env).length > 0 ? input.env : undefined,
  services: input.services.length > 0 ? input.services : undefined,
  mounts: input.mounts.length > 0 ? input.mounts : undefined,
  metadata: input.metadata,
  statics: input.statics !== undefined && input.statics.length > 0 ? input.statics : undefined,
});

const sameImage = (machine: FlyMachine, image: string) => {
  const configImage = machine.config?.image;
  if (configImage === image) return true;
  const ref = machine.image_ref;
  const colon = image.lastIndexOf(":");
  const slash = image.lastIndexOf("/");
  const split = colon > slash ? colon : -1;
  const repo = split === -1 ? image : image.slice(0, split);
  const tag = split === -1 ? "latest" : image.slice(split + 1);
  const observedRepo = ref?.repository;
  if (observedRepo === undefined || ref?.tag !== tag) return false;
  return observedRepo === repo || observedRepo.endsWith(`/${repo}`);
};

const sameGuest = (observed: FlyMachineGuest | undefined, desired: FlyMachineGuest) =>
  (observed?.cpu_kind ?? DEFAULT_CPU_KIND) === desired.cpu_kind &&
  (observed?.cpus ?? DEFAULT_CPUS) === desired.cpus &&
  (observed?.memory_mb ?? DEFAULT_MEMORY_MB) === desired.memory_mb &&
  observed?.gpu_kind === desired.gpu_kind &&
  observed?.gpus === desired.gpus;

const sameEnv = (
  observed: Record<string, string | undefined> | undefined,
  desired: Record<string, string>,
) => deepEqual(compactRecord(observed), desired);

const sameMounts = (observed: FlyMachineMount[] | undefined, desired: FlyMachineMount[]) => {
  const key = (mount: FlyMachineMount) => `${mount.volume ?? ""}:${mount.path ?? ""}`;
  const left = [...(observed ?? [])].map(key).sort();
  const right = desired.map(key).sort();
  return deepEqual(left, right);
};

const metadataChanged = (
  observed: Record<string, string | undefined> | undefined,
  desired: Record<string, string>,
) => {
  const { removed, added, updated } = diffMachineMetadata(compactRecord(observed), desired);
  return removed.length > 0 || Object.keys(added).length > 0 || Object.keys(updated).length > 0;
};

const sameStatics = (observed: FlyStatic[] | undefined, desired: FlyStatic[] | undefined) => {
  const normalize = (statics: FlyStatic[] | undefined) =>
    (statics ?? []).map((entry) => ({
      ...entry,
      // Empty and omitted index documents both disable directory indexes.
      index_document: entry.index_document === "" ? undefined : entry.index_document,
    }));
  return deepEqual(normalize(observed), normalize(desired), { stripNullish: true });
};

const configDrifted = (
  machine: FlyMachine,
  desired: {
    image: string;
    guest: FlyMachineGuest;
    env: Record<string, string>;
    services: FlyMachineService[];
    mounts: FlyMachineMount[];
    metadata: Record<string, string>;
    statics?: FlyStatic[];
  },
) => {
  const config = machine.config;
  return (
    !sameImage(machine, desired.image) ||
    !sameGuest(config?.guest, desired.guest) ||
    !sameEnv(config?.env, desired.env) ||
    !sameServices(config?.services, desired.services) ||
    !sameMounts(config?.mounts, desired.mounts) ||
    metadataChanged(config?.metadata, desired.metadata) ||
    !sameStatics(config?.statics, desired.statics)
  );
};

const withPort = (base: string, port: number, standard: number) =>
  port === standard ? base : `${base}:${port}`;

const isRedirect = (handlers: string[], forceHttps: boolean | undefined) =>
  forceHttps === true && handlers.includes("http") && !handlers.includes("tls");

/** Every published port on `host`, excluding HTTPS redirects and ranges. */
const endpointListOf = (
  host: string,
  services: FlyMachineService[] | undefined,
): ServiceEndpoint[] => {
  const flycast = host.endsWith(".flycast");
  return (services ?? []).flatMap((service) =>
    (service.ports ?? []).flatMap((entry) => {
      const handlers = entry.handlers ?? [];
      if (entry.port === undefined || isRedirect(handlers, entry.force_https)) return [];
      const http = handlers.includes("http");
      const tls = handlers.includes("tls");
      const url = !http
        ? undefined
        : tls
          ? flycast
            ? undefined
            : withPort(`https://${host}`, entry.port, 443)
          : withPort(`http://${host}`, entry.port, 80);
      return [
        {
          host,
          port: entry.port,
          internalPort: service.internal_port,
          protocol: service.protocol ?? "tcp",
          handlers,
          url,
        },
      ];
    }),
  );
};

/** HTTPS on the first TLS port, else HTTP on the first plain HTTP port. */
const mainUrlOf = (endpoints: ServiceEndpoint[]) =>
  endpoints.find((endpoint) => endpoint.url?.startsWith("https://"))?.url ??
  endpoints.find((endpoint) => endpoint.url !== undefined)?.url;

/** `public` and `network` configure the Service's own App. */
const validateOwnership = (props: Partial<Pick<ServiceProps, "app" | "public" | "network">>) => {
  if (props.app === undefined) return Effect.void;
  const conflicting = (["public", "network"] as const).filter((key) => props[key] !== undefined);
  return conflicting.length === 0
    ? Effect.void
    : Effect.fail(
        new InvalidServiceProps({
          message: `Fly.Service ${conflicting.map((key) => `\`${key}\``).join(" and ")} only apply when the Service owns its App; remove \`app\` or ${conflicting.map((key) => `\`${key}\``).join(" and ")}.`,
        }),
      );
};

/**
 * A private network name unique to the current stack and stage, for the
 * Service `network` prop. Services in one stage reach each other; other
 * stages and every other App in the organization cannot.
 */
export const stackNetwork = Effect.gen(function* () {
  const stack = yield* Stack;
  const name = `${stack.name}-${stack.stage}`
    .toLowerCase()
    .replace(/[^a-z0-9-]+/g, "-")
    .replace(/-+/g, "-")
    .replace(/^-|-$/g, "")
    .slice(0, 63)
    .replace(/-$/, "");
  return /^[a-z]/.test(name) ? name : `n-${name}`.slice(0, 63);
});

interface Access {
  ownsApp: boolean;
  isPublic: boolean;
  network: string | undefined;
  bindingPort: number;
  rpcToken: Redacted.Redacted<string> | undefined;
}

/** Drop the port Alchemy added for bindings from a services list. */
const withoutBindingPort = (services: FlyMachineService[] | undefined, bindingPort: number) =>
  (services ?? []).flatMap((service) => {
    const ports = (service.ports ?? []).filter(
      (entry) =>
        !(
          entry.port === bindingPort &&
          (entry.handlers ?? []).includes("http") &&
          !(entry.handlers ?? []).includes("tls")
        ),
    );
    return ports.length === 0 ? [] : [{ ...service, ports }];
  });

const endpointsOf = (set: ReplicaSet, access: Access) => {
  if (!hasPublishedService(set.services))
    return { url: undefined, privateUrl: undefined, endpoints: [] };
  const isPublic = !access.ownsApp || access.isPublic;
  const binding = bindingPortOf(portsOfFly(set.services), access.bindingPort);
  const visible = binding?.added ? withoutBindingPort(set.services, binding.port) : set.services;
  const endpoints = endpointListOf(`${set.appName}.${isPublic ? "fly.dev" : "flycast"}`, visible);
  return {
    url: isPublic ? mainUrlOf(endpoints) : undefined,
    privateUrl:
      binding === undefined
        ? undefined
        : withPort(`http://${set.appName}.flycast`, binding.port, 80),
    endpoints,
  };
};

/**
 * The Service's Fly services plus the plain-HTTP port for bound callers,
 * when none of its published ports serves plain HTTP.
 */
const withBindingService = (
  services: FlyMachineService[],
  internalPort: number,
  bindingPort: number,
): { services: FlyMachineService[]; added: boolean } => {
  const binding = bindingPortOf(portsOfFly(services), bindingPort);
  if (binding?.added !== true) return { services, added: false };
  if (portsOfFly(services).some((entry) => entry.start === bindingPort))
    return { services, added: true };
  // Add the port to the first TCP service so it shares that service's
  // internal port and health checks (blue/green requires checks on every
  // published service).
  const index = services.findIndex((service) => (service.protocol ?? "tcp") === "tcp");
  if (index === -1) {
    return {
      added: true,
      services: [
        ...services,
        {
          protocol: "tcp",
          internal_port: internalPort,
          ports: [{ port: bindingPort, handlers: ["http"] }],
        },
      ],
    };
  }
  return {
    added: true,
    services: services.map((service, i) =>
      i === index
        ? {
            ...service,
            ports: [...(service.ports ?? []), { port: bindingPort, handlers: ["http"] }],
          }
        : service,
    ),
  };
};

/** Fly reports the organization's default network as `default`. */
const normalizeNetwork = (network: string | undefined | null) =>
  network === undefined || network === null || network === "" || network === "default"
    ? undefined
    : network;

export class ServiceUnreachable extends Data.TaggedError("Fly.ServiceUnreachable")<{
  service: string;
  target: string;
  network: string | undefined;
  targetNetwork: string | undefined;
}> {
  get message() {
    return `Fly Service ${this.service} binds ${this.target}, but ${this.service} is on the ${this.network ?? "default"} network and ${this.target} is on the ${this.targetNetwork ?? "default"} network. Put both on the same \`network\`.`;
  }
}

export class ServiceNotBindable extends Data.TaggedError("Fly.ServiceNotBindable")<{
  service: string;
  target: string;
}> {
  get message() {
    return `Fly Service ${this.service} binds ${this.target}, which publishes no ports (\`services: []\`), so it has no private address.`;
  }
}

export class EndpointNotPublished extends Data.TaggedError("Fly.EndpointNotPublished")<{
  service: string;
  target: string;
  port: number;
}> {
  get message() {
    return `Fly Service ${this.service} binds port ${this.port} of ${this.target}, which does not publish it.`;
  }
}

/** Check every Service this one binds is reachable from its network. */
const validateTargets = (
  service: string,
  network: string | undefined,
  targets: readonly BoundTarget[],
) =>
  Effect.gen(function* () {
    for (const target of targets) {
      const targetNetwork = normalizeNetwork(target.network);
      if (targetNetwork !== normalizeNetwork(network)) {
        return yield* new ServiceUnreachable({
          service,
          target: target.service,
          network: normalizeNetwork(network),
          targetNetwork,
        });
      }
      if (target.privateUrl === undefined) {
        return yield* new ServiceNotBindable({ service, target: target.service });
      }
      if (
        target.port !== undefined &&
        !(target.endpoints ?? []).some((entry) => entry.port === target.port)
      ) {
        return yield* new EndpointNotPublished({
          service,
          target: target.service,
          port: target.port,
        });
      }
    }
  });

/**
 * Fail when a Machine outside this Service already publishes one of its
 * ports in a shared App. Catches Machines the App's bindings do not list:
 * other stacks, the `fly` CLI, or plain `Fly.Machine`s.
 */
const validateObservedPorts = (
  appName: string,
  fqn: string,
  id: string,
  services: FlyMachineService[],
) =>
  Effect.gen(function* () {
    const listed = yield* machines
      .listMachines({ app_name: appName })
      .pipe(Effect.catchTag(["NotFound"], () => Effect.succeed([])));
    const others = new Map<string, FlyMachineService[] | undefined>();
    for (const machine of listed) {
      if (machine.state === "destroyed") continue;
      const owner = machine.config?.metadata?.[alchemyMetadataKeys.fqn] ?? machine.id ?? "";
      if (owner === fqn || others.has(owner)) continue;
      others.set(owner, machine.config?.services);
    }
    const mine = portsOfFly(services);
    for (const [owner, theirs] of others) {
      const conflict = findPortConflict(appName, [
        { id, ports: mine },
        { id: owner, ports: portsOfFly(theirs) },
      ]);
      if (conflict !== undefined && conflict.publishers[0] !== conflict.publishers[1])
        return yield* conflict;
    }
  });

const toAttrs = (set: ReplicaSet, codeHash: string, access: Access): Service["Attributes"] => ({
  appName: set.appName,
  ownsApp: access.ownsApp,
  network: normalizeNetwork(access.network),
  rpcToken: access.rpcToken,
  ...endpointsOf(set, access),
  rolloutPending: set.rolloutPending,
  machineId: set.machineId,
  machineIds: set.machineIds,
  name: set.name,
  baseName: set.baseName,
  region: set.region,
  regions: set.regions,
  state: set.state,
  imageRef: set.imageRef,
  count: Math.round(set.count / Math.max(1, set.regions.length)),
  mounts: set.mounts,
  replicas: set.replicas,
  code: { hash: codeHash },
});

/** The replica set of a Service whose App exists but runs no Machines yet. */
const emptyReplicaSet = (appName: string, name: string): ReplicaSet => ({
  appName,
  machineId: "",
  machineIds: [],
  name,
  baseName: name,
  region: "",
  regions: [],
  state: "created",
  instanceId: undefined,
  privateIp: undefined,
  imageRef: undefined,
  guest: undefined,
  services: undefined,
  count: 0,
  mounts: [],
  replicas: [],
});

const machineIdsOf = (output: Service["Attributes"] | undefined) =>
  output?.machineIds ??
  (output?.machineId !== undefined && output.machineId.length > 0 ? [output.machineId] : []);

/** The private network the Service's Machines join. */
const networkOf = (props: ServiceProps) =>
  normalizeNetwork(
    props.app === undefined ? props.network : (props.app as { network?: string }).network,
  );

/**
 * Resolve the App the Service runs in. A Service that owns its App creates
 * it with its addresses; one placed in an App gets a Flycast address on it
 * so bound callers can reach it.
 */
const ensureServiceApp = Effect.fn(function* (
  id: string,
  props: ServiceProps,
  output: Service["Attributes"] | undefined,
) {
  yield* validateOwnership(props);
  const ownsApp = props.app === undefined;
  const isPublic = !ownsApp || props.public !== false;
  if (ownsApp) {
    const desired =
      props.name !== undefined
        ? sanitizeFlyAppName(props.name)
        : output?.ownsApp === true
          ? output.appName
          : yield* createFlyAppName(id);
    const app = yield* ensureApp({
      name: desired,
      network: props.network,
      previousName: output?.ownsApp === true ? output.appName : undefined,
    });
    const appName = app.name ?? desired;
    yield* syncOwnedAppAddresses(appName, isPublic, props.network);
    return { appName, ownsApp, isPublic, network: props.network };
  }
  const appName = appNameOf(props.app) ?? output?.appName;
  if (appName === undefined) {
    return yield* new ServiceAppNotResolved({
      message: "Fly.Service requires a resolved App with appName.",
    });
  }
  const network = networkOf(props);
  yield* ensureFlycastAddress(appName, network);
  return { appName, ownsApp, isPublic, network };
});

export const ServiceProvider = () =>
  Provider.effect(
    Service,
    Effect.gen(function* () {
      const stack = yield* Stack;
      const docker = yield* Docker;
      const { dotAlchemy } = yield* AlchemyContext;
      const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
      const hosted = createFlyHostedSupport({
        stackName: stack.name,
        stage: stack.stage,
        virtualEntryPlugin,
        docker,
        dotAlchemy,
      });

      return Service.Provider.of({
        stables: ["appName"],
        nuke: { dependsOn: ["Fly.App"] },

        diff: Effect.fn(function* ({ news, output }) {
          if (news === undefined) return;
          const shape = news as Partial<Pick<ServiceProps, "app" | "public" | "network">>;
          const ownsApp = shape.app === undefined;
          yield* validateOwnership(shape);
          if ("main" in news) {
            const settings: Input<
              Pick<
                ServiceProps,
                "deploy" | "shutdown" | "checks" | "services" | "port" | "isExternal" | "public"
              >
            > = {
              deploy: news.deploy,
              shutdown: news.shutdown,
              services: news.services,
              checks: news.checks,
              port: news.port,
              isExternal: news.isExternal,
              public: news.public,
            };
            if (
              isResolved<
                Pick<
                  ServiceProps,
                  "deploy" | "shutdown" | "checks" | "services" | "port" | "isExternal" | "public"
                >
              >(settings)
            ) {
              yield* validateDeployment(
                yield* deploymentPolicy(settings.deploy, settings.shutdown, !settings.isExternal),
                {
                  services:
                    settings.services?.map(toFlyService) ??
                    defaultHttpServices(
                      settings.port ?? DEFAULT_PORT,
                      1,
                      !ownsApp || settings.public !== false,
                    ),
                  checks: settings.checks,
                },
                false,
              );
            }
          }
          if (output === undefined) return;
          // Moving into or out of a shared App changes the hostname.
          if (ownsApp !== (output.ownsApp === true)) {
            return { action: "replace" as const, deleteFirst: false };
          }
          if (ownsApp && isResolved(news)) {
            const desiredAppName =
              news.name !== undefined ? sanitizeFlyAppName(news.name) : output.appName;
            const nameChanged = desiredAppName !== output.appName;
            // Fly cannot move an App to another network.
            const networkChanged =
              normalizeNetwork(news.network) !== normalizeNetwork(output.network);
            if (nameChanged || networkChanged) {
              return {
                action: "replace" as const,
                // A pinned App name cannot exist twice.
                deleteFirst: !nameChanged && news.name !== undefined,
              };
            }
          }
          if (!ownsApp && isResolved(news)) {
            const desiredAppName = appNameOf(news.app);
            const appChanged = desiredAppName !== undefined && desiredAppName !== output.appName;
            const desiredName =
              news.name !== undefined
                ? sanitizeFlyAppName(news.name)
                : (output.baseName ?? output.name);
            const nameChanged = desiredName !== (output.baseName ?? output.name);
            if (appChanged || nameChanged) {
              return {
                action: "replace" as const,
                deleteFirst: nameChanged === false && appChanged === false,
              };
            }
          }
          // The code hash depends only on statically-known props (`main`,
          // `build`, `image`, `port`, `extraFiles`, `isExternal`). Never
          // gate it on the WHOLE props being resolved: `app` is a resource
          // reference that stays unresolved at diff time, so a whole-props
          // guard makes code-only changes silently noop. By diff time the
          // effect-config form has been evaluated, so the object view is
          // safe to read.
          const statics = news as Partial<
            Pick<ServiceProps, "main" | "build" | "image" | "port" | "extraFiles" | "isExternal">
          >;
          if (
            isResolved({
              main: statics.main,
              build: statics.build,
              image: statics.image,
              port: statics.port,
              extraFiles: statics.extraFiles,
              isExternal: statics.isExternal,
            }) &&
            statics.main !== undefined
          ) {
            const hash = yield* hosted.hash(statics as HostedProgramProps);
            if (hash !== output.code.hash) {
              return { action: "update" as const };
            }
          }
          return output.rolloutPending ? { action: "update" as const } : undefined;
        }),

        read: Effect.fn(function* ({ id, fqn, instanceId, olds, output }) {
          const ownsApp = output?.ownsApp ?? (olds !== undefined && olds.app === undefined);
          const appName = ownsApp
            ? (output?.appName ??
              (olds?.name !== undefined
                ? sanitizeFlyAppName(olds.name)
                : yield* createFlyAppName(id)))
            : (appNameOf(olds?.app) ?? output?.appName);
          const name = yield* resolveMachineName(
            id,
            ownsApp ? undefined : olds?.name,
            output?.baseName ?? output?.name,
          );
          const found = yield* observeReplicaSet({
            appName,
            id,
            type: "Fly.Service",
            fqn,
            resourceInstanceId: instanceId,
            machineIds: machineIdsOf(output),
            baseName: name,
          });
          if (found === undefined) {
            // A create interrupted between creating the Service's own App and
            // starting its Machines (an image build in between can take
            // minutes) leaves the App with nothing in it. Report it, so the
            // engine's recovery of the interrupted create deletes it instead
            // of leaking it. The App's name is derived from this resource's
            // instance, so an App with that name is this resource's.
            if (!ownsApp || appName === undefined) return undefined;
            const app = yield* machines
              .getApp({ app_name: appName })
              .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
            if (app === undefined || !matchesAlchemyPhysicalName(app.name)) return undefined;
            return toAttrs(emptyReplicaSet(appName, name), output?.code.hash ?? "", {
              ownsApp,
              isPublic: false,
              network: output?.network ?? olds?.network,
              bindingPort: olds?.bindingPort ?? DEFAULT_BINDING_PORT,
              rpcToken: output?.rpcToken,
            });
          }
          return toAttrs(found, output?.code.hash ?? "", {
            ownsApp,
            isPublic: ownsApp && (yield* hasPublicAddress(found.appName)),
            network: output?.network ?? (ownsApp ? olds?.network : undefined),
            bindingPort: olds?.bindingPort ?? DEFAULT_BINDING_PORT,
            rpcToken: output?.rpcToken,
          });
        }),

        list: Effect.fn(function* () {
          const sets = yield* listReplicaSets("Fly.Service");
          // Owned Apps are also listed (and nuked) as Fly.App rows.
          return sets.map((set) =>
            toAttrs(set, "", {
              ownsApp: false,
              isPublic: true,
              network: undefined,
              bindingPort: DEFAULT_BINDING_PORT,
              rpcToken: undefined,
            }),
          );
        }),

        reconcile: Effect.fn(function* ({ id, fqn, instanceId, news, output, bindings, session }) {
          const props = news;
          const policy = yield* deploymentPolicy(props.deploy, props.shutdown, !props.isExternal);
          yield* validateOwnership(props);
          const bound = collectBindingState(bindings ?? []);
          // Before creating anything: every bound Service must be reachable.
          yield* validateTargets(id, networkOf(props), bound.targets);
          const { appName, ownsApp, isPublic, network } = yield* ensureServiceApp(
            id,
            props,
            output,
          );
          const name = yield* resolveMachineName(
            id,
            ownsApp ? undefined : props.name,
            output?.baseName ?? output?.name,
          );
          const regions = regionList(props.region, DEFAULT_REGION);
          const count = resolveCount(props.count);
          const port = props.port ?? DEFAULT_PORT;
          const bindingPort = props.bindingPort ?? DEFAULT_BINDING_PORT;
          const secretVersions: number[] = [];
          const redisVersion = yield* attachRedisSecrets(appName, bound.redis);
          if (redisVersion !== undefined) secretVersions.push(redisVersion);
          const bucketVersion = yield* attachBucketSecrets(appName, bound.buckets, {
            ...bound.env,
            ...toEnv(props.env),
          });
          if (bucketVersion !== undefined) secretVersions.push(bucketVersion);
          for (const pg of bound.postgres) {
            const version = yield* attachPostgresSecrets(appName, pg.clusterId, pg.variableName);
            if (version !== undefined) secretVersions.push(version);
          }
          const minSecretsVersion =
            secretVersions.length > 0 ? Math.max(...secretVersions) : undefined;
          const env = desiredEnv(props, bound.env, hosted.alchemyEnv, port);
          if (policy.shutdown && !props.isExternal) {
            env.ALCHEMY_FLY_SHUTDOWN_TIMEOUT_MS = String(policy.shutdown.timeoutMs);
          }
          const guest = toFlyGuest(props.guest);
          const published = withBindingService(
            props.services !== undefined
              ? props.services.map(toFlyService)
              : defaultHttpServices(port, count, isPublic),
            port,
            bindingPort,
          );
          const services = published.services;
          if (!ownsApp) yield* validateObservedPorts(appName, fqn, id, services);
          if (props.rpcToken !== undefined) env[RPC_TOKEN_ENV] = Redacted.value(props.rpcToken);
          for (const target of bound.targets) {
            const keys = boundTargetEnvKeys(target.service);
            env[keys.appName] = packEnvValue(target.appName);