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

import * as Binding from "alchemy/Binding";
import type { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import type { Volume } from "./Volume.ts";

export interface MountVolumeOptions {
  /**
   * Absolute path inside the container the Volume is mounted at
   * (e.g. `/data`).
   */
  path: string;
}

/**
 * Runtime view of a Volume mounted into a {@link Service} or
 * `Railway.Function`: the path inside the container.
 */
export interface MountedVolume {
  /** Mount path inside the container (same value as {@link MountVolumeOptions.path}). */
  path: string;
}

/**
 * A volume mount injected onto a {@link Service} via {@link MountVolume}.
 * Service reconcile attaches it with `volumeInstanceUpdate`.
 */
export interface MountSpec {
  /** Railway volume id (not the instance id). */
  volumeId: string;
  /** Absolute path inside the container. */
  path: string;
}

// Pass `volume.volumeId` through as-is. At bind time it is an Output,
// never a materialized string — `typeof === "string"` would store `""`
// and every downstream guard would skip the mount. `Input<Binding>`
// resolves the Output before reconcile.
const volumeIdOf = (volume: Volume) => volume.volumeId ?? "";

const RAILWAY_BIND_HOST_TYPES = new Set(["Railway.Service", "Railway.Function"]);

/**
 * True for a Railway compute host that accepts {@link ServiceBinding}
 * (`Railway.Service` or {@link Function}).
 */
export const isRailwayHost = (
  value: unknown,
): value is Resource<string, any, any, ServiceBinding> =>
  typeof value === "object" &&
  value !== null &&
  RAILWAY_BIND_HOST_TYPES.has((value as { Type?: string }).Type ?? "");

/**
 * Binding contract accepted by {@link Service} and
 * `Railway.Function` for mounted volumes and injected env.
 */
export interface ServiceBinding {
  env?: Record<string, any>;
  mounts?: MountSpec[];
}

/**
 * Railway allows one volume per service. Two `MountVolume`s, or a
 * second {@link Volume} attached via `service`, is this error.
 */
export class MultipleVolumes extends Data.TaggedError("Railway.MultipleVolumes")<{
  resourceName: string;
  paths: readonly string[];
  volumeIds: readonly string[];
}> {}

const distinctMounts = (mounts: readonly MountSpec[]): MountSpec[] => {
  const seen = new Set<string>();
  const out: MountSpec[] = [];
  for (const mount of mounts) {
    if (mount.volumeId.length === 0) continue;
    const key = `${mount.volumeId}:${mount.path}`;
    if (seen.has(key)) continue;
    seen.add(key);
    out.push(mount);
  }
  return out;
};

/** At most one volume on a host. */
export const assertHostDisk = (input: {
  name: string;
  mounts: readonly MountSpec[];
}): Effect.Effect<void, MultipleVolumes> => {
  const mounts = distinctMounts(input.mounts);
  if (mounts.length <= 1) return Effect.void;
  return new MultipleVolumes({
    resourceName: input.name,
    paths: mounts.map((mount) => mount.path),
    volumeIds: mounts.map((mount) => mount.volumeId),
  });
};

/**
 * Mount a Railway.Volume into a {@link Service} or `Railway.Function`.
 *
 * `yield* Railway.MountVolume(volume, { path: "/data" })` inside a
 * Service/Function impl registers `{ mounts: [{ volumeId, path }] }` on
 * the host. Reconcile attaches the volume via `volumeInstanceUpdate`.
 *
 * Railway allows **one volume per service**. A second mount is
 * `Railway.MultipleVolumes`. Railway does not give each replica its
 * own disk.
 *
 *
 * ### Mount into a Service
 * Yield `MountVolume` inside init. Provide {@link MountVolumeLive}.
 * At runtime you get `disk.path`.
 *
 * **Example:** Bind a path
 * ```typescript
 * export default class Api extends Railway.Service<Api>()(
 *   "Api",
 *   { project: Site, main: import.meta.url },
 *   Effect.gen(function* () {
 *     const disk = yield* Railway.MountVolume(Data, { path: "/data" });
 *     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(Railway.MountVolumeLive)),
 * ) {}
 * ```
 *
 * :::caution[One volume per service]
 * Railway does not attach a disk per replica. Two {@link MountVolume}s
 * on one host fail with {@link MultipleVolumes}.
 * :::
 *
 * @binding
 * @product Volume
 */
export interface MountVolume extends Binding.Service<
  MountVolume,
  "Railway.MountVolume",
  (volume: Volume, options: MountVolumeOptions) => Effect.Effect<MountedVolume>
> {}

export const MountVolume = Binding.Service<MountVolume>("Railway.MountVolume");

export const MountVolumeLive = Layer.effect(
  MountVolume,
  Effect.succeed(
    Effect.fn(function* (volume: Volume, options: MountVolumeOptions) {
      if (!globalThis.__ALCHEMY_RUNTIME__) {
        const host = yield* Binding.Host;
        if (isRailwayHost(host)) {
          yield* host.bind`Railway.MountVolume(${options.path})`({
            mounts: [{ volumeId: volumeIdOf(volume), path: options.path }],
          });
        }
      }
      return { path: options.path };
    }),
  ),
);