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

import { Query, type UnwrapPlan } from "@distilled.cloud/core/query";
import {
  Railway,
  type VolumeInstance,
  type VolumeInstanceBackup,
  type VolumeInstanceBackupScheduleKind,
  type VolumeState,
  type WorkflowId,
} from "@distilled.cloud/railway";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { waitUntilDeleted, environmentVolumes } from "./GraphQL.ts";
import { createRailwayName, matchesAlchemyPhysicalName } from "./Metadata.ts";
import { ownedProjects } from "./Project.ts";
import type { Providers } from "./Providers.ts";

const backupFields = <E>(backup: Query<VolumeInstanceBackup, E>) => ({
  id: backup.id,
  name: backup.name,
  createdAt: backup.createdAt,
  expiresAt: backup.expiresAt,
  usedMB: backup.usedMB,
  referencedMB: backup.referencedMB,
  volumeInstanceSizeMB: backup.volumeInstanceSizeMB,
  scheduleId: backup.scheduleId,
});
const volumeFields = <E>(instance: Query<VolumeInstance, E>) => ({
  id: instance.id,
  volumeId: instance.volumeId,
  environmentId: instance.environmentId,
  serviceId: instance.serviceId,
  deletedAt: instance.deletedAt,
  isPendingDeletion: instance.isPendingDeletion,
  state: instance.state,
  mountPath: instance.mountPath,
  volume: {
    id: instance.volume.id,
    name: instance.volume.name,
    projectId: instance.volume.projectId,
  },
});

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

/**
 * Volume identity a backup snapshots. Accepts a `Railway.Volume` or a
 * `{ volumeInstanceId }` stub.
 */
export type VolumeBackupVolume = {
  readonly volumeInstanceId: string;
  readonly volumeId?: string;
  readonly projectId?: string;
  readonly environmentId?: string;
};

/**
 * Environment identity used to pick a volume instance when the Volume
 * spans more than one. Accepts a `Railway.Project` (primary
 * environment), a `Railway.Environment`, or `{ environmentId }`.
 */
export type VolumeBackupEnvironment = { readonly environmentId: string };

export type VolumeBackupScheduleKind = VolumeInstanceBackupScheduleKind;

export interface VolumeBackupProps {
  /**
   * Volume to snapshot. Accepts a `Railway.Volume` or a
   * `{ volumeInstanceId }` stub. Changing it replaces the backup.
   */
  volume: Ref<VolumeBackupVolume>;
  /**
   * Environment whose volume instance to snapshot. Defaults to the
   * Volume's environment. Changing it replaces the backup.
   */
  environment?: Ref<VolumeBackupEnvironment>;
  /**
   * Backup name. If omitted, a unique name is generated from the stack,
   * stage and logical ID. Changing it replaces the backup.
   */
  name?: string;
  /**
   * Lock the backup so it does not expire. One-way — Railway has no
   * unlock. Updates in place via `volumeInstanceBackupLock`.
   *
   * @default false
   */
  lock?: boolean;
  /**
   * Backup schedules on the volume instance (`DAILY`, `WEEKLY`,
   * `MONTHLY`). Omit to leave schedules untouched. An empty array
   * clears them. Updates in place via
   * `volumeInstanceBackupScheduleUpdate`.
   */
  schedules?: readonly VolumeBackupScheduleKind[];
}

export type VolumeBackup = Resource<
  "Railway.VolumeBackup",
  VolumeBackupProps,
  {
    /** Railway volume-instance backup id. */
    volumeInstanceBackupId: string;
    /** Volume instance the backup belongs to. */
    volumeInstanceId: string;
    /** Parent volume id, if known. */
    volumeId: string | undefined;
    /** Parent Railway project id, if known. */
    projectId: string | undefined;
    /** Environment the volume instance is in, if known. */
    environmentId: string | undefined;
    /** Backup name (defaults to `'Manual'` on the API). */
    name: string;
    /** RFC3339 creation timestamp. */
    createdAt: string;
    /** RFC3339 expiration, or `undefined` when locked / never expires. */
    expiresAt: string | undefined;
    /** Unique bytes referenced by this backup, in MB. */
    usedMB: number | undefined;
    /** Logical size referenced, in MB. */
    referencedMB: number | undefined;
    /** Size of the volume instance when the backup was taken, in MB. */
    volumeInstanceSizeMB: number | undefined;
    /** Schedule that produced this backup, if it was not manual. */
    scheduleId: string | undefined;
    /** Whether expiration has been removed (`volumeInstanceBackupLock`). */
    locked: boolean;
    /** Observed schedule kinds on the volume instance. */
    schedules: VolumeBackupScheduleKind[];
  },
  never,
  Providers
