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

import { createHash } from "node:crypto";
import { Query } from "@distilled.cloud/core/query";
import { Railway, type VariableUpsertInput } 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 Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import { waitUntilDeleted } from "./GraphQL.ts";
import { createRailwayName, matchesAlchemyPhysicalName } from "./Metadata.ts";
import { ownedProjects, projectEnvironmentIds, type Project } from "./Project.ts";
import type { Providers } from "./Providers.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>;

/**
 * Environment identity a Variable is stored in. Accepts a
 * `Railway.Project` (its primary environment), a `Railway.Environment`,
 * or an `{ environmentId }` stub.
 */
export type VariableEnvironment = { readonly environmentId: string };

/**
 * Service identity a Variable can be scoped to. Accepts a
 * `Railway.Service` or a `{ serviceId }` stub.
 */
export type VariableService = { readonly serviceId: string };

export interface VariableProps {
  /**
   * Parent Railway Project. Changing it replaces the variable.
   */
  project: Ref<Project>;
  /**
   * Environment to store the variable in. Accepts a `Railway.Project`
   * (primary environment), a `Railway.Environment`, or `{ environmentId }`.
   * Defaults to the project's primary environment. Changing it replaces
   * the variable.
   */
  environment?: Ref<VariableEnvironment>;
  /**
   * Service to scope the variable to. Omit for a shared (project-level)
   * variable. Accepts a `Railway.Service` or `{ serviceId }`. Changing it
   * replaces the variable.
   */
  service?: Ref<VariableService>;
  /**
   * Variable name (the env-var name services see). Stored as-is when set
   * by the user (case-sensitive). If omitted, a unique name is generated
   * from the stack, stage and logical ID. Changing it replaces the
   * variable.
   */
  name?: string;
  /**
   * Variable value. Wrap secrets with `Redacted.make(...)` so they are
   * never logged. May also be a `Railway.ref(...)` template
   * (`${{Db.DATABASE_URL}}`, `${{shared.NAME}}`); Railway stores the
   * template and interpolates it at build/runtime. Updated in place via
   * `variableUpsert`. Never persisted in attributes.
   */
  value: Redacted.Redacted<string> | string;
}

export type Variable = Resource<
  "Railway.Variable",
  VariableProps,
  {
    /** Parent Railway project id. */
    projectId: string;
    /** Environment the variable lives in. */
    environmentId: string;
    /** Service the variable is scoped to, if any. */
    serviceId: string | undefined;
    /** Variable name (unique per project + environment + service). */
    name: string;
    /** sha256 of the current value. Not the plaintext. */
    digest: string;
  },
  never,
  Providers
>;

const resolveVariableProps = (
  props: VariableProps | Effect.Effect<VariableProps, never, Providers>,
): Effect.Effect<VariableProps, never, Providers> =>
  Effect.gen(function* () {
    const resolved = Effect.isEffect(props) ? yield* props : props;
    if (globalThis.__ALCHEMY_RUNTIME__) return resolved;
    const project = Effect.isEffect(resolved.project)
      ? yield* resolved.project as Effect.Effect<Project, never, Providers>
      : resolved.project;
    const environment =
      resolved.environment === undefined
        ? undefined
        : Effect.isEffect(resolved.environment)
          ? yield* resolved.environment as Effect.Effect<VariableEnvironment, never, Providers>
          : resolved.environment;
    const service =
      resolved.service === undefined
        ? undefined
        : Effect.isEffect(resolved.service)
          ? yield* resolved.service as Effect.Effect<VariableService, never, Providers>
          : resolved.service;
    return { ...resolved, project, environment, service };
  });

const VariableResource = Resource<Variable>("Railway.Variable");

