alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/src/Provider.ts

@@ -10,7 +10,7 @@ import type { Diff } from "./Diff.ts";
 import type { Input } from "./Input.ts";
 import type { InstanceId } from "./InstanceId.ts";
 import type { Platform } from "./Platform.ts";
-import type { ProviderMode } from "./ProviderMode.ts";
+import { defaultProviderMode, type ProviderMode } from "./ProviderMode.ts";
 import type {
   ResourceBinding,
   ResourceClass,
@@ -133,6 +133,31 @@ export interface ProviderService<
    * even during a live deploy (and vice versa).
    */
   modes?: { readonly [M in ProviderMode]: Effect.Effect<ProviderService<Res>> };
+  /**
+   * Data-plane override context for this provider's **local** mode: a layer
+   * of cloud environment services (endpoint, credentials, region,
+   * environment) that points data-plane API calls at the local emulator —
+   * the same override the local lifecycle variant runs under (e.g. AWS's
+   * `flociServices()`).
+   *
+   * Set by `ProviderLayer.dual` registrations that pass `dataPlane`.
+   * Consumed by `Binding.Service`'s client wrapper (via
+   * {@link resolveLocalDataPlane}) so deploy-time binding invocations —
+   * inside an `Action` body or a plan-time `execute` — target whatever
+   * data plane the bound resource actually lives on: a local-mode resource
+   * routes to the emulator while an `Alchemy.remote()` resource keeps
+   * hitting the real cloud. Pass a module-memoized layer reference.
+   */
+  localDataPlane?: () => Layer.Layer<any, any, never>;
+  /**
+   * Data-plane override context for this provider's **live** mode: the
+   * cloud environment captured at provider registration (credentials,
+   * region, endpoint). In an `alchemy dev` run the ambient environment IS
+   * the emulator, so an unwrapped live client would hit floci. Stamp this
+   * so `Alchemy.remote()` binding calls are provided the live chain
+   * closest, the inverse of {@link localDataPlane}.
+   */
+  liveDataPlane?: () => Layer.Layer<any, any, never>;
   /**
    * Account-wide teardown (`alchemy unsafe nuke`) behaviour. Providers whose
    * resources can't meaningfully be deleted opt out here so nuke doesn't
@@ -405,7 +430,7 @@ export const effect = <
   LogsReq = never,
   ListReq = never,
 >(
-  cls: ResourceClassLike<R> | Platform<R, any, any, any, any>,
+  cls: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
   eff: Effect.Effect<
     ProviderServiceInput<
       R,
@@ -449,7 +474,7 @@ export const succeed = <
   LogsReq = never,
   ListReq = never,
 >(
-  cls: ResourceClass<R> | Platform<R, any, any, any, any>,
+  cls: ResourceClass<R> | Platform<R, any, any, any, any, any>,
   service: ProviderServiceInput<
     R,
     ReadReq,
@@ -514,13 +539,13 @@ export interface ProviderCollectionService {
 }
 
 export const collection = <
-  R extends ResourceClassLike<any> | Platform<any, any, any, any, any>,
+  R extends ResourceClassLike<any> | Platform<any, any, any, any, any, any>,
 >(
   resources: R[],
 ): Effect.Effect<
   ProviderCollectionService,
   never,
-  R extends ResourceClass<infer R> | Platform<infer R, any, any, any, any>
+  R extends ResourceClass<infer R> | Platform<infer R, any, any, any, any, any>
     ? Provider<R>
     : never
 > =>
@@ -595,6 +620,78 @@ export const providerForMode = <R extends ResourceLike>(
     ? service.modes[mode]
     : Effect.succeed(service);
 
+/**
+ * Why a resource's deploy-time binding clients target the data plane they
+ * do — see {@link describeDataPlane}.
+ *
+ * - `local` — the resource runs on its provider's local emulator; `layer`
+ *   is the override to provide closest around every client call.
+ * - `live` — the resource targets the real cloud: either pinned there
+ *   (`Alchemy.remote()`) or the run is a plain deploy. `layer` is the
+ *   registration-captured live environment, provided closest around every
+ *   client call so a `remote()` resource still hits the real cloud when the
+ *   ambient environment is the emulator.
+ * - `undeclared` — the resource resolves to local mode, but its provider
+ *   is a dual registration without a {@link ProviderService.localDataPlane}
+ *   (a process-hosted local variant with no API to route to, or a missing
+ *   `dataPlane` on a hand-written `ProviderLayer.dual`). Clients fall back
+ *   to the real cloud — reported by name so the two are never confused.
+ * - `agnostic` — the provider is mode-agnostic (plain registration); its
+ *   resources live on the real cloud even in dev.
+ * - `unregistered` — no provider in context (bare runtime, unit tests).
+ */
+export type DataPlaneResolution =
+  | { readonly kind: "local"; readonly layer: Layer.Layer<any, any, never> }
+  | {
+      readonly kind: "live";
+      readonly layer?: Layer.Layer<any, any, never> | undefined;
+    }
+  | { readonly kind: "undeclared"; readonly providerType: string }
+  | { readonly kind: "agnostic" }
+  | { readonly kind: "unregistered" };
+
+/**
+ * Resolve where a resource's deploy-time binding clients should be routed:
+ * its registration-captured {@link ResourceLike.Mode} (`Alchemy.remote()`
+ * → `"live"`) or the run default (`alchemy dev` → `"local"`) — the same
+ * resolution `Plan.make` applies to lifecycle operations — combined with
+ * whether the provider registered a local data plane at all.
+ */
+export const describeDataPlane = (resource: {
+  readonly Type: string;
+  readonly Mode?: ProviderMode | undefined;
+}): Effect.Effect<DataPlaneResolution> =>
+  Effect.gen(function* () {
+    const found = yield* tryFindProviderByType(resource.Type);
+    if (Option.isNone(found)) return { kind: "unregistered" as const };
+    const provider = found.value;
+    if (provider.modes === undefined) return { kind: "agnostic" as const };
+    const mode = resource.Mode ?? (yield* defaultProviderMode);
+    if (mode !== "local") {
+      const layer = provider.liveDataPlane?.();
+      return layer !== undefined
+        ? { kind: "live" as const, layer }
+        : { kind: "live" as const };
+    }
+    if (provider.localDataPlane === undefined) {
+      return { kind: "undeclared" as const, providerType: resource.Type };
+    }
+    return { kind: "local" as const, layer: provider.localDataPlane() };
+  });
+
+/**
+ * The data-plane override layer for a resource, or `undefined` when its
+ * clients target the real cloud for any reason (see
+ * {@link describeDataPlane} for which).
+ */
+export const resolveLocalDataPlane = (resource: {
+  readonly Type: string;
+  readonly Mode?: ProviderMode | undefined;
+}): Effect.Effect<Layer.Layer<any, any, never> | undefined> =>
+  describeDataPlane(resource).pipe(
+    Effect.map((plane) => (plane.kind === "local" ? plane.layer : undefined)),
+  );
+
 export const findProviderByType: {
   <R extends ResourceLike>(
     resourceType: R["Type"],
@@ -618,7 +715,7 @@ export const findProviderByType: {
  */
 export const findProvider: {
   <R extends ResourceLike>(
-    resource: ResourceClassLike<R> | Platform<R, any, any, any, any>,
+    resource: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
     mode?: ProviderMode,
   ): Effect.Effect<ProviderService<R>>;
 } = (resource: { Type?: string; key?: string }, mode?: ProviderMode) =>

package/src/Railway/AuditLog.ts

@@ -0,0 +1,240 @@
+import type {
+  AuditLogEventTypeInfoResultItem,
+  AuditLogResponse,
+  AuditLogsResponseEdgesItemNode,
+} from "@distilled.cloud/railway";
+import * as railway from "@distilled.cloud/railway";
+import * as Effect from "effect/Effect";
+import { resolveWorkspaceId } from "./Environment.ts";
+
+/**
+ * Project identity for {@link listAuditLogs}. Accepts a `Railway.Project`
+ * or a `{ projectId }` stub.
+ */
+export type AuditLogProject = {
+  readonly projectId: string;
+};
+
+/**
+ * Environment identity for {@link listAuditLogs}. Accepts a
+ * `Railway.Project` (primary environment), a `Railway.Environment`, or
+ * `{ environmentId }`.
+ */
+export type AuditLogEnvironment = {
+  readonly environmentId: string;
+};
+
+export interface ListAuditLogsOptions {
+  /**
+   * Restrict to a project. Accepts a `Railway.Project` or `{ projectId }`.
+   */
+  project?: AuditLogProject | string;
+  /**
+   * Restrict to an environment. Accepts a `Railway.Project`, a
+   * `Railway.Environment`, or `{ environmentId }`.
+   */
+  environment?: AuditLogEnvironment | string;
+  /**
+   * Event type names from {@link listAuditLogEventTypes}.
+   */
+  eventTypes?: readonly string[];
+  /**
+   * Inclusive start (RFC3339).
+   */
+  startDate?: string;
+  /**
+   * Inclusive end (RFC3339).
+   */
+  endDate?: string;
+  /**
+   * Workspace id. Defaults to the current token workspace.
+   */
+  workspaceId?: string;
+  /**
+   * Page size. Defaults to 50. This helper fetches one page — it does
+   * not walk the whole workspace history.
+   * @default 50
+   */
+  first?: number;
+  /**
+   * Sort by `createdAt`. Railway default is `desc`.
+   */
+  sort?: "asc" | "desc";
+}
+
+/**
+ * One workspace audit-log row from `auditLogs` / `auditLog`.
+ */
+export interface AuditLogEntry {
+  /** Audit log id. */
+  readonly id: string;
+  /** Event type name (see {@link listAuditLogEventTypes}). */
+  readonly eventType: string;
+  /** RFC3339 creation timestamp. */
+  readonly createdAt: string;
+  /** Workspace the event was recorded in. */
+  readonly workspaceId: string | undefined;
+  /** Project the event targeted, when Railway attached one. */
+  readonly projectId: string | undefined;
+  /** Environment the event targeted, when Railway attached one. */
+  readonly environmentId: string | undefined;
+  /** Event payload. Shape depends on `eventType`. */
+  readonly payload: unknown;
+  /** Extra context Railway attached to the event. */
+  readonly context: unknown;
+}
+
+export type AuditLogEventType = AuditLogEventTypeInfoResultItem;
+
+type AuditLogRow = AuditLogResponse | AuditLogsResponseEdgesItemNode;
+
+const toEntry = (row: AuditLogRow): AuditLogEntry => ({
+  id: row.id,
+  eventType: row.eventType,
+  createdAt: row.createdAt,
+  workspaceId: row.workspaceId ?? undefined,
+  projectId: row.projectId ?? undefined,
+  environmentId: row.environmentId ?? undefined,
+  payload: row.payload ?? undefined,
+  context: row.context ?? undefined,
+});
+
+const projectIdOf = (
+  value: AuditLogProject | string | undefined,
+): string | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value === "string") return value;
+  return value.projectId;
+};
+
+const environmentIdOf = (
+  value: AuditLogEnvironment | string | undefined,
+): string | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value === "string") return value;
+  return value.environmentId;
+};
+
+const workspaceOf = (workspaceId: string | undefined) =>
+  workspaceId !== undefined
+    ? Effect.succeed(workspaceId)
+    : resolveWorkspaceId();
+
+/**
+ * List workspace audit logs. Query-only — Railway has no audit-log
+ * create/update/delete, so this is a catalog helper, not a resource.
+ *
+ * Defaults to the current token workspace. Pass `project` /
+ * `environment` to filter. The result may be empty.
+ *
+ * @see https://docs.railway.com/reference/audit-logs
+ *
+ * ### List logs
+ * **Example:** Workspace logs
+ * ```typescript
+ * const logs = yield* Railway.listAuditLogs();
+ * ```
+ *
+ * **Example:** Filter by project
+ * ```typescript
+ * const site = yield* Railway.Project("Site");
+ * const logs = yield* Railway.listAuditLogs({
+ *   project: site,
+ *   environment: site,
+ * });
+ * ```
+ *
+ * ### Get by id
+ * **Example:** One row
+ * ```typescript
+ * const log = yield* Railway.getAuditLog({ id: logs[0].id });
+ * ```
+ *
+ * ### Event types
+ * **Example:** Catalog
+ * ```typescript
+ * const types = yield* Railway.listAuditLogEventTypes();
+ * ```
+ *
+ * @resource
+ */
+export const AuditLog = Effect.fn(function* (options?: ListAuditLogsOptions) {
+  const workspaceId = yield* workspaceOf(options?.workspaceId);
+  const projectId = projectIdOf(options?.project);
+  const environmentId = environmentIdOf(options?.environment);
+  const first = options?.first ?? 50;
+  const filter =
+    projectId !== undefined ||
+    environmentId !== undefined ||
+    options?.eventTypes !== undefined ||
+    options?.startDate !== undefined ||
+    options?.endDate !== undefined
+      ? {
+          ...(projectId !== undefined ? { projectId } : {}),
+          ...(environmentId !== undefined ? { environmentId } : {}),
+          ...(options?.eventTypes !== undefined
+            ? { eventTypes: [...options.eventTypes] }
+            : {}),
+          ...(options?.startDate !== undefined
+            ? { startDate: options.startDate }
+            : {}),
+          ...(options?.endDate !== undefined
+            ? { endDate: options.endDate }
+            : {}),
+        }
+      : undefined;
+
+  const page = yield* railway
+    .auditLogs({
+      workspaceId,
+      first,
+      ...(options?.sort !== undefined ? { sort: options.sort } : {}),
+      ...(filter !== undefined ? { filter } : {}),
+    })
+    .pipe(
+      Effect.catchTag(["RailwayNotFound", "NotFound"], () =>
+        Effect.succeed({
+          edges: [] as { node: AuditLogsResponseEdgesItemNode }[],
+        }),
+      ),
+    );
+
+  return (page.edges ?? []).map((edge) => toEntry(edge.node));
+});
+
+/** Alias of {@link AuditLog}. */
+export const listAuditLogs = AuditLog;
+
+/**
+ * Fetch one audit log by id. Workspace defaults to the current token
+ * workspace.
+ *
+ * @example Get by id
+ * ```typescript
+ * const log = yield* Railway.getAuditLog({ id: logs[0].id });
+ * ```
+ */
+export const getAuditLog = Effect.fn(function* (options: {
+  id: string;
+  workspaceId?: string;
+}) {
+  const workspaceId = yield* workspaceOf(options.workspaceId);
+  const row = yield* railway.auditLog({
+    id: options.id,
+    workspaceId,
+  });
+  return toEntry(row);
+});
+
+/**
+ * Event types Railway can record, with descriptions.
+ *
+ * @example Event type catalog
+ * ```typescript
+ * const types = yield* Railway.listAuditLogEventTypes();
+ * ```
+ */
+export const listAuditLogEventTypes = Effect.fn(function* () {
+  const types = yield* railway.auditLogEventTypeInfo({});
+  return types ?? [];
+});