>;

const resolveVolumeBackupProps = (
  props: VolumeBackupProps | Effect.Effect<VolumeBackupProps, never, Providers>,
): Effect.Effect<VolumeBackupProps, never, Providers> =>
  Effect.gen(function* () {
    const resolved = Effect.isEffect(props) ? yield* props : props;
    if (globalThis.__ALCHEMY_RUNTIME__) return resolved;
    const volume = Effect.isEffect(resolved.volume)
      ? yield* resolved.volume as Effect.Effect<VolumeBackupVolume, never, Providers>
      : resolved.volume;
    const environment =
      resolved.environment === undefined
        ? undefined
        : Effect.isEffect(resolved.environment)
          ? yield* resolved.environment as Effect.Effect<VolumeBackupEnvironment, never, Providers>
          : resolved.environment;
    return { ...resolved, volume, environment };
  });

const VolumeBackupResource = Resource<VolumeBackup>("Railway.VolumeBackup");

/**
 * A Railway.VolumeBackup is a snapshot of a volume instance. Create it
 * next to a `Railway.Volume`. Railway backups run as workflows —
 * Alchemy waits for `workflowStatus` then reads the backup list.
 *
 * Restore is destructive to the volume instance; use
 * {@link restoreVolumeBackup}. Point-in-time restore forks a new
 * Postgres service via {@link restoreVolumePITR}.
 *
 * @see https://docs.railway.com/volumes/backups
 * @see https://docs.railway.com/integrations/api/manage-volumes
 *
 * ### Create a backup
 * Pass the Volume. Alchemy generates a unique name. The volume should
 * be attached to a Service — Railway only backups mounted volumes.
 *
 * **Example:** Manual snapshot
 * ```typescript
 * const site = yield* Railway.Project("Site");
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 * });
 * const data = yield* Railway.Volume("Data", {
 *   project: site,
 *   mountPath: "/data",
 *   service: api,
 * });
 * const snap = yield* Railway.VolumeBackup("Nightly", { volume: data });
 * ```
 *
 * :::caution[Changing `volume` or `environment` replaces the backup]
 * A new snapshot is created on the new instance. The old backup is
 * deleted.
 * :::
 *
 * ### Name
 * Omit `name` for an ownership-stamped name. Pass one to label the
 * snapshot in the dashboard.
 *
 * **Example:** Explicit name
 * ```typescript
 * const snap = yield* Railway.VolumeBackup("Nightly", {
 *   volume: data,
 *   name: "pre-migrate",
 * });
 * ```
 *
 * :::caution[Changing `name` replaces the backup]
 * Railway cannot rename a backup. A new snapshot is created, then the
 * old one is deleted.
 * :::
 *
 * ### Lock
 * Lock to drop the expiration. One-way.
 *
 * **Example:** Lock a backup
 * ```typescript
 * const snap = yield* Railway.VolumeBackup("Nightly", {
 *   volume: data,
 *   lock: true,
 * });
 * ```
 *
 * ### Schedules
 * `schedules` is volume-instance state, not per-snapshot. Set it on
 * one VolumeBackup that owns the instance.
 *
 * **Example:** Daily + weekly
 * ```typescript
 * const snap = yield* Railway.VolumeBackup("Nightly", {
 *   volume: data,
 *   schedules: ["DAILY", "WEEKLY"],
 * });
 * ```
 *
 * ### Restore
 * Restore is not a reconciler step. Call {@link restoreVolumeBackup}
 * (destructive to the instance) or {@link restoreVolumePITR} (forks a
 * new Postgres service).
 *
 * **Example:** Restore a snapshot
 * ```typescript
 * yield* Railway.restoreVolumeBackup({
 *   volumeInstanceId: snap.volumeInstanceId,
 *   volumeInstanceBackupId: snap.volumeInstanceBackupId,
 * });
 * ```
 *
 * ### Module-scope declarations
 * Resource-valued props accept the resource or an Effect producing it.
 *
 * **Example:** Module-scope backup
 * ```typescript
 * // src/data.ts
 * import * as Railway from "@alchemy.run/railway";
 *
 * export const Site = Railway.Project("Site");
 * export const Data = Railway.Volume("Data", {
 *   project: Site,
 *   mountPath: "/data",
 * });
 * export const Nightly = Railway.VolumeBackup("Nightly", {
 *   volume: Data,
 * });
 * ```
 *
 * @resource
 * @product Volume
 */