/**
 * A Railway.Variable is a project- or service-scoped env var. Railway
 * injects it into services in that environment. The plaintext is never
 * stored in attributes.
 *
 * @see https://docs.railway.com/guides/variables
 *
 * ### Create a Variable
 * Wrap the value with `Redacted.make` so it is never logged. Omit `name`
 * and Alchemy generates an ownership-stamped name. Shared (no `service`)
 * variables apply to every service in the environment.
 *
 * **Example:** Generated name
 * ```typescript
 * const site = yield* Railway.Project("Site");
 * const dbUrl = yield* Railway.Variable("DatabaseUrl", {
 *   project: site,
 *   value: Redacted.make("postgres://…"),
 * });
 * ```
 *
 * :::caution[Changing `project` replaces the Variable]
 * The value is created on the new Project. The old name is deleted.
 * :::
 *
 * ### Env-var name
 * `name` is the env-var services see. It is stored as-is
 * (case-sensitive).
 *
 * **Example:** Explicit name
 * ```typescript
 * export const ApiToken = Railway.Variable("ApiToken", {
 *   project: Site,
 *   name: "API_TOKEN",
 *   value: Redacted.make("sk_live_…"),
 * });
 * ```
 *
 * :::caution[Changing `name` replaces the Variable]
 * Railway cannot rename a variable. Alchemy creates the new name, then
 * deletes the old one.
 * :::
 *
 * ### Environment
 * Defaults to the Project's primary environment. Pass a
 * `Railway.Environment` (or `{ environmentId }`) to target another one.
 *
 * **Example:** Extra environment
 * ```typescript
 * const staging = yield* Railway.Environment("Staging", { project: site });
 * const token = yield* Railway.Variable("StagingToken", {
 *   project: site,
 *   environment: staging,
 *   value: Redacted.make("sk_staging_…"),
 * });
 * ```
 *
 * :::caution[Changing `environment` replaces the Variable]
 * The value is created in the new environment. The old name is deleted.
 * :::
 *
 * ### Service-scoped
 * Pass `service` to attach the variable to one service instead of the
 * shared project set.
 *
 * **Example:** Service variable
 * ```typescript
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 * });
 * const token = yield* Railway.Variable("ApiToken", {
 *   project: site,
 *   service: api,
 *   name: "API_TOKEN",
 *   value: Redacted.make("sk_live_…"),
 * });
 * ```
 *
 * ### Variable references
 * `value` may be a `Railway.ref(resource, key)` template instead of a
 * plaintext secret. Upsert stores `${{LogicalName.KEY}}` (or
 * `${{shared.NAME}}`) — not a resolved URI. Railway interpolates it.
 * Next to {@link ConnectPostgres}: use `ConnectPostgres` for a typed
 * client inside an Effect-native Service; use `Railway.ref` when you
 * want Railway's own `${{Db.DATABASE_URL}}` interpolation (IaC
 * `db.env.DATABASE_URL`).
 *
 * **Example:** Reference Postgres DATABASE_URL
 * ```typescript
 * const db = yield* Railway.Postgres("Db", { project: site });
 * const api = yield* Railway.Service("Api", {
 *   project: site,
 *   image: "hashicorp/http-echo",
 * });
 * const databaseUrl = yield* Railway.Variable("DatabaseUrl", {
 *   project: site,
 *   service: api,
 *   name: "DATABASE_URL",
 *   value: Railway.ref(db, "DATABASE_URL"),
 * });
 * ```
 *
 * **Example:** Shared variable
 * ```typescript
 * yield* Railway.Variable("SentryDsn", {
 *   project: site,
 *   name: "SENTRY_DSN",
 *   value: Redacted.make("https://…"),
 * });
 * yield* Railway.Variable("ApiSentry", {
 *   project: site,
 *   service: api,
 *   name: "SENTRY_DSN",
 *   value: Railway.ref("shared", "SENTRY_DSN"),
 * });
 * ```
 *
 * ### Rotate the value
 * Updating `value` is in place via `variableUpsert`. Deploys are skipped
 * (`skipDeploys: true`); the Service resource owns deploys.
 *
 * **Example:** New value
 * ```typescript
 * export const ApiToken = Railway.Variable("ApiToken", {
 *   project: Site,
 *   name: "API_TOKEN",
 *   value: Redacted.make("sk_live_rotated"),
 * });
 * ```
 *
 * ### 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 Variable
 * ```typescript
 * // src/secrets.ts
 * import * as Railway from "@alchemy.run/railway";
 * import * as Redacted from "effect/Redacted";
 *
 * export const Site = Railway.Project("Site");
 * export const ApiToken = Railway.Variable("ApiToken", {
 *   project: Site,
 *   name: "API_TOKEN",
 *   value: Redacted.make("sk_live_…"),
 * });
 * ```
 *
 * @resource
 * @product Service
 */
export const Variable: typeof VariableResource = Object.assign(
  (id: string, props: VariableProps | Effect.Effect<VariableProps, never, Providers>) =>
    VariableResource(id, resolveVariableProps(props)),
  VariableResource,
);

