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

import { Query, type UnwrapPlan } from "@distilled.cloud/core/query";
import {
  Railway,
  type AggregatedUsage,
  type EstimatedUsage,
  type MetricMeasurement,
  type MetricTag,
  type UsageLimit as RailwayUsageLimit,
  type UsageLimitSetInput,
} from "@distilled.cloud/railway";
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 { RailwayEnvironment, resolveWorkspace } from "./Environment.ts";
import { waitUntilDeleted } from "./GraphQL.ts";
import type { Providers } from "./Providers.ts";

const usageFields = <E>(row: Query<AggregatedUsage, E>) => ({
  measurement: row.measurement,
  value: row.value,
  tags: {
    deploymentId: row.tags.deploymentId,
    deploymentInstanceId: row.tags.deploymentInstanceId,
    environmentId: row.tags.environmentId,
    projectId: row.tags.projectId,
    region: row.tags.region,
    serviceId: row.tags.serviceId,
    volumeId: row.tags.volumeId,
    volumeInstanceId: row.tags.volumeInstanceId,
  },
});
type UsageResultItem = UnwrapPlan<ReturnType<typeof usageFields>>;

const estimatedUsageFields = <E>(row: Query<EstimatedUsage, E>) => ({
  measurement: row.measurement,
  estimatedValue: row.estimatedValue,
  projectId: row.projectId,
});
type EstimatedUsageResultItem = UnwrapPlan<ReturnType<typeof estimatedUsageFields>>;

const limitFields = <E>(limit: Query<RailwayUsageLimit, E>) => ({
  id: limit.id,
  customerId: limit.customerId,
  softLimit: limit.softLimit,
  hardLimit: limit.hardLimit,
  isOverLimit: limit.isOverLimit,
});
type CloudLimit = UnwrapPlan<ReturnType<typeof limitFields>>;

/**
 * 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 { EstimatedUsageResultItem, MetricMeasurement, MetricTag, UsageResultItem };

/**
 * Workspace identity a usage limit applies to. Accepts a
 * `Railway.Project` (`workspaceId`), `{ workspaceId }`, or `{ id }`.
 */
export type UsageLimitWorkspace = { readonly workspaceId?: string; readonly id?: string };

/**
 * Project whose workspace a usage limit applies to. Accepts a
 * `Railway.Project` or a `{ workspaceId, projectId? }` stub.
 */
export type UsageLimitProject = { readonly workspaceId: string; readonly projectId?: string };

/**
 * Dollar cap passed to `usageLimitSet`. A number is the soft limit.
 */
export type UsageLimitAmount = {
  readonly softLimitDollars: number;
  readonly hardLimitDollars?: number;
};

export interface UsageQuery {
  /**
   * Project to query. Accepts a project id, a `Railway.Project`, or a
   * `{ projectId }` stub. Omit for workspace-wide usage.
   */
  project?: string | { readonly projectId: string };
  /**
   * Workspace to query. Accepts a workspace id, `{ workspaceId }` /
   * `{ id }`, or a `Railway.Project`. Defaults to the current token
   * workspace.
   */
  workspace?: string | UsageLimitWorkspace;
  /**
   * Measurements to aggregate (`CPU_USAGE`, `MEMORY_USAGE_GB`, …).
   */
  measurements: ReadonlyArray<MetricMeasurement>;
  /**
   * Inclusive start of the window (RFC3339). Omit for the current
   * billing period of the project owner.
   */
  startDate?: string;
  /**
   * Inclusive end of the window (RFC3339). Omit for now.
   */
  endDate?: string;
  /**
   * Tags to group by (`PROJECT_ID`, `SERVICE_ID`, …). Default is the
   * whole project / workspace.
   */
  groupBy?: ReadonlyArray<MetricTag>;
  /**
   * Include deleted projects in the aggregation.
   *
   * @default false
   */
  includeDeleted?: boolean;
}

export interface EstimatedUsageQuery {
  /**
   * Project to estimate. Accepts a project id, a `Railway.Project`, or a
   * `{ projectId }` stub. Omit for workspace-wide estimates.
   */
  project?: string | { readonly projectId: string };
  /**
   * Workspace to estimate. Defaults to the current token workspace.
   */
  workspace?: string | UsageLimitWorkspace;
  /**
   * Measurements to estimate (`CPU_USAGE`, `MEMORY_USAGE_GB`, …).
   */
  measurements: ReadonlyArray<MetricMeasurement>;
  /**
   * Include deleted projects in the estimate.
   *
   * @default false
   */
  includeDeleted?: boolean;
}