export const VolumeBackup: typeof VolumeBackupResource = Object.assign(
  (id: string, props: VolumeBackupProps | Effect.Effect<VolumeBackupProps, never, Providers>) =>
    VolumeBackupResource(id, resolveVolumeBackupProps(props)),
  VolumeBackupResource,
);

export class VolumeBackupNotCreated extends Data.TaggedError("Railway.VolumeBackupNotCreated")<{
  resourceName: string;
  volumeInstanceId: string;
}> {}

export class VolumeBackupVolumeRequired extends Data.TaggedError(
  "Railway.VolumeBackupVolumeRequired",
)<{ message: string }> {}

export class VolumeBackupWorkflowFailed extends Data.TaggedError(
  "Railway.VolumeBackupWorkflowFailed",
)<{ workflowId: string; error: string }> {}

class VolumeBackupPending extends Data.TaggedError("Railway.VolumeBackupPending")<{
  volumeInstanceId: string;
  state: string;
}> {}

type CloudBackup = UnwrapPlan<ReturnType<typeof backupFields>>;
type CloudInstance = UnwrapPlan<ReturnType<typeof volumeFields>>;

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

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

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

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

const goneState = (state: VolumeState | null | undefined) =>
  state === "DELETED" || state === "DELETING";

const transientState = (state: VolumeState | null | undefined) =>
  state === "UPDATING" ||
  state === "MIGRATING" ||
  state === "MIGRATION_PENDING" ||
  state === "RESTORING";

const isGoneInstance = (instance: CloudInstance | undefined) =>
  instance === undefined ||
  instance.deletedAt != null ||
  instance.isPendingDeletion ||
  goneState(instance.state);

const uniqueKinds = (kinds: readonly VolumeBackupScheduleKind[]): VolumeBackupScheduleKind[] => {
  const seen = new Set<VolumeBackupScheduleKind>();
  const out: VolumeBackupScheduleKind[] = [];
  for (const kind of kinds) {
    if (seen.has(kind)) continue;
    seen.add(kind);
    out.push(kind);
  }
  return out;
};

const kindsKey = (kinds: readonly VolumeBackupScheduleKind[]) =>
  [...kinds].slice().sort().join(",");

const resolveName = (id: string, existing?: string) =>
  Effect.gen(function* () {
    if (existing !== undefined && existing.length > 0) return existing;
    return yield* createRailwayName(id);
  });

const volumeInstanceBackupList = Query.fn((volumeInstanceId: string) =>
  Railway.volumeInstanceBackupList({ volumeInstanceId }).pipe(Query.map(backupFields)),
);

const volumeInstanceBackupScheduleList = Query.fn((volumeInstanceId: string) =>
  Railway.volumeInstanceBackupScheduleList({ volumeInstanceId }).pipe(
    Query.map((schedule) => schedule.kind),
  ),
);

const listBackups = (volumeInstanceId: string) =>
  volumeInstanceBackupList(volumeInstanceId).pipe(
    Effect.catchTag("RailwayNotFound", () => Effect.succeed([] as CloudBackup[])),
  );

const listSchedules = (volumeInstanceId: string) =>
  volumeInstanceBackupScheduleList(volumeInstanceId).pipe(
    Effect.map((kinds) => uniqueKinds(kinds)),
    Effect.catchTag("RailwayNotFound", () => Effect.succeed([] as VolumeBackupScheduleKind[])),
  );

const toAttrs = (
  backup: CloudBackup,
  context: {
    volumeInstanceId: string;
    volumeId?: string;
    projectId?: string;
    environmentId?: string;
    schedules?: VolumeBackupScheduleKind[];
  },
): VolumeBackup["Attributes"] => ({
  volumeInstanceBackupId: backup.id,
  volumeInstanceId: context.volumeInstanceId,
  volumeId: context.volumeId,
  projectId: context.projectId,
  environmentId: context.environmentId,
  name: backup.name ?? "",
  createdAt: backup.createdAt,
  expiresAt: backup.expiresAt ?? undefined,
  usedMB: backup.usedMB ?? undefined,
  referencedMB: backup.referencedMB ?? undefined,
  volumeInstanceSizeMB: backup.volumeInstanceSizeMB ?? undefined,
  scheduleId: backup.scheduleId ?? undefined,
  locked: backup.expiresAt == null,
  schedules: context.schedules ?? [],
});