export class VariableNotCreated extends Data.TaggedError("Railway.VariableNotCreated")<{
  projectId: string;
  environmentId: string;
  variableName: string;
}> {}

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

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

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 serviceIdOf = (value: unknown): string | undefined => {
  if (value === null || typeof value !== "object") return undefined;
  const rec = value as { serviceId?: unknown };
  return typeof rec.serviceId === "string" && rec.serviceId.length > 0 ? rec.serviceId : undefined;
};

const unwrapSecret = (value: Redacted.Redacted<string> | string): string =>
  Redacted.isRedacted(value) ? Redacted.value(value) : value;

const digestOf = (plain: string) =>
  Effect.sync(() => createHash("sha256").update(Buffer.from(plain, "utf8")).digest("hex"));

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

const toAttrs = (input: {
  projectId: string;
  environmentId: string;
  serviceId: string | undefined;
  name: string;
  digest: string;
}): Variable["Attributes"] => input;

const asVariableMap = (value: unknown): Record<string, string> => {
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
    return {};
  }
  const out: Record<string, string> = {};
  for (const [key, item] of Object.entries(value)) {
    if (typeof item === "string") {
      out[key] = item;
    }
  }
  return out;
};

const readVariables = Query.fn((projectId: string, environmentId: string, serviceId?: string) =>
  Railway.variables({
    projectId,
    environmentId,
    ...(serviceId !== undefined ? { serviceId } : {}),
    unrendered: true,
  }),
);

const variableUpsert = Query.fn((input: VariableUpsertInput) => Railway.variableUpsert({ input }));

const variableDelete = Query.fn(
  (input: { projectId: string; environmentId: string; name: string; serviceId?: string }) =>
    Railway.variableDelete({ input }),
);

const listVariableMap = (projectId: string, environmentId: string, serviceId?: string) =>
  readVariables(projectId, environmentId, serviceId).pipe(
    Effect.map(asVariableMap),
    Effect.catchTag("RailwayNotFound", () => Effect.succeed({} as Record<string, string>)),
  );

const getValue = (projectId: string, environmentId: string, name: string, serviceId?: string) =>
  listVariableMap(projectId, environmentId, serviceId).pipe(Effect.map((vars) => vars[name]));

const upsertVariable = (input: {
  projectId: string;
  environmentId: string;
  name: string;
  value: string;
  serviceId?: string;
}) =>
  variableUpsert({
    projectId: input.projectId,
    environmentId: input.environmentId,
    name: input.name,
    value: input.value,
    skipDeploys: true,
    ...(input.serviceId !== undefined ? { serviceId: input.serviceId } : {}),
  });

const _listEnvironmentIds = (project: { projectId: string; environmentId: string }) =>
  Query.items(
    Railway.environments({ projectId: project.projectId, first: 50 }).pipe(
      Query.map((env) => ({ id: env.id, deletedAt: env.deletedAt })),
    ),
  ).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] : []),
    ),
  );