export interface UsageLimitProps {
  /**
   * Workspace whose customer this limit applies to. Accepts a
   * `Railway.Project`, `{ workspaceId }`, or `{ id }`. Defaults to the
   * current token's workspace. Changing it to a different workspace
   * replaces the limit.
   */
  workspace?: Ref<UsageLimitWorkspace>;
  /**
   * Project whose workspace this limit applies to. Alternative to
   * `workspace`. Changing it to a project in a different workspace
   * replaces the limit.
   */
  project?: Ref<UsageLimitProject>;
  /**
   * Dollar cap. A number is `softLimitDollars`. Pass
   * `{ softLimitDollars, hardLimitDollars }` for both. Updates in place
   * via `usageLimitSet`.
   */
  limit: number | UsageLimitAmount;
}

export type UsageLimit = Resource<
  "Railway.UsageLimit",
  UsageLimitProps,
  {
    /** Railway usage-limit id. */
    usageLimitId: string;
    /** Stripe / Railway customer id the cap is set on. */
    customerId: string;
    /** Workspace the customer belongs to. */
    workspaceId: string;
    /** Project used to resolve the workspace, if one was passed. */
    projectId: string | undefined;
    /** Soft dollar cap (`usageLimitSet.softLimitDollars`). */
    softLimitDollars: number;
    /** Hard dollar cap, if set. */
    hardLimitDollars: number | undefined;
    /** Whether current spend is over the soft cap. */
    isOverLimit: boolean;
  },
  never,
  Providers
>;

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

const parseLimit = (limit: number | UsageLimitAmount): UsageLimitAmount => {
  if (typeof limit === "number") {
    return { softLimitDollars: limit };
  }
  return {
    softLimitDollars: limit.softLimitDollars,
    ...(limit.hardLimitDollars !== undefined ? { hardLimitDollars: limit.hardLimitDollars } : {}),
  };
};

const readUsage = Query.fn(
  (args: {
    measurements: ReadonlyArray<MetricMeasurement>;
    workspaceId: string;
    projectId?: string;
    startDate?: string;
    endDate?: string;
    groupBy?: ReadonlyArray<MetricTag>;
    includeDeleted?: boolean;
  }) => Railway.usage(args).pipe(Query.map(usageFields)),
);

const readEstimatedUsage = Query.fn(
  (args: {
    measurements: ReadonlyArray<MetricMeasurement>;
    workspaceId: string;
    projectId?: string;
    includeDeleted?: boolean;
  }) => Railway.estimatedUsage(args).pipe(Query.map(estimatedUsageFields)),
);

/**
 * Billing usage for a project, workspace, or the current user.
 *
 * Pass `measurements`. Omit `startDate` / `endDate` for the current
 * billing period. Omit `project` for the current workspace.
 *
 * @example Current workspace CPU
 * ```typescript
 * const rows = yield* Railway.usage({
 *   measurements: ["CPU_USAGE"],
 * });
 * ```
 *
 * @example Project window
 * ```typescript
 * const rows = yield* Railway.usage({
 *   project: site,
 *   measurements: ["CPU_USAGE", "MEMORY_USAGE_GB"],
 *   startDate: "2026-01-01T00:00:00.000Z",
 *   endDate: "2026-01-31T23:59:59.000Z",
 * });
 * ```
 */
export const usage = Effect.fn(function* (query: UsageQuery) {
  const projectId = projectIdOf(query.project);
  const workspaceId = workspaceIdOf(query.workspace) ?? (yield* resolveWorkspace()).id;
  const rows = yield* readUsage({
    measurements: [...query.measurements],
    workspaceId,
    ...(projectId !== undefined ? { projectId } : {}),
    ...(query.startDate !== undefined ? { startDate: query.startDate } : {}),
    ...(query.endDate !== undefined ? { endDate: query.endDate } : {}),
    ...(query.groupBy !== undefined ? { groupBy: [...query.groupBy] } : {}),
    ...(query.includeDeleted !== undefined ? { includeDeleted: query.includeDeleted } : {}),
  });
  return rows ?? [];
});

/** Catalog helper. Alias of {@link usage}. */
export const Usage = usage;

/**
 * Estimated total cost at the end of the current billing cycle.
 *
 * @example Workspace estimate
 * ```typescript
 * const rows = yield* Railway.estimatedUsage({
 *   measurements: ["CPU_USAGE"],
 * });
 * ```
 */
export const estimatedUsage = Effect.fn(function* (query: EstimatedUsageQuery) {
  const projectId = projectIdOf(query.project);
  const workspaceId = workspaceIdOf(query.workspace) ?? (yield* resolveWorkspace()).id;
  const rows = yield* readEstimatedUsage({
    measurements: [...query.measurements],
    workspaceId,
    ...(projectId !== undefined ? { projectId } : {}),
    ...(query.includeDeleted !== undefined ? { includeDeleted: query.includeDeleted } : {}),
  });
  return rows ?? [];
});