const findBackup = (backups: readonly CloudBackup[], match: { id?: string; name?: string }) => {
  if (match.id !== undefined && match.id.length > 0) {
    const byId = backups.find((backup) => backup.id === match.id);
    if (byId !== undefined) return byId;
  }
  if (match.name !== undefined && match.name.length > 0) {
    return backups.find((backup) => backup.name === match.name);
  }
  return undefined;
};

const readVolumeInstance = Query.fn((id: string) => volumeFields(Railway.volumeInstance({ id })));

const getByInstanceId = (volumeInstanceId: string) =>
  readVolumeInstance(volumeInstanceId).pipe(
    Effect.map((instance): CloudInstance | undefined =>
      isGoneInstance(instance) ? undefined : instance,
    ),
    Effect.catchTag("RailwayNotFound", () => Effect.undefined),
  );

const listVolumeInstances = (environmentId: string, projectId: string) =>
  environmentVolumes(environmentId, projectId, volumeFields).pipe(
    Effect.map((rows) => rows.filter((node) => !isGoneInstance(node))),
    Effect.catchTag("RailwayNotFound", () => Effect.succeed([] as CloudInstance[])),
  );

const liveEnvironments = (projectId: string) =>
  Query.items(
    Railway.environments({ projectId, first: 50 }).pipe(
      Query.map((env) => ({ id: env.id, deletedAt: env.deletedAt })),
    ),
  );

const _listEnvironmentIds = (project: { projectId: string; environmentId: string }) =>
  liveEnvironments(project.projectId).pipe(
    Stream.filter((env) => env.deletedAt == null),
    Stream.map((env) => env.id),
    Stream.runCollect,
    Effect.map((ids) => {
      const set = new Set(Array.from(ids));
      if (project.environmentId.length > 0) {
        set.add(project.environmentId);
      }
      return Array.from(set);
    }),
    Effect.catchTag("RailwayNotFound", () =>
      Effect.succeed(project.environmentId.length > 0 ? [project.environmentId] : []),
    ),
  );

const readWorkflowStatus = Query.fn((workflowId: string) => {
  const workflow = Railway.workflowStatus({ workflowId });
  return { status: workflow.status, error: workflow.error };
});

const workflowIdFields = <E>(result: Query<WorkflowId, E>) => ({ workflowId: result.workflowId });

const volumeInstanceBackupRestore = Query.fn(
  (volumeInstanceBackupId: string, volumeInstanceId: string) =>
    workflowIdFields(
      Railway.volumeInstanceBackupRestore({ volumeInstanceBackupId, volumeInstanceId }),
    ),
);

const volumeInstancePITRRestore = Query.fn(
  (args: {
    volumeInstanceId: string;
    targetTimestamp: string;
    newServiceName?: string;
    sourceRepoPath?: string;
  }) => workflowIdFields(Railway.volumeInstancePITRRestore(args)),
);

const volumeInstanceBackupCreate = Query.fn((volumeInstanceId: string, name: string) =>
  workflowIdFields(Railway.volumeInstanceBackupCreate({ volumeInstanceId, name })),
);

const volumeInstanceBackupDelete = Query.fn(
  (volumeInstanceBackupId: string, volumeInstanceId: string) =>
    workflowIdFields(
      Railway.volumeInstanceBackupDelete({ volumeInstanceBackupId, volumeInstanceId }),
    ),
);

const volumeInstanceBackupLock = Query.fn(
  (volumeInstanceBackupId: string, volumeInstanceId: string) =>
    Railway.volumeInstanceBackupLock({ volumeInstanceBackupId, volumeInstanceId }),
);

const volumeInstanceBackupScheduleUpdate = Query.fn(
  (volumeInstanceId: string, kinds: ReadonlyArray<VolumeInstanceBackupScheduleKind>) =>
    Railway.volumeInstanceBackupScheduleUpdate({ volumeInstanceId, kinds }),
);

