@alchemy.run/fly 0.0.0 → 2.0.0-beta.84

package/lib/Service.d.ts

@@ -0,0 +1,1022 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+import { AlchemyContext } from "alchemy/AlchemyContext";
+import { Platform, type Main, type MainRpc, type PlatformProps } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import type { Resource } from "alchemy/Resource";
+import type { ServerHost } from "alchemy/Runtime/Process";
+import { Stack } from "alchemy/Stack";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { App } from "./App.ts";
+import { type MachineDeploy, type MachineShutdown, type MachineCheck } from "./Deployment.ts";
+import { type FlyBuildOptions, type FlyHostRuntimeContext } from "./hosted.ts";
+import type { MachineGuest, MachineImageRef, MachineService } from "./Machine.ts";
+import type { MountedDisk, ServiceBinding } from "./MountVolume.ts";
+import type { Providers } from "./Providers.ts";
+import { type Region } from "./Region.ts";
+import { type Replica } from "./replicas.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>;
+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 declare const isService: (value: unknown) => value is 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 `pg` unbundled
+ * `pg` is CommonJS. Rolldown's interop turns `Client` into a namespace.
+ * Install it into the image so `@effect/sql-pg` / `Drizzle.Postgres` load
+ * it with Node's CJS semantics — same `build.install` as Lambda.
+ * ```typescript
+ * export default class Api extends Fly.Service<Api>()(
+ *   "Api",
+ *   {
+ *     main: import.meta.url,
+ *     port: 3000,
+ *     build: { install: ["pg"] },
+ *   },
+ *   Effect.gen(function* () {
+ *     const conn = yield* Fly.ConnectPostgres(Db);
+ *     const db = yield* Drizzle.Postgres(conn.connectionString);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const rows = yield* db.execute("select 1 as ok");
+ *         return HttpServerResponse.json({ rows });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Fly.ConnectPostgresHttp)),
+ * ) {}
+ * ```
+ *
+ * ### 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 declare const Service: Platform<Service, ServiceServices, ServiceShape, ServiceRuntimeContext>;
+declare const ServiceNotCreated_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.ServiceNotCreated";
+} & Readonly<A>;
+export declare class ServiceNotCreated extends ServiceNotCreated_base<{
+    name: string;
+    appName: string;
+}> {
+}
+declare const InvalidServiceProps_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.InvalidServiceProps";
+} & Readonly<A>;
+export declare class InvalidServiceProps extends InvalidServiceProps_base<{
+    message: string;
+}> {
+}
+declare const ServiceAppNotResolved_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.ServiceAppNotResolved";
+} & Readonly<A>;
+export declare class ServiceAppNotResolved extends ServiceAppNotResolved_base<{
+    message: string;
+}> {
+}
+/**
+ * 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 declare const stackNetwork: Effect.Effect<string, never, Stack>;
+declare const ServiceUnreachable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.ServiceUnreachable";
+} & Readonly<A>;
+export declare class ServiceUnreachable extends ServiceUnreachable_base<{
+    service: string;
+    target: string;
+    network: string | undefined;
+    targetNetwork: string | undefined;
+}> {
+    get message(): string;
+}
+declare const ServiceNotBindable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.ServiceNotBindable";
+} & Readonly<A>;
+export declare class ServiceNotBindable extends ServiceNotBindable_base<{
+    service: string;
+    target: string;
+}> {
+    get message(): string;
+}
+declare const EndpointNotPublished_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Fly.EndpointNotPublished";
+} & Readonly<A>;
+export declare class EndpointNotPublished extends EndpointNotPublished_base<{
+    service: string;
+    target: string;
+    port: number;
+}> {
+    get message(): string;
+}
+export declare const ServiceProvider: () => Layer.Layer<Provider.Provider<Service>, never, AlchemyContext | import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("effect/Path").Path | Stack | import("alchemy/Stage").Stage | machines.FlyIoOpContext>;
+export {};
+//# sourceMappingURL=Service.d.ts.map