const resolveUsageLimitProps = (
  props: UsageLimitProps | Effect.Effect<UsageLimitProps, never, Providers>,
): Effect.Effect<UsageLimitProps, never, Providers> =>
  Effect.gen(function* () {
    const resolved = Effect.isEffect(props) ? yield* props : props;
    if (globalThis.__ALCHEMY_RUNTIME__) return resolved;
    const workspace =
      resolved.workspace === undefined
        ? undefined
        : Effect.isEffect(resolved.workspace)
          ? yield* resolved.workspace as Effect.Effect<UsageLimitWorkspace, never, Providers>
          : resolved.workspace;
    const project =
      resolved.project === undefined
        ? undefined
        : Effect.isEffect(resolved.project)
          ? yield* resolved.project as Effect.Effect<UsageLimitProject, never, Providers>
          : resolved.project;
    return { ...resolved, workspace, project };
  });

const UsageLimitResource = Resource<UsageLimit>("Railway.UsageLimit");

/**
 * A Railway.UsageLimit is a soft/hard dollar cap on a workspace
 * customer. One limit per customer. `usageLimitRemove` is idempotent.
 *
 * @see https://docs.railway.com/reference/pricing
 *
 * ### Query usage
 * {@link usage} is a catalog helper — not a resource. It returns
 * aggregated rows for the current workspace (or a project).
 *
 * **Example:** Workspace usage
 * ```typescript
 * const rows = yield* Railway.usage({
 *   measurements: ["CPU_USAGE", "MEMORY_USAGE_GB"],
 * });
 * ```
 *
 * ### Set a limit
 * Omit `workspace` / `project` to cap the current token workspace. A
 * number is the soft dollar cap.
 *
 * **Example:** Soft cap
 * ```typescript
 * const cap = yield* Railway.UsageLimit("SpendCap", {
 *   limit: 50,
 * });
 * ```
 *
 * **Example:** Soft and hard
 * ```typescript
 * const cap = yield* Railway.UsageLimit("SpendCap", {
 *   project: site,
 *   limit: { softLimitDollars: 50, hardLimitDollars: 100 },
 * });
 * ```
 *
 * :::caution[Changing `workspace` or `project` to another workspace replaces the limit]
 * The cap is removed from the old customer, then set on the new one.
 * :::
 *
 * ### Module-scope declarations
 * Resource-valued props accept the resource or an Effect producing it.
 *
 * **Example:** Module-scope limit
 * ```typescript
 * // src/billing.ts
 * import * as Railway from "@alchemy.run/railway";
 *
 * export const Site = Railway.Project("Site");
 * export const SpendCap = Railway.UsageLimit("SpendCap", {
 *   project: Site,
 *   limit: 50,
 * });
 * ```
 *
 * @resource
 * @product Workspace
 */
export const UsageLimit: typeof UsageLimitResource = Object.assign(
  (id: string, props: UsageLimitProps | Effect.Effect<UsageLimitProps, never, Providers>) =>
    UsageLimitResource(id, resolveUsageLimitProps(props)),
  UsageLimitResource,
);

export class UsageLimitNotCreated extends Data.TaggedError("Railway.UsageLimitNotCreated")<{
  customerId: string;
  workspaceId: string;
}> {}

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

const currentWorkspaceId = Effect.fn(function* () {
  const env = yield* yield* RailwayEnvironment;
  return env.workspaceId;
});

const readWorkspaceLimit = Query.fn((workspaceId: string) => {
  const customer = Railway.workspace({ workspaceId }).customer;
  return {
    customer: { id: customer.id, usageLimit: customer.usageLimit.pipe(Query.map(limitFields)) },
  };
});

const getWorkspace = (workspaceId: string) =>
  readWorkspaceLimit(workspaceId).pipe(Effect.catchTag("RailwayNotFound", () => Effect.undefined));

const toAttrs = (
  limit: CloudLimit,
  fallback: { workspaceId: string; customerId: string; projectId?: string },
): UsageLimit["Attributes"] => ({
  usageLimitId: limit.id,
  customerId: limit.customerId || fallback.customerId,
  workspaceId: fallback.workspaceId,
  projectId: fallback.projectId,
  softLimitDollars: limit.softLimit,
  hardLimitDollars: limit.hardLimit ?? undefined,
  isOverLimit: limit.isOverLimit,
});

