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

import type { Builder, RestartPolicyType } from "@distilled.cloud/railway";
import type { HttpEffect } from "alchemy/Http";
import { Platform, type Main, type MainRpc, type PlatformProps } from "alchemy/Platform";
import type { Resource } from "alchemy/Resource";
import type { ServerHost } from "alchemy/Runtime/Process";
import * as Effect from "effect/Effect";
import type * as Redacted from "effect/Redacted";
import {
  createRailwayHostRuntimeContext,
  type ExtraFile,
  type RailwayBuildOptions,
  type RailwayHostRuntimeContext,
} from "./hosted.ts";
import type { ServiceBinding } from "./MountVolume.ts";
import type { Project } from "./Project.ts";
import type { Providers } from "./Providers.ts";
import { serveRailwayRpc } from "./rpc-server.ts";
import { mintRpcToken } from "./rpc-token.ts";

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

export type { ExtraFile, RailwayBuildOptions };

/**
 * Environment identity a Service is deployed into. Accepts a
 * `Railway.Project` (its primary environment), a `Railway.Environment`,
 * or an `{ environmentId }` stub.
 */
export type ServiceEnvironment = {
  readonly environmentId: string;
};

export interface ServiceProps extends PlatformProps {
  /**
   * Parent Railway Project. Accepts a `Railway.Project` or an Effect
   * that produces one. Changing the Project replaces the Service.
   */
  project: Ref<Project>;
  /**
   * Environment to deploy the service instance into. Accepts a
   * `Railway.Project` (primary environment), a `Railway.Environment`, or
   * `{ environmentId }`. Defaults to the project's primary environment.
   * Changing it replaces the Service.
   */
  environment?: Ref<ServiceEnvironment>;
  /**
   * Module entrypoint bundled with rolldown and packed into a generated
   * Dockerfile. Railway builds that Dockerfile (`railway up`). Typically
   * `import.meta.url`. Mutually exclusive with the public-image path
   * (`image` without `main`). A content-hash change updates in place.
   */
  main?: string;
  /**
   * Local Docker context uploaded with Railway `up`. Paths are relative to the
   * initial working directory. Limited to a 32 MiB archive, 10,000 entries,
   * ASCII paths, and no symlinks; Docker ignore files apply.
   */
  context?: string;
  /**
   * Docker image Railway should run.
   *
   * When `main` is omitted this is `source.image` (e.g.
   * `hashicorp/http-echo`). When `main` is set this is the generated
   * Dockerfile's `FROM` (default `node:26-slim`).
   */
  image?: string;
  /**
   * Region the service runs in (`us-west2`, `europe-west4-drams3a`, …).
   * Railway places replicas with `deploy.multiRegionConfig`. Omit this
   * and the current placement is left alone (the workspace default on
   * first create). Updating it moves the replicas in place and keeps
   * the current replica count.
   */
  region?: string;
  /**
   * Port the process listens on. Written to `PORT` and used as the
   * generated `*.up.railway.app` `targetPort`. Default is `3000` for
   * Effect-native (`main`) Services. Pass `5678` for
   * `hashicorp/http-echo`.
   */
  port?: number;
  /**
   * Whether to create and manage a generated `*.up.railway.app` domain.
   * Existing unowned generated or custom domains are not removed.
   * @default true
   */
  publicDomain?: boolean;
  /**
   * Additional environment variables. Merged after binding-injected
   * `env`. Upserted as service-scoped Railway variables with
   * `skipDeploys: true`; this Service owns the subsequent deploy.
   */
  env?: Record<string, any>;
  /**
   * Private-mesh RPC token. Minted by a child `Alchemy.Random`
   * (`{logicalId}RpcToken`) and persisted in state. Set automatically.
   */
  rpcToken?: Redacted.Redacted<string>;
  /**
   * Bundler configuration for `main`: rolldown `input`/`output`
   * overrides, plus `install` for packages that must ship as real
   * `node_modules` (see {@link RailwayBuildOptions}).
   */
  build?: RailwayBuildOptions;
  /**
   * Extra files/directories copied into `/app` in the generated
   * Dockerfile (`COPY dest /app/dest`). Website composites use this to
   * bake the framework `clientDirectory` (or Next.js `.next`) so asset
   * changes rebuild on Railway.
   */
  extraFiles?: ReadonlyArray<ExtraFile>;
  /**
   * Named export to load from `main`.
   *
   * @default "default"
   */
  handler?: string;
  /**
   * Service name. Unique per Project. If omitted, a unique name is
   * generated from the stack, stage and logical ID. Changing it updates
   * in place via `serviceUpdate`.
   */
  name?: string;
  /**
   * GitHub repository (`owner/repo`). Creates/syncs
   * `serviceCreate.source.repo` / `serviceInstanceUpdate.source.repo`.
   * Mutually exclusive with the public-image and `main` paths. Requires a
   * GitHub connection on the Railway account.
   */
  repo?: string;
  /**
   * GitHub branch for {@link repo}. Passed as `serviceCreate.branch` and
   * synced onto the deployment trigger.
   */
  branch?: string;
  /**
   * Monorepo subdirectory Railway builds from (`rootDirectory`).
   */
  rootDirectory?: string;
  /**
   * Build command (`pnpm build`). Distinct from hosted
   * {@link RailwayBuildOptions} (`build.install`).
   */
  buildCommand?: string;
  /**
   * Pre-deploy step Railway runs after the image build and before
   * start (migrations, seed). Omit to leave the current Railway setting
   * unchanged. Pass `{ command: null }` to clear it.
   *
   * @see https://docs.railway.com/deployments/pre-deploy-command
   */
  preDeploy?: {
    /**
     * Shell command Railway executes in a separate container after
     * build and before start. Must exit 0 or the deployment fails.
     * Pass `null` to clear it.
     */
    command: string | null;
  };
  /**
   * Start command (`pnpm start`).
   */
  startCommand?: string;
  /**
   * HTTP healthcheck path (`/health`). Synced via
   * `serviceInstanceUpdate.healthcheckPath`. Alias of {@link healthcheck}
   * (Railway IaC `healthcheck: "/health"`).
   */
  healthcheckPath?: string;
  /**
   * HTTP healthcheck path. Same as {@link healthcheckPath}; matches
   * Railway IaC `healthcheck`.
   */
  healthcheck?: string;
  /**
   * Healthcheck timeout in seconds.
   */
  healthcheckTimeout?: number;
  /**
   * Cron expression (`cronSchedule`). Observed as `cronSchedule` /
   * `nextCronRunAt`.
   */
  cronSchedule?: string;
  /**
   * Restart policy (`ALWAYS`, `NEVER`, `ON_FAILURE`).
   */
  restartPolicyType?: RestartPolicyType;
  /**
   * Max retries when {@link restartPolicyType} is `ON_FAILURE`.
   */
  restartPolicyMaxRetries?: number;
  /**
   * Drain window in seconds before a replica is stopped.
   */
  drainingSeconds?: number;
  /**
   * Overlap window in seconds while a new replica starts.
   */
  overlapSeconds?: number;
  /**
   * Sleep the application when idle.
   */
  sleepApplication?: boolean;
  /**
   * Auto-deploy on new commits / image tags
   * (`serviceInstanceAutoDeployUpdate`).
   */
  autoUpdates?: boolean;
  /**
   * Dockerfile path relative to {@link rootDirectory}, or to {@link context}
   * for a local context.
   * @default "Dockerfile"
   */
  dockerfilePath?: string;
  /**
   * Builder (`RAILPACK`, `NIXPACKS`, `HEROKU`, `PAKETO`).
   */
  builder?: Builder;
  /**
   * Git watch patterns that trigger a rebuild.
   */
  watchPatterns?: string[];
}