const waitForWorkflow = (workflowId: string, volumeInstanceId: string, mode: "create" | "delete") =>
  Effect.gen(function* () {
    const result = yield* readWorkflowStatus(workflowId);
    if (result.status === "Complete") return result;
    if (result.status === "Error") {
      return yield* new VolumeBackupWorkflowFailed({
        workflowId,
        error: result.error ?? "backup workflow failed",
      });
    }
    return yield* new VolumeBackupPending({ volumeInstanceId, state: result.status });
  }).pipe(
    Effect.retry({
      while: (e) => e._tag === "Railway.VolumeBackupPending",
      times: 10,
      schedule: Schedule.spaced("2 seconds"),
    }),
    Effect.catchTag("Railway.VolumeBackupPending", () =>
      mode === "delete"
        ? Effect.void
        : Effect.fail(
            new VolumeBackupWorkflowFailed({
              workflowId,
              error: "timed out waiting for backup workflow",
            }),
          ),
    ),
  );

const instanceReady = (instance: CloudInstance | undefined) =>
  instance !== undefined &&
  !isGoneInstance(instance) &&
  !transientState(instance.state) &&
  instance.state !== "ERROR";

const waitUntilReady = (volumeInstanceId: string) =>
  getByInstanceId(volumeInstanceId).pipe(
    Effect.flatMap((instance) => {
      if (!instanceReady(instance)) {
        return Effect.fail(
          new VolumeBackupPending({ volumeInstanceId, state: instance?.state ?? "missing" }),
        );
      }
      return Effect.succeed(instance);
    }),
    Effect.retry({
      while: (e) => e._tag === "Railway.VolumeBackupPending",
      times: 10,
      schedule: Schedule.spaced("2 seconds"),
    }),
    Effect.catchTag("Railway.VolumeBackupPending", () => getByInstanceId(volumeInstanceId)),
  );

const waitForBackup = (input: {
  volumeInstanceId: string;
  name: string;
  id?: string;
  previousIds: ReadonlySet<string>;
}) =>
  listBackups(input.volumeInstanceId).pipe(
    Effect.flatMap((backups) => {
      const found =
        findBackup(backups, { id: input.id, name: input.name }) ??
        backups.find((backup) => !input.previousIds.has(backup.id));
      if (found === undefined) {
        return Effect.fail(
          new VolumeBackupPending({ volumeInstanceId: input.volumeInstanceId, state: "creating" }),
        );
      }
      return Effect.succeed(found);
    }),
    Effect.retry({
      while: (e) => e._tag === "Railway.VolumeBackupPending",
      times: 10,
      schedule: Schedule.spaced("2 seconds"),
    }),
    Effect.catchTag("Railway.VolumeBackupPending", () =>
      listBackups(input.volumeInstanceId).pipe(
        Effect.map(
          (backups) =>
            findBackup(backups, { id: input.id, name: input.name }) ??
            backups.find((backup) => !input.previousIds.has(backup.id)),
        ),
      ),
    ),
  );

const waitUntilGone = (volumeInstanceId: string, volumeInstanceBackupId: string) =>
  waitUntilDeleted(
    "VolumeBackup",
    volumeInstanceBackupId,
    listBackups(volumeInstanceId).pipe(
      Effect.map((backups) => !backups.some((backup) => backup.id === volumeInstanceBackupId)),
    ),
  );

const observeInstance = Effect.fn(function* (input: {
  volumeInstanceId?: string;
  volumeId?: string;
  projectId?: string;
  environmentId?: string;
}) {
  if (input.volumeInstanceId !== undefined && input.volumeInstanceId.length > 0) {
    const byId = yield* getByInstanceId(input.volumeInstanceId);
    if (byId !== undefined) return byId;
  }
  if (
    input.environmentId !== undefined &&
    input.projectId !== undefined &&
    input.volumeId !== undefined
  ) {
    const instances = yield* listVolumeInstances(input.environmentId, input.projectId);
    return instances.find((instance) => instance.volumeId === input.volumeId);
  }
  return undefined;
});

/**
 * Restore a volume instance from a backup. Destructive to the live
 * volume — the instance is overwritten. Waits for the restore workflow.
 */
export const restoreVolumeBackup = Effect.fn(function* (input: {
  volumeInstanceId: string;
  volumeInstanceBackupId: string;
}) {
  const result = yield* volumeInstanceBackupRestore(
    input.volumeInstanceBackupId,
    input.volumeInstanceId,
  );
  if (result.workflowId != null && result.workflowId.length > 0) {
    yield* waitForWorkflow(result.workflowId, input.volumeInstanceId, "create");
  }
  return result;
});