const observe = Effect.fn(function* (workspaceId: string) {
  const workspace = yield* getWorkspace(workspaceId);
  if (workspace === undefined) return undefined;
  return {
    workspace,
    customerId: workspace.customer.id,
    limit: workspace.customer.usageLimit ?? undefined,
  };
});

const usageLimitSet = Query.fn((input: UsageLimitSetInput) => Railway.usageLimitSet({ input }));

const usageLimitRemove = Query.fn((customerId: string) =>
  Railway.usageLimitRemove({ input: { customerId } }),
);

const setLimit = (input: {
  customerId: string;
  softLimitDollars: number;
  hardLimitDollars?: number | null;
}) =>
  usageLimitSet({
    customerId: input.customerId,
    softLimitDollars: input.softLimitDollars,
    ...(input.hardLimitDollars !== undefined ? { hardLimitDollars: input.hardLimitDollars } : {}),
  });

const resolveScope = Effect.fn(function* (input: {
  news?: UsageLimitProps;
  olds?: UsageLimitProps;
  output?: UsageLimit["Attributes"];
}) {
  const projectId =
    projectIdOf(input.news?.project) ?? input.output?.projectId ?? projectIdOf(input.olds?.project);
  const workspaceId =
    workspaceIdOf(input.news?.workspace) ??
    workspaceIdOf(input.news?.project) ??
    input.output?.workspaceId ??
    workspaceIdOf(input.olds?.workspace) ??
    workspaceIdOf(input.olds?.project) ??
    (yield* currentWorkspaceId());
  return { workspaceId, projectId };
});

const waitUntilGone = (workspaceId: string, usageLimitId: string) =>
  waitUntilDeleted(
    "UsageLimit",
    usageLimitId,
    observe(workspaceId).pipe(
      Effect.map((found) => {
        if (found?.limit === undefined) return true;
        return found.limit.id !== usageLimitId;
      }),
    ),
  );

export const UsageLimitProvider = () =>
  Provider.succeed(UsageLimit, {
    stables: ["usageLimitId", "customerId", "workspaceId"],

    diff: Effect.fn(function* ({ news, output }) {
      if (news === undefined || !isResolved(news)) return undefined;
      if (output === undefined) return undefined;
      const nextWorkspace = workspaceIdOf(news.workspace) ?? workspaceIdOf(news.project);
      if (nextWorkspace !== undefined && nextWorkspace !== output.workspaceId) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ olds, output }) {
      const { workspaceId, projectId } = yield* resolveScope({ olds, output });
      const found = yield* observe(workspaceId);
      if (found?.limit === undefined) return undefined;
      return toAttrs(found.limit, { workspaceId, customerId: found.customerId, projectId });
    }),

    list: Effect.fn(function* () {
      const workspaceId = yield* currentWorkspaceId();
      const found = yield* observe(workspaceId);
      if (found?.limit === undefined) return [];
      return [toAttrs(found.limit, { workspaceId, customerId: found.customerId })];
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const props = news ?? ({} as UsageLimitProps);
      const { workspaceId, projectId } = yield* resolveScope({ news: props, output });
      const desired = parseLimit(props.limit ?? output?.softLimitDollars ?? 0);

      let found = yield* observe(workspaceId);
      if (found === undefined) {
        return yield* new UsageLimitWorkspaceNotFound({ workspaceId });
      }

      const observed = found.limit;
      const hardChanged =
        desired.hardLimitDollars !== undefined
          ? (observed?.hardLimit ?? undefined) !== desired.hardLimitDollars
          : observed?.hardLimit != null;
      const needsSet =
        observed === undefined || observed.softLimit !== desired.softLimitDollars || hardChanged;

      if (needsSet) {
        yield* setLimit({
          customerId: found.customerId,
          softLimitDollars: desired.softLimitDollars,
          ...(desired.hardLimitDollars !== undefined
            ? { hardLimitDollars: desired.hardLimitDollars }
            : observed?.hardLimit != null
              ? { hardLimitDollars: null }
              : {}),
        }).pipe(Effect.catchTag("RailwayValidationError", () => Effect.void));
        found = yield* observe(workspaceId);
      }

      if (found?.limit === undefined) {
        return yield* new UsageLimitNotCreated({
          customerId: found?.customerId ?? output?.customerId ?? "",
          workspaceId,
        });
      }

      return toAttrs(found.limit, { workspaceId, customerId: found.customerId, projectId });
    }),

    delete: Effect.fn(function* ({ output }) {
      const customerId = output.customerId;
      const workspaceId = output.workspaceId;
      if (customerId.length === 0) return;
      yield* usageLimitRemove(customerId);
      if (workspaceId.length > 0 && output.usageLimitId.length > 0) {
        yield* waitUntilGone(workspaceId, output.usageLimitId);
      }
    }),
  });