export type Service = Resource<
  "Railway.Service",
  ServiceProps,
  {
    /** Railway service id. */
    serviceId: string;
    /** Physical service name (unique per project). */
    name: string;
    /** Parent Railway project id. */
    projectId: string;
    /** Environment the instance is deployed in. */
    environmentId: string;
    /** Observed `source.image`, if set. */
    image: string | undefined;
    /** Observed `source.repo` (`owner/repo`), if set. */
    repo: string | undefined;
    /** Observed healthcheck path. */
    healthcheckPath: string | undefined;
    /** Observed healthcheck timeout in seconds. */
    healthcheckTimeout: number | undefined;
    /**
     * Observed replica count. Alchemy does not set this — Railway
     * load-balances whatever is running (default 1).
     */
    replicas: number | undefined;
    /** Observed build command. */
    buildCommand: string | undefined;
    /** Observed start command. */
    startCommand: string | undefined;
    /** Observed cron schedule. */
    cronSchedule: string | undefined;
    /** Observed root directory. */
    rootDirectory: string | undefined;
    /**
     * Region the service is placed in. Set when
     * `deploy.multiRegionConfig` has replicas in exactly one region.
     */
    region: string | undefined;
    /** Port published on the generated service domain. */
    port: number | undefined;
    /** Public `https://{domain}` URL (`*.up.railway.app`). */
    url: string | undefined;
    /** Generated Railway service domain hostname. */
    domain: string | undefined;
    /**
     * Internal DNS name on the default private mesh
     * (`{name}.railway.internal`). Derived from the service name — no
     * extra API call.
     */
    dnsName: string;
    /**
     * Shared token for private schemaless RPC. Value of the child
     * `Alchemy.Random` resource. Packed onto callers by `bindService` /
     * `bindFunction`; never send this to the public internet.
     */
    rpcToken: string;
    /** Railway service domain id. */
    domainId: string | undefined;
    /** Latest deployment id, if one exists. */
    deploymentId: string | undefined;
    /** Latest deployment status (`SUCCESS`, `DEPLOYING`, …). */
    deploymentStatus: string | undefined;
    /** Content hash of the bundled program (empty for public images). */
    code: {
      hash: string;
    };
  },
  ServiceBinding,
  Providers