/**
 * Point-in-time restore. Creates a new Postgres service whose volume
 * is populated from the source archive. The source service is left
 * online.
 */
export const restoreVolumePITR = Effect.fn(function* (input: {
  volumeInstanceId: string;
  targetTimestamp: string;
  newServiceName?: string;
  sourceRepoPath?: string;
}) {
  const result = yield* volumeInstancePITRRestore({
    volumeInstanceId: input.volumeInstanceId,
    targetTimestamp: input.targetTimestamp,
    ...(input.newServiceName !== undefined ? { newServiceName: input.newServiceName } : {}),
    ...(input.sourceRepoPath !== undefined ? { sourceRepoPath: input.sourceRepoPath } : {}),
  });
  if (result.workflowId != null && result.workflowId.length > 0) {
    yield* waitForWorkflow(result.workflowId, input.volumeInstanceId, "create");
  }
  return result;
});

export const VolumeBackupProvider = () =>
  Provider.succeed(VolumeBackup, {
    stables: [
      "volumeInstanceBackupId",
      "volumeInstanceId",
      "volumeId",
      "projectId",
      "environmentId",
      "createdAt",
    ],
    nuke: { dependsOn: ["Railway.Volume", "Railway.Project"] },

    diff: Effect.fn(function* ({ news, output }) {
      if (news === undefined || !isResolved(news)) return undefined;
      if (output === undefined) return undefined;
      const nextInstance = volumeInstanceIdOf(news.volume);
      const instanceChanged =
        nextInstance !== undefined && nextInstance !== output.volumeInstanceId;
      const nextEnv = environmentIdOf(news.environment);
      const environmentChanged =
        nextEnv !== undefined &&
        output.environmentId !== undefined &&
        nextEnv !== output.environmentId;
      const nextVolumeId = volumeIdOf(news.volume);
      const volumeChanged =
        nextVolumeId !== undefined &&
        output.volumeId !== undefined &&
        nextVolumeId !== output.volumeId;
      const nameChanged =
        news.name !== undefined && news.name.length > 0 && news.name !== output.name;
      if (instanceChanged || environmentChanged || volumeChanged || nameChanged) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const volumeInstanceId =
        output?.volumeInstanceId ??
        (olds !== undefined ? volumeInstanceIdOf(olds.volume) : undefined);
      const name = yield* resolveName(id, output?.name ?? olds?.name);
      if (volumeInstanceId === undefined) return undefined;
      const backups = yield* listBackups(volumeInstanceId);
      const found = findBackup(backups, { id: output?.volumeInstanceBackupId, name });
      if (found === undefined) return undefined;
      const schedules = yield* listSchedules(volumeInstanceId);
      const attrs = toAttrs(found, {
        volumeInstanceId,
        volumeId: output?.volumeId ?? (olds !== undefined ? volumeIdOf(olds.volume) : undefined),
        projectId: output?.projectId ?? (olds !== undefined ? projectIdOf(olds.volume) : undefined),
        environmentId:
          output?.environmentId ??
          (olds !== undefined
            ? (environmentIdOf(olds.environment) ?? environmentIdOf(olds.volume))
            : undefined),
        schedules,
      });
      if (output !== undefined) return attrs;
      return matchesAlchemyPhysicalName(found.name ?? undefined) ? attrs : Unowned(attrs);
    }),

    list: Effect.fn(function* () {
      const projects = yield* ownedProjects();
      const rows = yield* Effect.forEach(projects, (project) =>
        Effect.gen(function* () {
          const envRows = yield* liveEnvironments(project.projectId).pipe(
            Stream.filter((env) => env.deletedAt == null),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
            Effect.catchTag("RailwayNotFound", () => Effect.succeed([])),
          );
          const instances = (yield* Effect.forEach(envRows, (env) =>
            listVolumeInstances(env.id, project.projectId),
          ))
            .flat()
            .filter((instance) => matchesAlchemyPhysicalName(instance.volume.name));
          const nested = yield* Effect.forEach(instances, (instance) =>
            Effect.gen(function* () {
              const backups = yield* listBackups(instance.id);
              const schedules = yield* listSchedules(instance.id);
              return backups.map((backup) =>
                toAttrs(backup, {
                  volumeInstanceId: instance.id,
                  volumeId: instance.volumeId,
                  projectId: instance.volume.projectId,
                  environmentId: instance.environmentId,
                  schedules,
                }),
              );
            }),
          );
          return nested.flat();
        }),
      );
      const seen = new Set<string>();
      const unique: VolumeBackup["Attributes"][] = [];
      for (const row of rows.flat()) {
        if (seen.has(row.volumeInstanceBackupId)) continue;
        seen.add(row.volumeInstanceBackupId);
        unique.push(row);
      }
      return unique;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const props = news ?? ({} as VolumeBackupProps);
      const environmentId =
        environmentIdOf(props.environment) ??
        environmentIdOf(props.volume) ??
        output?.environmentId;
      const projectId = projectIdOf(props.volume) ?? output?.projectId;
      const volumeId = volumeIdOf(props.volume) ?? output?.volumeId;
      let volumeInstanceId = volumeInstanceIdOf(props.volume) ?? output?.volumeInstanceId;

      const instance = yield* observeInstance({
        volumeInstanceId,
        volumeId,
        projectId,
        environmentId,
      });
      if (instance !== undefined) {
        volumeInstanceId = instance.id;
      }
      if (volumeInstanceId === undefined || volumeInstanceId.length === 0) {
        return yield* new VolumeBackupVolumeRequired({
          message: "VolumeBackup requires a resolved Railway.Volume (volumeInstanceId)",
        });
      }

      const name = yield* resolveName(id, props.name ?? output?.name);
      const resolvedVolumeId = instance?.volumeId ?? volumeId;
      const resolvedProjectId = instance?.volume.projectId ?? projectId;
      const resolvedEnvironmentId = instance?.environmentId ?? environmentId;

      let current: CloudBackup | undefined;
      const existing = yield* listBackups(volumeInstanceId);
      current = findBackup(existing, { id: output?.volumeInstanceBackupId, name });

      if (current === undefined) {
        const ready = yield* waitUntilReady(volumeInstanceId);
        if (ready === undefined || isGoneInstance(ready)) {
          return yield* new VolumeBackupNotCreated({ resourceName: name, volumeInstanceId });
        }
        const previousIds = new Set(existing.map((backup) => backup.id));
        const created = yield* volumeInstanceBackupCreate(volumeInstanceId, name);
        if (created.workflowId != null && created.workflowId.length > 0) {
          yield* waitForWorkflow(created.workflowId, volumeInstanceId, "create");
        }
        current = yield* waitForBackup({ volumeInstanceId, name, previousIds });
      }

      if (current === undefined) {
        return yield* new VolumeBackupNotCreated({ resourceName: name, volumeInstanceId });
      }

      if (props.lock === true && current.expiresAt != null) {
        yield* volumeInstanceBackupLock(current.id, volumeInstanceId);
        const locked = yield* listBackups(volumeInstanceId).pipe(
          Effect.map((backups) => findBackup(backups, { id: current!.id, name })),
        );
        if (locked !== undefined) current = locked;
      }

      let schedules = yield* listSchedules(volumeInstanceId);
      if (props.schedules !== undefined) {
        const desired = uniqueKinds(props.schedules);
        if (kindsKey(desired) !== kindsKey(schedules)) {
          yield* volumeInstanceBackupScheduleUpdate(volumeInstanceId, desired);
          schedules = yield* listSchedules(volumeInstanceId);
        }
      }

      return toAttrs(current, {
        volumeInstanceId,
        volumeId: resolvedVolumeId,
        projectId: resolvedProjectId,
        environmentId: resolvedEnvironmentId,
        schedules,
      });
    }),

    delete: Effect.fn(function* ({ output }) {
      const volumeInstanceBackupId = output.volumeInstanceBackupId;
      const volumeInstanceId = output.volumeInstanceId;
      if (volumeInstanceBackupId.length === 0 || volumeInstanceId.length === 0) {
        return;
      }
      const deleted = yield* volumeInstanceBackupDelete(
        volumeInstanceBackupId,
        volumeInstanceId,
      ).pipe(
        Effect.catchTag("RailwayNotFound", () =>
          Effect.succeed({ workflowId: null as string | null }),
        ),
      );
      if (deleted.workflowId != null && deleted.workflowId.length > 0) {
        yield* waitForWorkflow(deleted.workflowId, volumeInstanceId, "delete");
      }
      yield* waitUntilGone(volumeInstanceId, volumeInstanceBackupId);
    }),
  });