export const VariableProvider = () =>
  Provider.succeed(Variable, {
    stables: ["projectId", "environmentId", "serviceId", "name"],
    nuke: { dependsOn: ["Railway.Project"] },

    diff: Effect.fn(function* ({ news, output }) {
      if (news === undefined || !isResolved(news)) return undefined;
      if (output === undefined) return undefined;
      const desiredName = news.name !== undefined ? news.name : output.name;
      const nameChanged = desiredName !== output.name;
      const nextProject = projectIdOf(news.project);
      const projectChanged = nextProject !== undefined && nextProject !== output.projectId;
      const nextEnv = environmentIdOf(news.environment);
      const environmentChanged = nextEnv !== undefined && nextEnv !== output.environmentId;
      const nextService = serviceIdOf(news.service);
      const serviceChanged = news.service !== undefined && nextService !== output.serviceId;
      if (nameChanged || projectChanged || environmentChanged || serviceChanged) {
        return {
          action: "replace" as const,
          deleteFirst: nameChanged && !projectChanged && !environmentChanged && !serviceChanged,
        };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const projectId =
        output?.projectId ?? (olds !== undefined ? projectIdOf(olds.project) : undefined);
      const environmentId =
        output?.environmentId ??
        (olds !== undefined
          ? (environmentIdOf(olds.environment) ?? environmentIdOf(olds.project))
          : undefined);
      if (projectId === undefined || environmentId === undefined) {
        return undefined;
      }
      const name = yield* resolveName(id, olds?.name, output?.name);
      const serviceId =
        output?.serviceId ?? (olds !== undefined ? serviceIdOf(olds.service) : undefined);
      const value = yield* getValue(projectId, environmentId, name, serviceId);
      if (value === undefined) return undefined;
      const digest = yield* digestOf(value);
      const attrs = toAttrs({ projectId, environmentId, serviceId, name, digest });
      if (output !== undefined) return attrs;
      return matchesAlchemyPhysicalName(name) ? attrs : Unowned(attrs);
    }),

    list: Effect.fn(function* () {
      const projects = yield* ownedProjects();
      const rows = yield* Effect.forEach(projects, (project) =>
        Effect.gen(function* () {
          const envIds = yield* projectEnvironmentIds(project);
          const nested = yield* Effect.forEach(envIds, (environmentId) =>
            listVariableMap(project.projectId, environmentId).pipe(
              Effect.flatMap((vars) =>
                Effect.forEach(
                  Object.keys(vars).filter((name) => matchesAlchemyPhysicalName(name)),
                  (name) =>
                    digestOf(vars[name]!).pipe(
                      Effect.map((digest) =>
                        toAttrs({
                          projectId: project.projectId,
                          environmentId,
                          serviceId: undefined,
                          name,
                          digest,
                        }),
                      ),
                    ),
                ),
              ),
            ),
          );
          return nested.flat();
        }),
      );
      return rows.flat();
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const props = news ?? ({} as VariableProps);
      const projectId = projectIdOf(props.project) ?? output?.projectId;
      if (projectId === undefined) {
        return yield* new VariableProjectRequired({
          message: "Variable requires a resolved Railway.Project",
        });
      }
      const environmentId =
        environmentIdOf(props.environment) ??
        environmentIdOf(props.project) ??
        output?.environmentId;
      if (environmentId === undefined) {
        return yield* new VariableEnvironmentRequired({
          message:
            "Variable requires a Railway environment (pass environment or a Project with environmentId)",
        });
      }
      const serviceId =
        props.service !== undefined ? serviceIdOf(props.service) : output?.serviceId;
      const name = yield* resolveName(id, props.name, output?.name);
      const desiredPlain = unwrapSecret(props.value);

      let current =
        output !== undefined
          ? yield* getValue(output.projectId, output.environmentId, output.name, output.serviceId)
          : undefined;
      if (
        current === undefined &&
        (output === undefined ||
          output.projectId !== projectId ||
          output.environmentId !== environmentId ||
          output.name !== name ||
          output.serviceId !== serviceId)
      ) {
        current = yield* getValue(projectId, environmentId, name, serviceId);
      }

      let createdThisRun = false;
      if (current === undefined) {
        yield* upsertVariable({ projectId, environmentId, name, value: desiredPlain, serviceId });
        current = yield* getValue(projectId, environmentId, name, serviceId);
        createdThisRun = true;
      }

      if (current === undefined) {
        return yield* new VariableNotCreated({ projectId, environmentId, variableName: name });
      }

      if (!createdThisRun && current !== desiredPlain) {
        yield* upsertVariable({ projectId, environmentId, name, value: desiredPlain, serviceId });
        current = (yield* getValue(projectId, environmentId, name, serviceId)) ?? desiredPlain;
      }

      const digest = yield* digestOf(current);
      return toAttrs({ projectId, environmentId, serviceId, name, digest });
    }),

    delete: Effect.fn(function* ({ output }) {
      if (
        output.projectId.length === 0 ||
        output.environmentId.length === 0 ||
        output.name.length === 0
      ) {
        return;
      }
      yield* variableDelete({
        projectId: output.projectId,
        environmentId: output.environmentId,
        name: output.name,
        ...(output.serviceId !== undefined ? { serviceId: output.serviceId } : {}),
      }).pipe(Effect.catchTag("RailwayNotFound", () => Effect.void));
      yield* waitUntilDeleted(
        "Variable",
        `${output.environmentId}/${output.serviceId ?? "shared"}/${output.name}`,
        getValue(output.projectId, output.environmentId, output.name, output.serviceId).pipe(
          Effect.map((value) => value === undefined),
        ),
      );
    }),
  });