>;

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

export type ServiceServices = ServerHost;

export type ServiceShape = Main<ServiceServices> & MainRpc<ServiceServices>;

export type ServiceRuntimeContext = RailwayHostRuntimeContext;

const createServiceRuntimeContext = (id: string): ServiceRuntimeContext => {
  const base = createRailwayHostRuntimeContext("Railway.Service")(id);
  const inner = base.serve;
  return Object.assign(base, {
    serve: ((handler, options) =>
      inner(
        (options?.shape === undefined
          ? handler
          : // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- the RPC server provides the request service at call time
            serveRailwayRpc(options.shape, handler as HttpEffect)) as typeof handler,
        options,
      )) as ServiceRuntimeContext["serve"],
  });
};

/**
 * A Railway.Service is a container in a Project. Point it at a public
 * image (`hashicorp/http-echo`) or an Effect program (`main`). Alchemy
 * stamps the name, creates a `*.up.railway.app` domain via
 * `serviceDomainCreate`, and deploys.
 *
 * @see https://docs.railway.com/guides/services
 *
 * ### Image service
 * Pass `image` without `main`. Railway pulls the image and runs it.
 * `url` is the generated `*.up.railway.app` hostname.
 *
 * **Example:** Public image
 * ```typescript
 * const site = yield* Railway.Project("Site");
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 *   port: 5678,
 * });
 * ```
 *
 * :::caution[Changing `project` replaces the Service]
 * The Service is created in the new Project. The old Service is deleted.
 * :::
 *
 * ### Effect-native Service
 * A Service is a class. `main: import.meta.url` is the bundle
 * entrypoint. Alchemy bundles this file with Rolldown, generates a
 * Dockerfile (`FROM node:26-slim`), and uploads the context. Railway
 * builds the image. `build.install: ["pg"]` ships `pg` unbundled.
 *
 * **Example:** Class + Project + main
 * ```typescript
 * export default class Api extends Railway.Service<Api>()(
 *   "Api",
 *   {
 *     project: Site,
 *     main: import.meta.url,
 *     build: { install: ["pg"] },
 *   },
 *   Effect.gen(function* () {
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("hello")),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Local Docker context
 * `context` is a directory Railway builds with `up`. Mutually exclusive
 * with `image` (without `main`) and `repo`. Docker ignore files apply.
 *
 * **Example:** Upload a local Dockerfile
 * ```typescript
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   context: "./api",
 *   port: 80,
 * });
 * ```
 *
 * ### The public URL
 * Yield the Service in the Stack. `api.url` is
 * `https://{name}.up.railway.app`.
 *
 * **Example:** Stack output
 * ```typescript
 * export default Alchemy.Stack(
 *   "MyApp",
 *   { providers: Railway.providers(), state: Alchemy.localState() },
 *   Effect.gen(function* () {
 *     const api = yield* Api;
 *     return { url: api.url };
 *   }),
 * );
 * ```
 *
 * ### Private service
 * `publicDomain: false` skips the generated `*.up.railway.app` hostname.
 * `url` / `domain` stay unset. Reach it on the private mesh at
 * `{name}.railway.internal`. Unowned generated or custom domains are
 * left alone.
 *
 * **Example:** Private-only service
 * ```typescript
 * const worker = yield* Railway.Service("Worker", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 *   port: 5678,
 *   publicDomain: false,
 * });
 * ```
 *
 * ### Pin a region
 * Omit `region` to leave placement alone. On first create that is the
 * workspace default. Updating `region` moves the replicas in place.
 *
 * **Example:** Region
 * ```typescript
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 *   port: 5678,
 *   region: "us-west2",
 * });
 * ```
 *
 * ### Healthcheck
 * `healthcheckPath` (or `healthcheck`, matching Railway IaC) is the
 * HTTP path Railway probes. Railway load-balances public traffic
 * across whatever replicas are running. Alchemy does not pin a count.
 *
 * **Example:** Healthcheck
 * ```typescript
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 *   port: 5678,
 *   healthcheck: "/health",
 * });
 * ```
 *
 * :::caution[One volume per service]
 * Railway does not give each replica its own disk. A second volume
 * on one Service fails with `Railway.MultipleVolumes`.
 * :::
 *
 * ### GitHub source
 * `repo` + `branch` is the third source, next to `image` and `main`.
 * Railway must have GitHub connected to the account.
 *
 * **Example:** GitHub repo
 * ```typescript
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   repo: "acme/web",
 *   branch: "main",
 *   rootDirectory: "apps/api",
 *   buildCommand: "pnpm build",
 *   startCommand: "pnpm start",
 * });
 * ```
 *
 * ### Pre-deploy
 * Railway runs `preDeploy.command` after the image build and before
 * start — the same setting as the dashboard Pre-deploy Command.
 *
 * **Example:** Run migrations before traffic
 * ```typescript
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 *   preDeploy: { command: "bun --cwd apps/api migrate" },
 * });
 * ```
 *
 * ### Cron
 * `cronSchedule` runs the service on a cron expression.
 *
 * **Example:** Cron schedule
 * ```typescript
 * const worker = yield* Railway.Service("Worker", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 *   cronSchedule: "0 * * * *",
 * });
 * ```
 *
 * ### Mount a disk
 * Bind {@link MountVolume} inside init. Provide {@link MountVolumeLive}.
 *
 * **Example:** Volume
 * ```typescript
 * export default class Api extends Railway.Service<Api>()(
 *   "Api",
 *   { project: Site, image: "hashicorp/http-echo", port: 5678 },
 *   Effect.gen(function* () {
 *     const disk = yield* Railway.MountVolume(Data, { path: "/data" });
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text(disk.path)),
 *     };
 *   }).pipe(Effect.provide(Railway.MountVolumeLive)),
 * ) {}
 * ```
 *
 * ### Schemaless RPC
 * Return methods next to `fetch`. Another Service or Function binds
 * this class and calls them over `{name}.railway.internal` with a
 * shared token. Public `*.up.railway.app` requests to `/__rpc__/*`
 * get 401.
 *
 * **Example:** Bind a Service
 * ```typescript
 * export default class Query extends Railway.Service<Query>()(
 *   "Query",
 *   { project: Site, main: import.meta.url },
 *   Effect.gen(function* () {
 *     return {
 *       greet: (name: string) => Effect.succeed(`hello ${name}`),
 *     };
 *   }),
 * ) {}
 *
 * export default class Api extends Railway.Function<Api>()(
 *   "Api",
 *   { project: Site, main: import.meta.url },
 *   Effect.gen(function* () {
 *     const query = yield* Railway.bindService(Query);
 *     return {
 *       fetch: query
 *         .greet("sam")
 *         .pipe(Effect.map((greeting) => HttpServerResponse.text(greeting))),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Module-scope declarations
 * Declare the Project once. Pass it into every child. Resource-valued
 * props accept the resource or an Effect producing it.
 *
 * **Example:** Module-scope Service
 * ```typescript
 * // src/api.ts
 * import * as Railway from "@alchemy.run/railway";
 *
 * export const Site = Railway.Project("Site");
 * export const Api = Railway.Service("Api", {
 *   project: Site,
 *   image: "hashicorp/http-echo",
 *   port: 5678,
 * });
 * ```
 *
 * @resource
 * @product Service
 */
export const Service: Platform<Service, ServiceServices, ServiceShape, ServiceRuntimeContext> =
  Platform("Railway.Service", {
    createRuntimeContext: createServiceRuntimeContext,
    transformProps: (id, props) =>
      Effect.gen(function* () {
        if (globalThis.__ALCHEMY_RUNTIME__) return props;
        const project = Effect.isEffect(props.project)
          ? yield* props.project as Effect.Effect<Project, never, Providers>
          : props.project;
        const environment =
          props.environment === undefined
            ? undefined
            : Effect.isEffect(props.environment)
              ? yield* props.environment as Effect.Effect<ServiceEnvironment, never, Providers>
              : props.environment;
        const rpcToken = yield* mintRpcToken(id);
        return { ...props, project, environment, rpcToken };
      }),
  });