import * as Data from "effect/Data"; import * as Effect from "effect/Effect"; import { State, type StateService, type StateStoreError } from "./State.ts"; import { encodeState } from "./StateEncoding.ts"; // The store viewed as a filesystem: `stack/stage/fqn` for a resource record, // `stack/stage/output` for a stage's outputs. Everything here addresses that // tree by slash-separated path, so a CLI or an RPC client can walk state // without knowing the backend's key layout. /** Reading or listing a path. Omit `path` for the root. */ export interface TreeQuery { readonly path?: string; /** Recurse into every descendant instead of stopping at immediate children. */ readonly recursive?: boolean; } /** Deleting a path. The path is required — the root is not deletable. */ export interface TreeDelete { readonly path: string; /** Delete every descendant when the path identifies a directory. */ readonly recursive?: boolean; } /** One decoded record produced by {@link readState}. */ export interface StateEntry { readonly path: string; readonly kind: "resource" | "output"; readonly value: unknown; } /** The path does not exist, or does not support the requested operation. */ export class InvalidStatePath extends Data.TaggedError("InvalidStatePath")<{ readonly path: string; readonly reason: string; }> {} export interface StateDeleted { readonly _tag: "StateDeleted"; readonly path: string; readonly deleted: ReadonlyArray; } /** * Every `(stack, stage)` pair the store holds, or the subset a filter pins. * * Enumerating them means `listStacks` then a `listStages` per stack, so the * fan-out runs concurrently: against a remote store a serial walk is one * round trip per stack before the first stage is even known. A pinned * `stack`/`stage` is taken at face value and skips the corresponding call — * naming a scope is not a claim that it exists, and callers report a missing * one from the emptiness of what comes back. * * Ordered by stack then stage so every traversal built on it is deterministic. */ export const allStages = Effect.fn("allStages")(function* ( filter: { readonly stack?: string; readonly stage?: string } = {}, ) { return yield* stagesOf(yield* yield* State, filter); }); const stagesOf = ( state: StateService, filter: { readonly stack?: string; readonly stage?: string }, ): Effect.Effect< ReadonlyArray<{ readonly stack: string; readonly stage: string }>, StateStoreError > => Effect.gen(function* () { const stacks = filter.stack !== undefined ? [filter.stack] : [...(yield* state.listStacks())].sort(); if (filter.stage !== undefined) { const stage = filter.stage; return stacks.map((stack) => ({ stack, stage })); } const perStack = yield* Effect.forEach( stacks, (stack) => Effect.map(state.listStages(stack), (stages) => [...stages].sort().map((stage) => ({ stack, stage })), ), { concurrency: "unbounded" }, ); return perStack.flat(); }); type StateFile = | { readonly kind: "resource"; readonly path: string; readonly stack: string; readonly stage: string; readonly fqn: string; } | { readonly kind: "output"; readonly path: string; readonly stack: string; readonly stage: string; }; const pathParts = (path: string | undefined): ReadonlyArray => (path ?? "").split("/").filter((part) => part !== "" && part !== "."); const invalidPath = (path: string, reason = "path does not exist") => Effect.fail(new InvalidStatePath({ path, reason })); const parsePath = (path: string | undefined) => { const parts = pathParts(path); return parts.includes("..") ? invalidPath(path ?? "/", "parent path segments are not allowed") : Effect.succeed(parts); }; const stageFiles = Effect.fn(function* (state: StateService, stack: string, stage: string) { const fqns = yield* state.list({ stack, stage }); return [ ...fqns.map((fqn): StateFile => ({ kind: "resource", path: `${stack}/${stage}/${fqn}`, stack, stage, fqn, })), { kind: "output", path: `${stack}/${stage}/output`, stack, stage, } as const, ]; }); /** Every file under the given scope, listed one stage at a time in parallel. */ const filesUnder = Effect.fn(function* ( state: StateService, filter: { readonly stack?: string } = {}, ) { const stages = yield* stagesOf(state, filter); const perStage = yield* Effect.forEach( stages, ({ stack, stage }) => stageFiles(state, stack, stage), { concurrency: "unbounded" }, ); return perStage.flat(); }); const filesAt = Effect.fn(function* (state: StateService, parts: ReadonlyArray) { const path = parts.join("/"); if (parts.length === 0) { return { directory: true as const, files: yield* filesUnder(state) }; } if (parts.length === 1) { const stack = parts[0]!; if (!(yield* state.listStacks()).includes(stack)) { return yield* invalidPath(path); } return { directory: true as const, files: yield* filesUnder(state, { stack }), }; } if (parts.length === 2) { const [stack, stage] = parts as [string, string]; if (!(yield* state.listStages(stack)).includes(stage)) { return yield* invalidPath(path); } return { directory: true as const, files: yield* stageFiles(state, stack, stage), }; } const files = yield* stageFiles(state, parts[0]!, parts[1]!); const exact = files.find((file) => file.path === path); if (exact !== undefined) return { directory: false as const, files: [exact] }; const descendants = files.filter((file) => file.path.startsWith(`${path}/`)); if (descendants.length === 0) return yield* invalidPath(path); return { directory: true as const, files: descendants }; }); export const listState = Effect.fn("listState")(function* ({ path, recursive = false }: TreeQuery) { const state = yield* yield* State; const parts = yield* parsePath(path); const normalizedPath = parts.join("/"); if (parts.length === 0 && !recursive) { return (yield* state.listStacks()).map((stack) => `${stack}/`); } const { directory, files } = yield* filesAt(state, parts); if (!directory) return [normalizedPath]; const prefix = normalizedPath === "" ? "" : `${normalizedPath}/`; if (recursive) return files.map((file) => file.path); return [ ...new Set( files.map((file) => { const rest = file.path.slice(prefix.length); const child = rest.split("/")[0]!; return rest.includes("/") ? `${prefix}${child}/` : file.path; }), ), ]; }); export const readState = Effect.fn("readState")(function* ({ path, recursive = false }: TreeQuery) { const state = yield* yield* State; const parts = yield* parsePath(path); const target = yield* filesAt(state, parts); if (target.directory && !recursive) { return yield* invalidPath( path ?? "/", "path is a directory; set recursive to read its descendants", ); } return yield* Effect.forEach(target.files, (file) => (file.kind === "output" ? state.getOutput(file) : state.get(file)).pipe( Effect.map((value): StateEntry => ({ path: file.path, kind: file.kind, value: encodeState(value) ?? null, })), ), ); }); export const deleteState = Effect.fn("deleteState")(function* ({ path, recursive = false, }: TreeDelete) { const state = yield* yield* State; const parts = yield* parsePath(path); if (parts.length === 0) { return yield* invalidPath(path, "the state root cannot be deleted"); } const target = yield* filesAt(state, parts); if (target.directory && !recursive) { return yield* invalidPath(path, "path is a directory; set recursive to delete its descendants"); } if (parts.length === 1) { yield* state.deleteStack({ stack: parts[0]! }); } else if (parts.length === 2) { yield* state.deleteStack({ stack: parts[0]!, stage: parts[1]! }); } else { const resources = target.files.filter( (file): file is Extract => file.kind === "resource", ); if (resources.length === 0) { return yield* invalidPath(path, "output cannot be deleted independently"); } yield* Effect.forEach(resources, (file) => state.delete(file), { concurrency: 32, discard: true, }); } return { _tag: "StateDeleted" as const, path: parts.join("/"), deleted: target.files.map((file) => file.path), }; });