From e2a6c9d919d8d77b09b76ef9e69e692b87c8ae5e Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 16 Nov 2026 13:53:16 +0100 Subject: [PATCH 01/45] feat(cli): generate warehouse commands from the Management API spec --- .github/workflows/api-package-sync.yml | 5 +- .oxlintrc.json | 2 + apps/cli/package.json | 2 + apps/cli/schemas/config/v1.json | 24 + apps/cli/scripts/api-command-derive.ts | 722 ++++++++++++++ .../scripts/api-command-derive.unit.test.ts | 262 ++++++ apps/cli/scripts/generate-api-commands.ts | 133 +++ .../cli/boolean-flag-defaults.unit.test.ts | 10 +- apps/cli/src/cli/main.ts | 9 +- apps/cli/src/cli/root.ts | 3 + .../command-errors.annotation.ts | 23 + .../command-permissions.unit.test.ts | 1 + .../fga-request-sets.unit.test.ts | 1 + .../help-section.tree.unit.test.ts | 1 + .../command-surface.integration.test.ts | 133 +++ .../command-surface/command-surface.ts | 287 ++++++ .../hosted-consent-coverage.unit.test.ts | 3 +- .../target/target-policy.unit.test.ts | 1 + .../api-command-bindings.integration.test.ts | 388 ++++++++ .../src/commands/api/api-command-execute.ts | 301 ++++++ .../api/api-command-execute.unit.test.ts | 60 ++ .../cli/src/commands/api/api-command-flags.ts | 38 + .../cli/src/commands/api/api-command-names.ts | 53 ++ .../src/commands/api/api-command-pointer.ts | 33 + .../src/commands/api/api-command-request.ts | 240 +++++ .../cli/src/commands/api/api-command-stage.ts | 37 + .../commands/api/api-command.annotation.ts | 29 + .../src/commands/api/api-command.errors.ts | 54 ++ .../cli/src/commands/api/api-command.model.ts | 95 ++ .../src/commands/api/api-commands.e2e.test.ts | 194 ++++ .../api/api-commands.integration.test.ts | 883 ++++++++++++++++++ .../cli/src/commands/api/generated.schemas.ts | 437 +++++++++ apps/cli/src/commands/api/generated.ts | 178 ++++ apps/cli/src/commands/api/runtime.ts | 271 ++++++ .../cli/src/commands/api/warehouse-backend.ts | 35 + .../api/warehouse/enable/SIDE_EFFECTS.md | 86 ++ .../api/warehouse/status/SIDE_EFFECTS.md | 74 ++ .../cli-config-flag-ownership.unit.test.ts | 2 +- apps/cli/src/shared/cli/agent-output.ts | 4 +- apps/cli/src/shared/cli/run.ts | 61 +- .../cli/standard-errors.integration.test.ts | 153 +++ apps/cli/src/shared/cli/standard-errors.ts | 241 +++++ .../shared/cli/standard-errors.unit.test.ts | 178 ++++ .../shared/cli/subcommand-flag-suggestions.ts | 3 +- .../src/shared/cli/value-consuming-flags.ts | 7 + .../src/shared/config/experimental-feature.ts | 2 + .../telemetry/__fixtures__/error-tags.txt | 4 + .../cli/tests/fixtures/standard-errors-cli.ts | 69 ++ .../tests/helpers/command-flags.unit.test.ts | 2 + apps/cli/tests/helpers/hosted-consent.ts | 4 +- knip.jsonc | 3 + package.json | 4 +- packages/api/scripts/openapi-overrides.json | 720 ++++++++++++++ packages/api/src/generated/contracts.ts | 401 ++++++++ packages/api/src/generated/effect-client.ts | 32 + packages/api/src/generated/openapi.json | 702 ++++++++++++++ packages/api/src/generated/permissions.ts | 2 + packages/config/src/experimental.ts | 6 + .../src/project-config/hosted-sections.ts | 1 + .../project-config.unit.test.ts | 1 + turbo.json | 16 + 61 files changed, 7700 insertions(+), 26 deletions(-) create mode 100644 apps/cli/scripts/api-command-derive.ts create mode 100644 apps/cli/scripts/api-command-derive.unit.test.ts create mode 100644 apps/cli/scripts/generate-api-commands.ts create mode 100644 apps/cli/src/command-internal/command-errors/command-errors.annotation.ts create mode 100644 apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts create mode 100644 apps/cli/src/command-internal/command-surface/command-surface.ts create mode 100644 apps/cli/src/commands/api/api-command-bindings.integration.test.ts create mode 100644 apps/cli/src/commands/api/api-command-execute.ts create mode 100644 apps/cli/src/commands/api/api-command-execute.unit.test.ts create mode 100644 apps/cli/src/commands/api/api-command-flags.ts create mode 100644 apps/cli/src/commands/api/api-command-names.ts create mode 100644 apps/cli/src/commands/api/api-command-pointer.ts create mode 100644 apps/cli/src/commands/api/api-command-request.ts create mode 100644 apps/cli/src/commands/api/api-command-stage.ts create mode 100644 apps/cli/src/commands/api/api-command.annotation.ts create mode 100644 apps/cli/src/commands/api/api-command.errors.ts create mode 100644 apps/cli/src/commands/api/api-command.model.ts create mode 100644 apps/cli/src/commands/api/api-commands.e2e.test.ts create mode 100644 apps/cli/src/commands/api/api-commands.integration.test.ts create mode 100644 apps/cli/src/commands/api/generated.schemas.ts create mode 100644 apps/cli/src/commands/api/generated.ts create mode 100644 apps/cli/src/commands/api/runtime.ts create mode 100644 apps/cli/src/commands/api/warehouse-backend.ts create mode 100644 apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md create mode 100644 apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md create mode 100644 apps/cli/src/shared/cli/standard-errors.integration.test.ts create mode 100644 apps/cli/src/shared/cli/standard-errors.ts create mode 100644 apps/cli/src/shared/cli/standard-errors.unit.test.ts create mode 100644 apps/cli/tests/fixtures/standard-errors-cli.ts diff --git a/.github/workflows/api-package-sync.yml b/.github/workflows/api-package-sync.yml index d651f7b49d..95a2ccc89c 100644 --- a/.github/workflows/api-package-sync.yml +++ b/.github/workflows/api-package-sync.yml @@ -28,13 +28,16 @@ jobs: env: SUPABASE_API_URL: https://api.supabase.com + - name: Regenerate API commands + run: pnpm --filter supabase run api-commands:generate + - name: Format API package run: pnpm run fmt:fix - name: Check for generated changes id: check run: | - if git diff --ignore-space-at-eol --exit-code --quiet packages/api/src/generated packages/api/scripts/openapi-source.json; then + if git diff --ignore-space-at-eol --exit-code --quiet packages/api/src/generated packages/api/scripts/openapi-source.json apps/cli/src/commands/api/generated.ts apps/cli/src/commands/api/generated.schemas.ts; then echo "No generated changes detected." echo "has_changes=false" >> "$GITHUB_OUTPUT" else diff --git a/.oxlintrc.json b/.oxlintrc.json index f48e4f2a84..a0076f3df5 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -10,6 +10,8 @@ ".repos", /* Generated from the OpenAPI spec by `packages/api/scripts/generate.ts`. */ "packages/api/src/generated/contracts.ts", + // Generated command data, whose API paths are data rather than hand-built requests. + "apps/cli/src/commands/api/generated.ts", // Generated by `supabase gen types` (see `gen:feedback-types` in apps/cli). "apps/cli/src/shared/feedback/database.types.ts", /* Standalone Node shim built with `bun build --target node` that does not use Effect. */ diff --git a/apps/cli/package.json b/apps/cli/package.json index d0fdd65efd..691f55756d 100644 --- a/apps/cli/package.json +++ b/apps/cli/package.json @@ -24,6 +24,8 @@ "access": "public" }, "scripts": { + "api-commands:check": "bun scripts/generate-api-commands.ts --check", + "api-commands:generate": "bun scripts/generate-api-commands.ts", "build": "pnpm build:binary && pnpm build:shim", "build:binary": "bun scripts/build-binary.ts", "build:shim": "bun build src/shared/cli/bin.ts --outfile dist/supabase.js --target node", diff --git a/apps/cli/schemas/config/v1.json b/apps/cli/schemas/config/v1.json index 05c19c774b..e558df751a 100644 --- a/apps/cli/schemas/config/v1.json +++ b/apps/cli/schemas/config/v1.json @@ -4326,6 +4326,18 @@ } ] }, + "warehouse": { + "description": "Enable the experimental warehouse command family.", + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "pattern": "^env\\((.*)\\)$" + } + ] + }, "stack": { "description": "Use the new local stack backend for start, stop, and status, and for --local targets of the db, migration, test db, gen types, inspect, and pull command families.", "anyOf": [ @@ -9251,6 +9263,18 @@ } ] }, + "warehouse": { + "description": "Enable the experimental warehouse command family.", + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "pattern": "^env\\((.*)\\)$" + } + ] + }, "stack": { "description": "Use the new local stack backend for start, stop, and status, and for --local targets of the db, migration, test db, gen types, inspect, and pull command families.", "anyOf": [ diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts new file mode 100644 index 0000000000..b4dcde8eb3 --- /dev/null +++ b/apps/cli/scripts/api-command-derive.ts @@ -0,0 +1,722 @@ +import type { OperationId } from "@supabase/api/effect"; +import { Predicate, Schema } from "effect"; +import { + verbVocabulary, + type ApiCommandName, + type ApiNoun, +} from "../src/commands/api/api-command-names.ts"; +import type { + ApiCommandBinding, + ApiCommandEntry, + ApiCommandFlag, + ApiCommandSchemas, + ApiCommandWait, +} from "../src/commands/api/api-command.model.ts"; + +type JsonObject = Readonly>; + +/** Flags the generated-command runtime adds itself. */ +const RESERVED_FLAGS: ReadonlySet = new Set([ + "body", + "file", + "remote", + "project-ref", + "yes", + "dry-run", + "wait", + "timeout", + "output", + "output-format", + "experimental", + "help", +]); + +const CREDENTIAL_TOKENS: ReadonlySet = new Set([ + "password", + "secret", + "token", + "key", + "private", +]); + +const VERBS: ReadonlySet = new Set(verbVocabulary); + +const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const; +const MAX_COMMAND_WORDS = 4; +const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u; + +export class ApiCommandGenerationError extends Schema.TaggedError()( + "ApiCommandGenerationError", + { problems: Schema.Array(Schema.String) }, +) { + override get message(): string { + return this.problems.map((problem) => `- ${problem}`).join("\n"); + } +} + +interface DeriveInput { + /** The parsed OpenAPI document. */ + readonly spec: JsonObject; + readonly names: Readonly>; + readonly nouns: Readonly>; + /** Kebab-case operation id to the camelCase key of the typed client's `operationDefinitions`. */ + readonly operationIdMap: Readonly>; + /** Top-level command names owned by hand-written commands. */ + readonly handWrittenTopLevel: ReadonlySet; +} + +interface DeriveResult { + readonly entries: ReadonlyArray; + readonly schemas: Readonly>; + readonly problems: ReadonlyArray; +} + +interface Operation { + readonly id: string; + readonly method: ApiCommandEntry["method"]; + readonly path: string; + readonly node: JsonObject; + readonly pathItem: JsonObject; +} + +interface FlagShape { + readonly type: ApiCommandFlag["type"]; + readonly choices?: ReadonlyArray; + readonly repeatable: boolean; +} + +const asRecord = (value: unknown): JsonObject | undefined => + Predicate.isReadonlyObject(value) ? value : undefined; + +const asArray = (value: unknown): ReadonlyArray => (Array.isArray(value) ? value : []); + +const asString = (value: unknown): string | undefined => + typeof value === "string" ? value : undefined; + +const MAX_REF_DEPTH = 32; + +const lookupRef = (spec: JsonObject, ref: string): unknown => { + if (!ref.startsWith("#/")) return undefined; + let target: unknown = spec; + for (const segment of ref.slice(2).split("/")) { + target = asRecord(target)?.[segment.replaceAll("~1", "/").replaceAll("~0", "~")]; + } + return target; +}; + +/** Follows `$ref` chains within the document; unresolvable references yield `undefined`. */ +const resolve = (spec: JsonObject, value: unknown): unknown => { + let current = value; + for (let depth = 0; depth < MAX_REF_DEPTH; depth++) { + const ref = asString(asRecord(current)?.$ref); + if (ref === undefined) return current; + current = lookupRef(spec, ref); + } + return undefined; +}; + +const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"; +const DROPPED_KEYWORDS: ReadonlySet = new Set(["discriminator", "xml", "externalDocs"]); +const DATA_KEYWORDS: ReadonlySet = new Set([ + "type", + "format", + "title", + "description", + "default", + "enum", + "const", + "required", + "minimum", + "maximum", + "multipleOf", + "minLength", + "maxLength", + "pattern", + "minItems", + "maxItems", + "uniqueItems", + "minProperties", + "maxProperties", + "readOnly", + "writeOnly", + "deprecated", +]); +const SCHEMA_LIST_KEYWORDS = ["allOf", "anyOf", "oneOf"] as const; +const SCHEMA_MAP_KEYWORDS = ["properties", "patternProperties"] as const; + +/** + * Copies an OpenAPI 3.0 schema as JSON Schema 2020-12: every `$ref` is inlined and 3.0-only + * keywords are converted. A keyword with no conversion fails generation. + */ +const toJsonSchema = ( + spec: JsonObject, + node: unknown, + stack: ReadonlyArray, + fail: (reason: string) => void, +): unknown => { + const schema = asRecord(node); + if (schema === undefined) { + fail("schema is not an object"); + return {}; + } + const recurse = (child: unknown) => toJsonSchema(spec, child, stack, fail); + const ref = asString(schema.$ref); + if (ref !== undefined) { + if (stack.includes(ref)) { + fail(`unsupported in this runtime: recursive schema reference ${ref}`); + return {}; + } + const target = lookupRef(spec, ref); + if (target === undefined) { + fail(`schema reference ${ref} does not resolve`); + return {}; + } + return toJsonSchema(spec, target, [...stack, ref], fail); + } + + const out: Record = {}; + for (const [key, value] of Object.entries(schema)) { + if (DROPPED_KEYWORDS.has(key) || key === "nullable" || key === "example") continue; + if (key === "exclusiveMinimum" || key === "exclusiveMaximum") continue; + if (DATA_KEYWORDS.has(key) || key.startsWith("x-")) { + out[key] = value; + } else if (key === "items" || key === "not") { + out[key] = recurse(value); + } else if (key === "additionalProperties") { + out[key] = typeof value === "boolean" ? value : recurse(value); + } else if (SCHEMA_LIST_KEYWORDS.some((keyword) => keyword === key)) { + out[key] = asArray(value).map(recurse); + } else if (SCHEMA_MAP_KEYWORDS.some((keyword) => keyword === key)) { + out[key] = Object.fromEntries( + Object.entries(asRecord(value) ?? {}).map(([name, child]) => [name, recurse(child)]), + ); + } else { + fail( + `unsupported in this runtime: schema keyword "${key}" has no JSON Schema 2020-12 conversion`, + ); + } + } + + for (const [exclusive, bound] of [ + ["exclusiveMinimum", "minimum"], + ["exclusiveMaximum", "maximum"], + ] as const) { + const flag = schema[exclusive]; + if (typeof flag === "number") { + out[exclusive] = flag; + } else if (flag === true) { + if (typeof schema[bound] === "number") { + out[exclusive] = schema[bound]; + delete out[bound]; + } else { + fail(`schema sets ${exclusive}: true without ${bound}`); + } + } else if (flag !== undefined && flag !== false) { + fail(`schema keyword "${exclusive}" has an unsupported value`); + } + } + + if (schema.example !== undefined) { + if (out.examples !== undefined) fail('schema has both "example" and "examples"'); + out.examples = [schema.example]; + } + + if (schema.nullable === true) { + const type = out.type; + if (typeof type === "string") { + out.type = [type, "null"]; + } else if (Array.isArray(type)) { + out.type = [...type, "null"]; + } else { + return { anyOf: [out, { type: "null" }] }; + } + } else if (schema.nullable !== undefined && schema.nullable !== false) { + fail('schema keyword "nullable" has an unsupported value'); + } + return out; +}; + +const withDialect = (schema: unknown): unknown => ({ + $schema: JSON_SCHEMA_DIALECT, + ...asRecord(schema), +}); + +const escapePointer = (segment: string): string => + segment.replaceAll("~", "~0").replaceAll("/", "~1"); + +interface SuccessResponse { + readonly status: number; + readonly kind: "json" | "text" | "empty"; + readonly schema?: unknown; +} + +/** Classifies the 2xx responses; the first one by status code is the one commands report. */ +const classifySuccess = ( + spec: JsonObject, + operation: Operation, + fail: (reason: string) => void, +): SuccessResponse | undefined => { + const responses = asRecord(operation.node.responses) ?? {}; + const classified: Array = []; + for (const code of Object.keys(responses).sort()) { + if (!code.startsWith("2")) continue; + const status = Number(code); + if (!Number.isInteger(status)) { + fail(`unsupported in this runtime: response status "${code}"`); + continue; + } + const content = asRecord(asRecord(resolve(spec, responses[code]))?.content) ?? {}; + const types = Object.keys(content); + const json = types.find((type) => type === "application/json" || type.endsWith("+json")); + if (types.length === 0) { + classified.push({ status, kind: "empty" }); + } else if (json !== undefined) { + classified.push({ status, kind: "json", schema: asRecord(content[json])?.schema ?? {} }); + } else if (types.every((type) => type.startsWith("text/") && type !== "text/event-stream")) { + classified.push({ status, kind: "text" }); + } else { + fail( + `unsupported in this runtime: ${code} response is binary or streaming (${types.join(", ")})`, + ); + } + } + if (classified.length === 0 && !Object.keys(responses).some((code) => code.startsWith("2"))) { + fail("operation has no 2xx response"); + } + return classified[0]; +}; + +const kebabCase = (field: string): string => + field + .replace(/([a-z0-9])([A-Z])/gu, "$1-$2") + .replaceAll("_", "-") + .toLowerCase(); + +const credentialLike = (field: string): boolean => + kebabCase(field) + .split("-") + .some((token) => CREDENTIAL_TOKENS.has(token.replace(/s$/u, ""))); + +const describeScalar = ( + spec: JsonObject, + raw: unknown, +): Pick | undefined => { + const schema = asRecord(resolve(spec, raw)); + if (schema === undefined) return undefined; + if (["anyOf", "oneOf", "allOf", "not"].some((keyword) => keyword in schema)) return undefined; + const type = schema.type; + if (type !== "string" && type !== "integer" && type !== "number" && type !== "boolean") { + return undefined; + } + if (schema.enum === undefined) return { type }; + const choices = asArray(schema.enum); + if (type !== "string" || !choices.every((choice) => typeof choice === "string")) { + return undefined; + } + return { type, choices: choices.filter(Predicate.isString) }; +}; + +const describeFlagSchema = (spec: JsonObject, raw: unknown): FlagShape | undefined => { + const schema = asRecord(resolve(spec, raw)); + if (schema?.type === "array") { + const items = describeScalar(spec, schema.items); + return items === undefined ? undefined : { ...items, repeatable: true }; + } + const scalar = describeScalar(spec, raw); + return scalar === undefined ? undefined : { ...scalar, repeatable: false }; +}; + +const schemaDescription = (spec: JsonObject, raw: unknown): string | undefined => + asString(asRecord(resolve(spec, raw))?.description); + +const resolvePointer = (spec: JsonObject, root: unknown, pointer: string): unknown => { + if (!pointer.startsWith("/")) return undefined; + let current = resolve(spec, root); + for (const segment of pointer.slice(1).split("/")) { + const node = asRecord(current); + if (node === undefined) return undefined; + const property = asRecord(node.properties)?.[segment]; + if (property !== undefined) { + current = resolve(spec, property); + } else if (node.type === "array" && /^\d+$/u.test(segment) && node.items !== undefined) { + current = resolve(spec, node.items); + } else { + return undefined; + } + } + return current; +}; + +const successSchema = (spec: JsonObject, operation: Operation): unknown => { + const responses = asRecord(operation.node.responses) ?? {}; + for (const code of Object.keys(responses).sort()) { + if (!code.startsWith("2")) continue; + const response = asRecord(resolve(spec, responses[code])); + const media = asRecord(asRecord(response?.content)?.["application/json"]); + if (media?.schema !== undefined) return media.schema; + } + return undefined; +}; + +const collectOperations = (spec: JsonObject): ReadonlyMap => { + const operations = new Map(); + for (const [path, rawItem] of Object.entries(asRecord(spec.paths) ?? {})) { + const pathItem = asRecord(rawItem); + if (pathItem === undefined) continue; + for (const method of HTTP_METHODS) { + const node = asRecord(pathItem[method]); + const id = asString(node?.operationId); + if (node === undefined || id === undefined) continue; + operations.set(id, { + id, + method: method.toUpperCase() as ApiCommandEntry["method"], + path, + node, + pathItem, + }); + } + } + return operations; +}; + +const operationParameters = (spec: JsonObject, operation: Operation): ReadonlyArray => + [...asArray(operation.pathItem.parameters), ...asArray(operation.node.parameters)] + .map((raw) => asRecord(resolve(spec, raw))) + .filter(Predicate.isNotUndefined); + +/** Derives the generated commands for every name-table entry and collects every lint failure. */ +export function deriveApiCommands(input: DeriveInput): DeriveResult { + const { spec, names, nouns, operationIdMap, handWrittenTopLevel } = input; + const operations = collectOperations(spec); + const problems: Array = []; + const entries: Array = []; + const schemas: Record = {}; + const commandOwners = new Map(); + + for (const [operationId, name] of Object.entries(names)) { + const fail = (reason: string) => problems.push(`${operationId}: ${reason}`); + const operation = operations.get(operationId); + if (operation === undefined) { + fail("name table entry has no operation in the spec"); + continue; + } + const definition = operationIdMap[operationId]; + if (definition === undefined) { + fail("operation is missing from the typed client; regenerate @supabase/api"); + continue; + } + const failuresBefore = problems.length; + + const command = [...name.group.split("."), name.method]; + const segments = [...name.group.split("."), name.method]; + if (!segments.every((segment) => KEBAB.test(segment))) { + fail(`command "${command.join(" ")}" must be lowercase kebab-case words`); + } + if (command.length > MAX_COMMAND_WORDS) { + fail(`command "${command.join(" ")}" exceeds ${MAX_COMMAND_WORDS} words`); + } + if (name.customVerb !== true && !VERBS.has(name.method)) { + fail(`verb "${name.method}" is outside the vocabulary; use a listed verb or set customVerb`); + } + const noun = nouns[command[0] ?? ""]; + if (noun === undefined) { + fail(`noun "${command[0]}" is missing from the nouns table`); + } + const commandKey = command.join(" "); + const owner = commandOwners.get(commandKey); + if (owner !== undefined) fail(`command "${commandKey}" is already generated by ${owner}`); + commandOwners.set(commandKey, operationId); + if (handWrittenTopLevel.has(command[0] ?? "")) { + fail(`command "${commandKey}" collides with the hand-written "${command[0]}" command`); + } + + const stability = asString(operation.node["x-scalar-stability"]); + if (stability !== "experimental") { + fail( + "stable generated commands need the R8 baseline check, not implemented yet (x-scalar-stability must be experimental)", + ); + } + const summary = asString(operation.node.summary); + if (summary === undefined) fail("operation has no summary"); + + const renames = name.flags ?? {}; + const sensitive = name.sensitive ?? []; + const fields: Array<{ + readonly location: "query" | "body"; + readonly key: string; + readonly pointer?: string; + readonly shape: FlagShape; + readonly required: boolean; + readonly description: string | undefined; + }> = []; + + const pathBindings: Array = []; + for (const parameter of operationParameters(spec, operation)) { + const parameterName = asString(parameter.name) ?? ""; + switch (parameter.in) { + case "path": + if (parameterName === "ref") { + pathBindings.push({ location: "path", name: "ref", source: "target" }); + } else { + fail(`unsupported in this runtime: path parameter "${parameterName}"`); + } + break; + case "query": { + const shape = describeFlagSchema(spec, parameter.schema); + if (parameterName === "dry_run") { + fail('unsupported in this runtime: server-side "dry_run" parameter'); + } else if (shape === undefined || shape.repeatable) { + fail(`unsupported in this runtime: query parameter "${parameterName}" is not a scalar`); + } else { + fields.push({ + location: "query", + key: parameterName, + shape, + required: parameter.required === true, + description: + asString(parameter.description) ?? schemaDescription(spec, parameter.schema), + }); + } + break; + } + default: + fail(`unsupported in this runtime: ${String(parameter.in)} parameter "${parameterName}"`); + } + } + + let body: ApiCommandEntry["body"]; + let requestSchema: unknown; + const requestBody = asRecord(resolve(spec, operation.node.requestBody)); + if (requestBody !== undefined) { + const content = asRecord(requestBody.content) ?? {}; + const mediaTypes = Object.keys(content); + const bodySchema = asRecord(resolve(spec, asRecord(content["application/json"])?.schema)); + const properties = asRecord(bodySchema?.properties); + if ( + mediaTypes.length !== 1 || + bodySchema?.type !== "object" || + properties === undefined || + ["anyOf", "oneOf", "allOf"].some((keyword) => keyword in bodySchema) + ) { + fail( + `unsupported in this runtime: request body (${mediaTypes.join(", ") || "none"}) is not a JSON object`, + ); + } else { + const data = asRecord(resolve(spec, properties.data)); + const dataProperties = asRecord(data?.properties); + const typeEnum = asArray(asRecord(resolve(spec, dataProperties?.type))?.enum); + const attributes = asRecord(resolve(spec, dataProperties?.attributes)); + const envelopeType = asString(typeEnum[0]); + const isEnvelope = + Object.keys(properties).length === 1 && + typeEnum.length === 1 && + envelopeType !== undefined && + attributes?.type === "object" && + asRecord(attributes.properties) !== undefined; + const fieldProperties = isEnvelope ? asRecord(attributes?.properties) : properties; + const required = asArray(isEnvelope ? asRecord(attributes)?.required : bodySchema.required); + requestSchema = asRecord(content["application/json"])?.schema; + body = isEnvelope + ? { contentType: "application/json", kind: "json-envelope", type: envelopeType } + : { contentType: "application/json", kind: "json-object" }; + for (const [field, schema] of Object.entries(fieldProperties ?? {})) { + const shape = describeFlagSchema(spec, schema); + if (field === "dry_run") { + fail('unsupported in this runtime: server-side "dry_run" body field'); + } else if (shape === undefined) { + fail( + `unsupported in this runtime: body field "${field}" is not a scalar, string enum or array of scalars`, + ); + } else { + fields.push({ + location: "body", + key: field, + pointer: isEnvelope + ? `/data/attributes/${escapePointer(field)}` + : `/${escapePointer(field)}`, + shape, + required: required.includes(field), + description: schemaDescription(spec, schema), + }); + } + } + } + } + + for (const key of Object.keys(renames)) { + if (!fields.some((field) => field.key === key)) { + fail(`flags rename "${key}" matches no query parameter or body field`); + } + } + for (const key of sensitive) { + if (!fields.some((field) => field.location === "body" && field.key === key)) { + fail(`sensitive "${key}" matches no body field`); + } + } + + const flags: Array = []; + const bindings: Array = [...pathBindings]; + const seenNames = new Set(); + const seenKeys = new Set(); + for (const field of fields) { + const flagName = renames[field.key] ?? kebabCase(field.key); + if (!KEBAB.test(flagName)) fail(`flag "${flagName}" must be lowercase kebab-case`); + if (RESERVED_FLAGS.has(flagName)) { + fail( + `flag "--${flagName}" (from "${field.key}") collides with a reserved runtime flag; rename it`, + ); + } + if (seenNames.has(flagName)) { + fail(`flag "--${flagName}" (from "${field.key}") is produced twice; rename one`); + } + if (seenKeys.has(field.key)) { + fail(`"${field.key}" is both a query parameter and a body field`); + } + seenNames.add(flagName); + seenKeys.add(field.key); + const isSensitive = sensitive.includes(field.key); + if (field.location === "body" && credentialLike(field.key) && !isSensitive) { + fail( + `body field "${field.key}" looks like a credential; review it and list it under sensitive`, + ); + } + bindings.push( + field.location === "body" && field.pointer !== undefined + ? { + location: "body", + name: field.key, + pointer: field.pointer, + source: "flag", + flag: flagName, + } + : { location: "query", name: field.key, source: "flag", flag: flagName }, + ); + flags.push({ + name: flagName, + type: field.shape.type, + ...(field.shape.choices === undefined ? {} : { choices: field.shape.choices }), + repeatable: field.shape.repeatable, + required: field.required, + ...(isSensitive ? { sensitive: true as const } : {}), + ...(field.description === undefined ? {} : { description: field.description }), + }); + } + + if (name.wait !== undefined) { + lintWait({ spec, operations, names, operationId, operation, wait: name.wait, fail }); + } + + const response = classifySuccess(spec, operation, fail); + const schemaSet: ApiCommandSchemas | undefined = + response === undefined + ? undefined + : { + ...(requestSchema === undefined + ? {} + : { + request: { + contentType: "application/json" as const, + schema: withDialect(toJsonSchema(spec, requestSchema, [], fail)), + }, + }), + result: + response.kind === "empty" + ? withDialect({ type: "null" }) + : response.kind === "text" + ? withDialect({ type: "string" }) + : withDialect(toJsonSchema(spec, response.schema, [], fail)), + }; + + if (problems.length > failuresBefore || summary === undefined) continue; + if (response === undefined || schemaSet === undefined) continue; + schemas[operationId] = schemaSet; + const description = asString(operation.node.description)?.trim(); + entries.push({ + command, + operationId, + definition, + method: operation.method, + apiPath: operation.path, + summary, + ...(description === undefined || description === "" ? {} : { description }), + scope: "project", + readOnly: operation.method === "GET", + stability: "experimental", + ...(noun?.feature === undefined ? {} : { feature: noun.feature }), + ...(body === undefined ? {} : { body }), + response: { status: response.status, kind: response.kind }, + flags, + bindings, + ...(name.wait === undefined ? {} : { wait: name.wait }), + }); + } + + entries.sort((left, right) => + left.command.join(" ").localeCompare(right.command.join(" "), "en"), + ); + return { entries, schemas, problems }; +} + +function lintWait(input: { + readonly spec: JsonObject; + readonly operations: ReadonlyMap; + readonly names: Readonly>; + readonly operationId: string; + readonly operation: Operation; + readonly wait: ApiCommandWait; + readonly fail: (reason: string) => void; +}): void { + const { spec, operations, names, operation, wait, fail } = input; + const readOperation = operations.get(wait.read); + if (readOperation === undefined) { + fail(`wait.read "${wait.read}" has no operation in the spec`); + return; + } + if (names[wait.read] === undefined) { + fail(`wait.read "${wait.read}" is not in the name table, so it has no command`); + } + + const readParameters = operationParameters(spec, readOperation); + const queryNames = new Set( + readParameters.filter((parameter) => parameter.in === "query").map((p) => asString(p.name)), + ); + const changeResponse = successSchema(spec, operation); + for (const [parameter, pointer] of Object.entries(wait.params)) { + if (!queryNames.has(parameter)) { + fail(`wait.params "${parameter}" is not a query parameter of ${wait.read}`); + } + if (resolvePointer(spec, changeResponse, pointer) === undefined) { + fail(`wait.params "${parameter}" pointer "${pointer}" does not resolve in the response`); + } + } + for (const parameter of readParameters) { + const parameterName = asString(parameter.name); + if ( + parameter.required === true && + parameterName !== undefined && + parameterName !== "ref" && + wait.params[parameterName] === undefined + ) { + fail(`wait.params does not supply required parameter "${parameterName}" of ${wait.read}`); + } + } + + const readResponse = successSchema(spec, readOperation); + const status = resolvePointer(spec, readResponse, wait.status); + if (status === undefined) { + fail(`wait.status pointer "${wait.status}" does not resolve in the ${wait.read} response`); + } + if (wait.error !== undefined && resolvePointer(spec, readResponse, wait.error) === undefined) { + fail(`wait.error pointer "${wait.error}" does not resolve in the ${wait.read} response`); + } + if (wait.succeeded.length === 0) fail("wait.succeeded must list at least one status"); + const statusValues = asRecord(status)?.enum; + if (statusValues !== undefined) { + const allowed = asArray(statusValues); + for (const value of [...wait.succeeded, ...wait.failed]) { + if (!allowed.includes(value)) { + fail(`wait status "${value}" is not in the status enum of ${wait.read}`); + } + } + } +} diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts new file mode 100644 index 0000000000..2d3ef6fbe5 --- /dev/null +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -0,0 +1,262 @@ +import { describe, expect, it } from "@effect/vitest"; +import type { ApiCommandName } from "../src/commands/api/api-command-names.ts"; +import { deriveApiCommands } from "./api-command-derive.ts"; + +const DIALECT = "https://json-schema.org/draft/2020-12/schema"; + +const jsonResponse = (schema: unknown) => ({ + "200": { description: "ok", content: { "application/json": { schema } } }, +}); + +const operation = (overrides: Record) => ({ + summary: "Do the thing", + "x-scalar-stability": "experimental", + parameters: [{ name: "ref", in: "path", required: true, schema: { type: "string" } }], + responses: jsonResponse({ type: "object", properties: { ok: { type: "boolean" } } }), + ...overrides, +}); + +const envelope = (attributes: Record) => ({ + content: { + "application/json": { + schema: { + type: "object", + properties: { + data: { + type: "object", + properties: { + type: { type: "string", enum: ["thing"] }, + attributes: { + type: "object", + required: ["name"], + properties: { name: { type: "string" }, ...attributes }, + }, + }, + }, + }, + }, + }, + }, +}); + +const derive = (operations: Record, names: Record) => + deriveApiCommands({ + spec: { + paths: Object.fromEntries( + Object.entries(operations).map(([id, node]) => [ + `/v1/projects/{ref}/${id}`, + { post: { operationId: id, ...(node as object) } }, + ]), + ), + components: { schemas: { Tags: { type: "array", items: { type: "string" } } } }, + }, + names, + nouns: { thing: { description: "Manage things", feature: "things" } }, + operationIdMap: Object.fromEntries( + Object.keys(operations).map((id) => [id, "v2EnableWarehouse" as const]), + ), + handWrittenTopLevel: new Set(["db"]), + }); + +const create: ApiCommandName = { group: "thing", method: "create" }; + +describe("deriveApiCommands", () => { + it("binds envelope body fields by JSON pointer and the project ref to the target", () => { + const result = derive( + { + "create-thing": operation({ + requestBody: envelope({ tags: { type: "array", items: { type: "string" } } }), + }), + }, + { "create-thing": { ...create, flags: { tags: "tag" } } }, + ); + + expect(result.problems).toEqual([]); + const [entry] = result.entries; + expect(entry?.body).toEqual({ + contentType: "application/json", + kind: "json-envelope", + type: "thing", + }); + expect(entry?.response).toEqual({ status: 200, kind: "json" }); + expect(entry?.flags.map((flag) => [flag.name, flag.required, flag.repeatable])).toEqual([ + ["name", true, false], + ["tag", false, true], + ]); + expect(entry?.bindings).toEqual([ + { location: "path", name: "ref", source: "target" }, + { + location: "body", + name: "name", + pointer: "/data/attributes/name", + source: "flag", + flag: "name", + }, + { + location: "body", + name: "tags", + pointer: "/data/attributes/tags", + source: "flag", + flag: "tag", + }, + ]); + }); + + it("binds plain body fields at the body root and inlines referenced schemas", () => { + const result = derive( + { + "create-thing": operation({ + requestBody: { + content: { + "application/json": { + schema: { + type: "object", + properties: { display_name: { type: "string" } }, + }, + }, + }, + }, + responses: jsonResponse({ $ref: "#/components/schemas/Tags" }), + }), + }, + { "create-thing": create }, + ); + + expect(result.problems).toEqual([]); + expect(result.entries[0]?.body?.kind).toBe("json-object"); + expect(result.entries[0]?.bindings).toContainEqual({ + location: "body", + name: "display_name", + pointer: "/display_name", + source: "flag", + flag: "display-name", + }); + expect(result.schemas["create-thing"]?.result).toEqual({ + $schema: DIALECT, + type: "array", + items: { type: "string" }, + }); + }); + + it("turns a string enum query parameter into flag choices and an empty response into null", () => { + const result = derive( + { + "list-things": operation({ + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "sort", in: "query", schema: { type: "string", enum: ["asc", "desc"] } }, + ], + responses: { "204": { description: "none" } }, + }), + }, + { "list-things": { group: "thing", method: "list" } }, + ); + + expect(result.problems).toEqual([]); + expect(result.entries[0]?.flags[0]).toMatchObject({ name: "sort", choices: ["asc", "desc"] }); + expect(result.entries[0]?.response).toEqual({ status: 204, kind: "empty" }); + expect(result.schemas["list-things"]?.result).toEqual({ $schema: DIALECT, type: "null" }); + }); + + it.each([ + [ + "a nested object body field", + operation({ requestBody: envelope({ nested: { type: "object", properties: {} } }) }), + 'body field "nested"', + ], + [ + "a binary success response", + operation({ + responses: { "200": { description: "file", content: { "application/octet-stream": {} } } }, + }), + "binary or streaming", + ], + ])("rejects %s", (_label, node, message) => { + const result = derive({ "create-thing": node }, { "create-thing": create }); + + expect(result.entries).toEqual([]); + expect(result.problems.join("\n")).toContain(message); + }); + + it("rejects a body field that collides with a reserved runtime flag", () => { + const result = derive( + { "create-thing": operation({ requestBody: envelope({ wait: { type: "boolean" } }) }) }, + { "create-thing": create }, + ); + + expect(result.problems.join("\n")).toContain('"--wait"'); + }); + + it("rejects a wait pointer that does not resolve in the response", () => { + const result = derive( + { + "create-thing": operation({}), + "get-thing": operation({}), + }, + { + "create-thing": { + ...create, + wait: { + read: "get-thing", + params: {}, + status: "/data/attributes/missing", + succeeded: ["done"], + failed: [], + }, + }, + "get-thing": { group: "thing", method: "get" }, + }, + ); + + expect(result.problems.join("\n")).toContain('wait.status pointer "/data/attributes/missing"'); + }); + + it("converts OpenAPI 3.0 schema keywords to JSON Schema 2020-12", () => { + const result = derive( + { + "get-thing": operation({ + responses: jsonResponse({ + type: "object", + properties: { + name: { type: "string", nullable: true, example: "a" }, + count: { + type: "integer", + minimum: 0, + exclusiveMinimum: true, + maximum: 9, + exclusiveMaximum: false, + }, + any: { nullable: true, description: "free" }, + }, + discriminator: { propertyName: "name" }, + }), + }), + }, + { "get-thing": { group: "thing", method: "get" } }, + ); + + expect(result.problems).toEqual([]); + expect(result.schemas["get-thing"]?.result).toEqual({ + $schema: DIALECT, + type: "object", + properties: { + name: { type: ["string", "null"], examples: ["a"] }, + count: { type: "integer", exclusiveMinimum: 0, maximum: 9 }, + any: { anyOf: [{ description: "free" }, { type: "null" }] }, + }, + }); + }); + + it("rejects a schema keyword it cannot convert", () => { + const result = derive( + { + "get-thing": operation({ + responses: jsonResponse({ type: "string", contentMediaType: "x" }), + }), + }, + { "get-thing": { group: "thing", method: "get" } }, + ); + + expect(result.problems.join("\n")).toContain('keyword "contentMediaType"'); + }); +}); diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts new file mode 100644 index 0000000000..4e24eb7bb1 --- /dev/null +++ b/apps/cli/scripts/generate-api-commands.ts @@ -0,0 +1,133 @@ +import { BunRuntime, BunServices } from "@effect/platform-bun"; +import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; +import { ChildProcess, ChildProcessSpawner } from "effect/process"; +import { commandNames, nouns } from "../src/commands/api/api-command-names.ts"; +import { openApiOperationIdMap } from "@supabase/api/effect"; +import { ApiCommandGenerationError, deriveApiCommands } from "./api-command-derive.ts"; + +class ApiCommandFormatError extends Data.TaggedError("ApiCommandFormatError")<{ + readonly message: string; +}> {} + +class ApiCommandDriftError extends Data.TaggedError("ApiCommandDriftError")<{ + readonly files: ReadonlyArray; +}> { + override get message(): string { + return `Generated API command files are out of date: ${this.files.join(", ")}. Run \`pnpm --filter supabase run api-commands:generate\`.`; + } +} + +const HEADER = "// Generated by scripts/generate-api-commands.ts. Do not edit.\n"; +const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown, { space: 2 })); +const decodeJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown)); +const COMMAND_NAME = /Command\.make\(\s*"([^"]+)"/u; + +/** Top-level names of the hand-written commands, read from their `.command.ts` files. */ +const handWrittenTopLevel = Effect.fn("ApiCommands.scanHandWritten")(function* (cliRoot: string) { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const names = new Set(); + for (const base of ["src/commands", "src/commands/experimental"]) { + const root = path.join(cliRoot, base); + for (const entry of yield* fs.readDirectory(root)) { + if (entry === "api") continue; + const file = path.join(root, entry, `${entry}.command.ts`); + if (!(yield* fs.exists(file))) continue; + const match = COMMAND_NAME.exec(yield* fs.readFileString(file)); + if (match?.[1] !== undefined) names.add(match[1]); + } + } + yield* Effect.annotateCurrentSpan("handWritten.count", names.size); + return names; +}); + +/** Formats in memory with the repo's oxfmt config so the committed files match `pnpm fmt`. */ +const format = Effect.fn("ApiCommands.format")(function* ( + repoRoot: string, + filePath: string, + source: string, +) { + const spawner = yield* ChildProcessSpawner.ChildProcessSpawner; + const output = yield* spawner + .string( + ChildProcess.make( + "node_modules/.bin/oxfmt", + ["-c", ".oxfmtrc.json", "--stdin-filepath", filePath], + { + cwd: repoRoot, + stdin: Stream.make(new TextEncoder().encode(source)), + stderr: "inherit", + }, + ), + ) + .pipe( + Effect.mapError( + (error) => new ApiCommandFormatError({ message: `oxfmt failed: ${error.message}` }), + ), + ); + if (output.trim() === "") { + return yield* new ApiCommandFormatError({ + message: `oxfmt produced no output for ${filePath}`, + }); + } + return output; +}); + +const main = Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const check = process.argv.includes("--check"); + const cliRoot = path.resolve(import.meta.dir, ".."); + const repoRoot = path.resolve(cliRoot, "../.."); + const specPath = path.join(repoRoot, "packages/api/src/generated/openapi.json"); + const spec = yield* decodeJson(yield* fs.readFileString(specPath)); + if (!Predicate.isReadonlyObject(spec)) { + return yield* new ApiCommandGenerationError({ problems: ["openapi.json is not an object"] }); + } + + const { entries, schemas, problems } = deriveApiCommands({ + spec, + names: commandNames, + nouns, + operationIdMap: openApiOperationIdMap, + handWrittenTopLevel: yield* handWrittenTopLevel(cliRoot), + }); + if (problems.length > 0) return yield* new ApiCommandGenerationError({ problems }); + + const sortedSchemas = Object.fromEntries( + Object.entries(schemas).sort(([left], [right]) => left.localeCompare(right, "en")), + ); + const outputs = [ + { + relative: "src/commands/api/generated.ts", + source: `${HEADER}import type { ApiCommandEntry } from "./api-command.model.ts";\n\nexport const apiCommands = ${yield* encodeJson(entries)} as const satisfies readonly ApiCommandEntry[];\n`, + }, + { + relative: "src/commands/api/generated.schemas.ts", + source: `${HEADER}import type { ApiCommandSchemas } from "./api-command.model.ts";\n\nexport const apiCommandSchemas = ${yield* encodeJson(sortedSchemas)} as const satisfies Readonly>;\n`, + }, + ]; + + const stale: Array = []; + for (const output of outputs) { + const target = path.join(cliRoot, output.relative); + const formatted = yield* format(repoRoot, path.relative(repoRoot, target), output.source); + if (check) { + const current = (yield* fs.exists(target)) ? yield* fs.readFileString(target) : undefined; + if (current !== formatted) stale.push(output.relative); + } else { + yield* fs.makeDirectory(path.dirname(target), { recursive: true }); + yield* fs.writeFileString(target, formatted); + yield* Console.log(`Generated: ${output.relative}`); + } + } + if (stale.length > 0) return yield* new ApiCommandDriftError({ files: stale }); + if (check) yield* Console.log("Generated API command files are up to date."); + yield* Effect.annotateCurrentSpan("apiCommands.count", entries.length); +}); + +if (import.meta.main) { + BunRuntime.runMain( + main.pipe(Effect.withSpan("ApiCommands.generate"), Effect.provide(BunServices.layer)), + ); +} diff --git a/apps/cli/src/cli/boolean-flag-defaults.unit.test.ts b/apps/cli/src/cli/boolean-flag-defaults.unit.test.ts index c3e6284563..bf2e675948 100644 --- a/apps/cli/src/cli/boolean-flag-defaults.unit.test.ts +++ b/apps/cli/src/cli/boolean-flag-defaults.unit.test.ts @@ -54,9 +54,13 @@ describe("boolean flag wiring", () => { it("gives every boolean flag a default, so omitting it is not a parse error", () => { for (const stackBackend of ["legacy", "stack"] as const) { for (const computeEnabled of [false, true]) { - expect( - booleanFlagsRequiringAValue(rootCommandForFeatures({ stackBackend, computeEnabled })), - ).toEqual([]); + for (const warehouseEnabled of [false, true]) { + expect( + booleanFlagsRequiringAValue( + rootCommandForFeatures({ stackBackend, computeEnabled, warehouseEnabled }), + ), + ).toEqual([]); + } } } }); diff --git a/apps/cli/src/cli/main.ts b/apps/cli/src/cli/main.ts index 4e7a099358..a14b05cb2b 100644 --- a/apps/cli/src/cli/main.ts +++ b/apps/cli/src/cli/main.ts @@ -7,6 +7,7 @@ import { upgradeNoticeHook } from "../command-internal/upgrade-notice.ts"; import { analyticsLayerFor } from "../telemetry/analytics.layer.ts"; import { defaultCompleteDeps, tryComplete } from "./complete.ts"; import { resolveProjectStateSelection } from "../command-internal/stack-backend.ts"; +import { resolveWarehouseEnabled } from "../commands/api/warehouse-backend.ts"; import { resolveComputeEnabled } from "../commands/experimental/compute/compute-backend.ts"; import { cliConfigProviderLayer } from "../shared/config/cli-config-provider.layer.ts"; import { cliEntrypointForFeatures, rootCommandForFeatures } from "./root.ts"; @@ -28,12 +29,16 @@ const selectionExit = await Effect.runPromiseExit( args, cwd: process.cwd(), }); - return { projectState, stackBackend, computeEnabled }; + const warehouseEnabled = yield* resolveWarehouseEnabled({ + args, + cwd: process.cwd(), + }); + return { projectState, stackBackend, computeEnabled, warehouseEnabled }; }).pipe(Effect.provide(Layer.mergeAll(BunServices.layer, cliConfigProviderLayer))), ); const selectedFeatures = Exit.isSuccess(selectionExit) ? selectionExit.value - : ({ stackBackend: "legacy", computeEnabled: false } as const); + : ({ stackBackend: "legacy", computeEnabled: false, warehouseEnabled: false } as const); const { rootCommand: selectedRoot, agentDefaultOutputFormat } = cliEntrypointForFeatures( selectedFeatures, args, diff --git a/apps/cli/src/cli/root.ts b/apps/cli/src/cli/root.ts index 9e41bc8ff5..25c295ab0e 100644 --- a/apps/cli/src/cli/root.ts +++ b/apps/cli/src/cli/root.ts @@ -23,6 +23,7 @@ import { type ProjectStateMode, projectStateModeLayer, } from "../shared/config/project-state-mode.ts"; +import { apiCommandGroups } from "../commands/api/runtime.ts"; import { computeCommand } from "../commands/experimental/compute/compute.command.ts"; import { feedbackCommand } from "../commands/feedback/feedback.command.ts"; import { functionsCommand } from "../commands/functions/functions.command.ts"; @@ -147,6 +148,7 @@ interface RootCommandFeatures { readonly projectState?: Exit.Exit; readonly stackBackend?: StackBackend; readonly computeEnabled?: boolean; + readonly warehouseEnabled?: boolean; } /** Agents default to stream-json for Stack-backed `functions serve`, which rejects json. */ @@ -204,6 +206,7 @@ export const rootCommandForFeatures = (options: RootCommandFeatures = {}) => testCommand, unlinkCommand, vanitySubdomainsCommand, + ...apiCommandGroups(options.warehouseEnabled ? ["warehouse"] : []), whoamiCommand, ]), Command.provide( diff --git a/apps/cli/src/command-internal/command-errors/command-errors.annotation.ts b/apps/cli/src/command-internal/command-errors/command-errors.annotation.ts new file mode 100644 index 0000000000..941b41ac35 --- /dev/null +++ b/apps/cli/src/command-internal/command-errors/command-errors.annotation.ts @@ -0,0 +1,23 @@ +import { Context, Option } from "effect"; +import { Command } from "effect/cli"; + +/** The failure contract a command reports through: the `errors.standard` envelope or the legacy one. */ +export type CommandErrorsContract = "standard" | "legacy"; + +/** Context key under which a command's error contract is stored in `Command.annotations`. */ +export class CommandErrorsAnnotation extends Context.Service< + CommandErrorsAnnotation, + CommandErrorsContract +>()("supabase/CommandErrorsAnnotation") {} + +/** + * Reports the command's failures through the `errors.standard` envelope at the CLI error boundary; + * the handler propagates failures instead of rendering them. + */ +export const withStandardErrors = ( + self: Command.Command, +) => self.pipe(Command.annotate(CommandErrorsAnnotation, "standard")); + +/** A command without the standard marker reports through the legacy envelope. */ +export const readCommandErrorsContract = (command: Command.Command.Any): CommandErrorsContract => + Option.getOrElse(Context.getOption(command.annotations, CommandErrorsAnnotation), () => "legacy"); diff --git a/apps/cli/src/command-internal/command-permissions/command-permissions.unit.test.ts b/apps/cli/src/command-internal/command-permissions/command-permissions.unit.test.ts index 527cd603aa..ed4707ce11 100644 --- a/apps/cli/src/command-internal/command-permissions/command-permissions.unit.test.ts +++ b/apps/cli/src/command-internal/command-permissions/command-permissions.unit.test.ts @@ -43,6 +43,7 @@ const VARIANTS: ReadonlyArray<{ readonly name: string; readonly variant: Permiss projectState: Exit.succeed("stack"), stackBackend: "stack", computeEnabled: true, + warehouseEnabled: true, } satisfies Required>, }, ]; diff --git a/apps/cli/src/command-internal/command-permissions/fga-request-sets.unit.test.ts b/apps/cli/src/command-internal/command-permissions/fga-request-sets.unit.test.ts index 72371f570f..afe51a09ec 100644 --- a/apps/cli/src/command-internal/command-permissions/fga-request-sets.unit.test.ts +++ b/apps/cli/src/command-internal/command-permissions/fga-request-sets.unit.test.ts @@ -19,6 +19,7 @@ const VARIANTS: ReadonlyArray = [ projectState: Exit.succeed("stack"), stackBackend: "stack", computeEnabled: true, + warehouseEnabled: true, } satisfies Required>, ]; diff --git a/apps/cli/src/command-internal/command-permissions/help-section.tree.unit.test.ts b/apps/cli/src/command-internal/command-permissions/help-section.tree.unit.test.ts index a8b801f817..ed5cd96bff 100644 --- a/apps/cli/src/command-internal/command-permissions/help-section.tree.unit.test.ts +++ b/apps/cli/src/command-internal/command-permissions/help-section.tree.unit.test.ts @@ -21,6 +21,7 @@ const VARIANTS: ReadonlyArray<{ readonly name: string; readonly variant: Permiss projectState: Exit.succeed("stack"), stackBackend: "stack", computeEnabled: true, + warehouseEnabled: true, } satisfies Required>, }, ]; diff --git a/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts b/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts new file mode 100644 index 0000000000..8f9edee1ed --- /dev/null +++ b/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts @@ -0,0 +1,133 @@ +import { describe, expect, it } from "@effect/vitest"; +import { Effect, Schema } from "effect"; + +import { commandSurface, commandSurfaceEntry, walkCommandSurface } from "./command-surface.ts"; +import { rootCommandForFeatures } from "../../cli/root.ts"; + +const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); +const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); + +const surface = Effect.runPromise(commandSurface()); + +const titlesOf = (result: unknown): ReadonlyArray => + typeof result === "object" && result !== null && "oneOf" in result && Array.isArray(result.oneOf) + ? result.oneOf.map((branch) => + typeof branch === "object" && branch !== null && "title" in branch ? branch.title : null, + ) + : []; + +/** Source files a bundle of `entrypoint` pulls in, following relative imports only. */ +const bundledInputs = (entrypoint: string) => + Effect.promise(() => + Bun.build({ + entrypoints: [entrypoint], + target: "bun", + packages: "external", + metafile: true, + }), + ).pipe( + Effect.map((built) => { + expect(built.success).toBe(true); + return Object.keys(built.metafile?.inputs ?? {}); + }), + ); + +describe("command surface", () => { + it.effect("keeps warehouse commands out of the default surface", () => + Effect.gen(function* () { + const { commands } = yield* Effect.promise(() => surface); + expect(Object.keys(commands).filter((path) => path.startsWith("warehouse"))).toEqual([]); + expect(Object.keys(commands)).toContain("projects list"); + }), + ); + + it.effect("lists exactly the warehouse entries the feature adds", () => + Effect.gen(function* () { + const { variants } = yield* Effect.promise(() => surface); + expect(Object.keys(variants.warehouse)).toEqual([ + "warehouse", + "warehouse enable", + "warehouse status", + ]); + }), + ); + + it.effect("extracts one command from any mounted root, keyed like the full walk", () => + Effect.gen(function* () { + const root = rootCommandForFeatures({ warehouseEnabled: true }); + const walked = yield* walkCommandSurface(root); + const single = yield* commandSurfaceEntry(root, ["warehouse", "status"]); + expect(walked["warehouse status"]).toStrictEqual(single); + expect(Object.keys(walked)).toEqual(Object.keys(walked).toSorted()); + }), + ); + + it.effect("describes a generated command from its annotations and operation schemas", () => + Effect.gen(function* () { + const { variants } = yield* Effect.promise(() => surface); + const enable = variants.warehouse["warehouse enable"]; + expect(enable).toMatchObject({ + path: ["warehouse", "enable"], + target: { group: "hosted", consent: "no" }, + errors: "standard", + stage: { status: "experimental", gate: { kind: "feature", feature: "warehouse" } }, + api: { operationId: "v2-enable-warehouse", request: { contentType: "application/json" } }, + }); + expect(titlesOf(enable?.result)).toEqual(["response", "waited", "dryRun"]); + expect(enable?.flags["table"]).toMatchObject({ type: "string", variadic: true }); + expect(enable?.flags["dry-run"]).toMatchObject({ type: "boolean", default: false }); + expect(Object.keys(enable?.flags ?? {})).not.toContain("output"); + }), + ); + + it.effect("emits global flags once at the top level, not per command", () => + Effect.gen(function* () { + const { globalFlags, commands } = yield* Effect.promise(() => surface); + expect(globalFlags["yes"]).toMatchObject({ type: "boolean", default: false }); + expect(globalFlags["output-format"]).toMatchObject({ type: "choice" }); + expect(globalFlags["output-format"]?.choices).toContain("json"); + expect(Object.keys(commands["projects list"]?.flags ?? {})).not.toContain("yes"); + }), + ); + + it.effect("declares a waited result only for a command with a wait read", () => + Effect.gen(function* () { + const { variants } = yield* Effect.promise(() => surface); + expect(titlesOf(variants.warehouse["warehouse status"]?.result)).toEqual([ + "response", + "dryRun", + ]); + }), + ); + + it.effect("reports a hand-written command with the legacy error contract and no result", () => + Effect.gen(function* () { + const { commands } = yield* Effect.promise(() => surface); + expect(commands["projects list"]).toMatchObject({ + errors: "legacy", + result: "undeclared", + target: { group: "account" }, + }); + expect(commands["projects list"]).not.toHaveProperty("api"); + }), + ); + + it.effect("serializes to JSON and back unchanged", () => + Effect.gen(function* () { + const built = yield* Effect.promise(() => surface); + expect(decodeJson(encodeJson(built))).toStrictEqual(built); + }), + ); + + it.effect("loads the generated schemas only through the surface extraction", () => + Effect.gen(function* () { + const extraction = yield* bundledInputs( + "src/command-internal/command-surface/command-surface.ts", + ); + const runtime = yield* bundledInputs("src/main.ts"); + expect(extraction).toContain("src/commands/api/generated.schemas.ts"); + expect(runtime).not.toContain("src/commands/api/generated.schemas.ts"); + expect(runtime).not.toContain("src/command-internal/command-surface/command-surface.ts"); + }), + ); +}); diff --git a/apps/cli/src/command-internal/command-surface/command-surface.ts b/apps/cli/src/command-internal/command-surface/command-surface.ts new file mode 100644 index 0000000000..0bf44fe211 --- /dev/null +++ b/apps/cli/src/command-internal/command-surface/command-surface.ts @@ -0,0 +1,287 @@ +import { Effect, Option, Predicate, Schema } from "effect"; +import { Command, CommandSpec } from "effect/cli"; + +import { readApiCommand } from "../../commands/api/api-command.annotation.ts"; +import type { + ApiCommandBinding, + ApiCommandEntry, + ApiCommandSchemas, +} from "../../commands/api/api-command.model.ts"; +import { readCommandStage } from "../../commands/api/api-command-stage.ts"; +import type { CommandStage } from "../../commands/api/api-command-stage.ts"; +import { apiCommands } from "../../commands/api/generated.ts"; +import { rootCommandForFeatures } from "../../cli/root.ts"; +import { flattenSubcommands } from "../../docs/docs-introspection.ts"; +import { readCommandErrorsContract } from "../command-errors/command-errors.annotation.ts"; +import { readPermissions } from "../command-permissions/command-permissions.annotation.ts"; +import type { CommandPermissions } from "../command-permissions/model.ts"; +import { readTargetPolicy } from "../target/target-policy.ts"; +import type { TargetGroup } from "../target/target-policy.ts"; + +type JsonSchema = Readonly>; + +/** A positional argument as the parser accepts it. */ +interface SurfaceArgument { + readonly name: string; + readonly type: string; + readonly choices: readonly string[] | null; + readonly required: boolean; + readonly variadic: boolean; +} + +/** A flag as the parser accepts it; `env` is `null` because the parser carries no env name. */ +interface SurfaceFlag { + readonly name: string; + readonly aliases: readonly string[]; + readonly type: string; + readonly choices: readonly string[] | null; + readonly required: boolean; + readonly default: unknown; + readonly env: string | null; + readonly negatable: boolean; + readonly variadic: boolean; + readonly hidden: boolean; + readonly sensitive: boolean; +} + +/** What a generated command declares about the Management API operation it calls. */ +interface SurfaceApi { + readonly operationId: string; + /** Request body content type and JSON Schema, `null` when the operation sends none. */ + readonly request: { readonly contentType: string; readonly schema: unknown } | null; + readonly bindings: readonly ApiCommandBinding[]; +} + +/** One command or group of the mounted tree. Optional fields are omitted when the command declares nothing. */ +interface CommandSurfaceEntry { + readonly path: readonly string[]; + readonly aliases: readonly string[]; + readonly summary: string; + readonly unlisted: boolean; + readonly stage?: CommandStage; + readonly target?: { readonly group: TargetGroup; readonly consent: "none" | "no" | "yes" }; + readonly permissions?: CommandPermissions; + readonly arguments: readonly SurfaceArgument[]; + readonly flags: Readonly>; + /** `"undeclared"` for a hand-written command, else a JSON Schema `oneOf` of titled branches. */ + readonly result: "undeclared" | JsonSchema; + readonly errors: "standard" | "legacy"; + readonly api?: SurfaceApi; +} + +/** The default tree plus the entries each feature variant adds or changes. */ +interface CommandSurface { + readonly globalFlags: Readonly>; + readonly commands: Readonly>; + readonly variants: { + readonly warehouse: Readonly>; + }; +} + +type CommandRoot = Command.Command.Any; + +const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); + +const generatedEntries: readonly ApiCommandEntry[] = apiCommands; + +const dryRunSchema: JsonSchema = { + title: "dryRun", + type: "object", + properties: { + method: { type: "string" }, + path: { type: "string" }, + query: { type: "object" }, + body: {}, + }, + required: ["method", "path", "query", "body"], + additionalProperties: false, +}; + +// The schema table is the heavy generated module; importing it on demand keeps it out of the +// command runtime's module graph. +const loadSchemaTable = Effect.fn("CommandSurface.loadSchemas")(function* () { + const loaded = yield* Effect.promise(() => import("../../commands/api/generated.schemas.ts")); + const table: Readonly> = loaded.apiCommandSchemas; + return table; +}); + +const titled = (schema: unknown, title: string): JsonSchema => + Predicate.isObject(schema) ? { ...schema, title } : { title, allOf: [schema] }; + +const jsonOf = (value: unknown): unknown => + Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value) + ? value + : Array.isArray(value) + ? value.map(jsonOf) + : null; + +const choicesOf = (type: CommandSpec.Type): readonly string[] | null => + type._tag === "Choice" ? type.values : null; + +const defaultOf = (fallbacks: ReadonlyArray): unknown => { + const found = fallbacks.find((fallback) => fallback._tag === "Default"); + return found === undefined ? null : jsonOf(found.value); +}; + +const findCommand = (root: CommandRoot, path: readonly string[]): Option.Option => + path.reduce>( + (current, segment) => + Option.flatMap(current, (command) => + Option.fromUndefinedOr(flattenSubcommands(command).find((child) => child.name === segment)), + ), + Option.some(root), + ); + +const collectPaths = ( + command: CommandRoot, + prefix: readonly string[], +): ReadonlyArray => + flattenSubcommands(command).flatMap((child) => { + const path = [...prefix, child.name]; + return [path, ...collectPaths(child, path)]; + }); + +const sortedRecord = ( + entries: ReadonlyArray, +): Readonly> => + Object.fromEntries([...entries].toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))); + +const surfaceFlag = ( + flag: CommandSpec.Flag, + sensitiveFlags: ReadonlySet, +): readonly [string, SurfaceFlag] => [ + flag.name, + { + name: flag.name, + aliases: flag.aliases, + type: flag.typeName, + choices: choicesOf(flag.type), + required: flag.required, + default: defaultOf(flag.fallbacks), + env: null, + negatable: flag.negation !== undefined, + variadic: flag.variadic !== undefined, + hidden: flag.hidden, + sensitive: flag.type._tag === "Redacted" || sensitiveFlags.has(flag.name), + }, +]; + +/** The Global-scope flags every command accepts, keyed by name in sorted order. */ +const walkGlobalFlags = (root: CommandRoot) => { + const spec = CommandSpec.resolve(root, [root.name]); + return sortedRecord( + Option.isNone(spec) + ? [] + : spec.value.flags + .filter((flag) => flag.scope._tag === "Global") + .map((flag) => surfaceFlag(flag, new Set())), + ); +}; + +const apiSurface = Effect.fn("CommandSurface.api")(function* (command: CommandRoot) { + const descriptor = readApiCommand(command); + if (Option.isNone(descriptor)) return Option.none(); + const { operationId, bindings } = descriptor.value; + const generated = generatedEntries.find((entry) => entry.operationId === operationId); + if (generated === undefined) { + return yield* Effect.die(`no generated command declares operation "${operationId}"`); + } + const table = yield* loadSchemaTable(); + const schemas = table[operationId]; + if (schemas === undefined) { + return yield* Effect.die(`no generated schemas for operation "${operationId}"`); + } + const waitRead = generated.wait?.read; + const waitSchemas = waitRead === undefined ? undefined : table[waitRead]; + if (waitRead !== undefined && waitSchemas === undefined) { + return yield* Effect.die(`no generated schemas for operation "${waitRead}"`); + } + const branches = [ + titled(schemas.result, "response"), + ...(waitSchemas === undefined ? [] : [titled(waitSchemas.result, "waited")]), + dryRunSchema, + ]; + return Option.some({ + api: { + operationId, + request: + schemas.request === undefined + ? null + : { contentType: schemas.request.contentType, schema: schemas.request.schema }, + bindings, + } satisfies SurfaceApi, + result: { oneOf: branches } satisfies JsonSchema, + sensitiveFlags: new Set( + generated.flags.filter((flag) => flag.sensitive).map((flag) => flag.name), + ), + }); +}); + +/** Extracts the surface of the command at `path` (root name omitted) from the mounted tree `root`. */ +export const commandSurfaceEntry = Effect.fn("CommandSurface.entry")(function* ( + root: CommandRoot, + path: readonly string[], +) { + const command = findCommand(root, path); + const spec = CommandSpec.resolve(root, [root.name, ...path]); + if (Option.isNone(command) || Option.isNone(spec)) { + return yield* Effect.die(`unknown command path "${path.join(" ")}"`); + } + const api = yield* apiSurface(command.value); + const sensitiveFlags = Option.match(api, { + onNone: () => new Set(), + onSome: (found) => found.sensitiveFlags, + }); + const stage = readCommandStage(command.value); + const target = readTargetPolicy(command.value); + const permissions = readPermissions(command.value); + const flags = spec.value.flags + .filter((flag) => flag.scope._tag !== "Global") + .map((flag) => surfaceFlag(flag, sensitiveFlags)); + const entry: CommandSurfaceEntry = { + path, + aliases: spec.value.alias === undefined ? [] : [spec.value.alias], + summary: spec.value.shortDescription ?? spec.value.description ?? "", + unlisted: spec.value.unlisted, + ...(Option.isSome(stage) ? { stage: stage.value } : {}), + ...(Option.isSome(target) + ? { target: { group: target.value.group, consent: target.value.consent } } + : {}), + ...(Option.isSome(permissions) ? { permissions: permissions.value } : {}), + arguments: spec.value.arguments.map((argument) => ({ + name: argument.name, + type: argument.typeName, + choices: choicesOf(argument.type), + required: argument.required, + variadic: argument.variadic !== undefined, + })), + flags: sortedRecord(flags), + result: Option.isSome(api) ? api.value.result : "undeclared", + errors: readCommandErrorsContract(command.value), + ...(Option.isSome(api) ? { api: api.value.api } : {}), + }; + return entry; +}); + +/** Extracts every command and group of `root`, keyed by space-joined path in sorted order. */ +export const walkCommandSurface = Effect.fn("CommandSurface.walk")(function* (root: CommandRoot) { + const paths = collectPaths(root, []); + const entries = yield* Effect.forEach(paths, (path) => + Effect.map(commandSurfaceEntry(root, path), (entry) => [path.join(" "), entry] as const), + ); + return sortedRecord(entries); +}); + +/** The default command surface and, per feature, the entries that differ when the feature is on. */ +export const commandSurface = Effect.fn("CommandSurface.build")(function* () { + const base = yield* walkCommandSurface(rootCommandForFeatures()); + const warehouse = yield* walkCommandSurface(rootCommandForFeatures({ warehouseEnabled: true })); + const differing = Object.entries(warehouse).filter( + ([key, entry]) => key in base === false || encodeJson(base[key]) !== encodeJson(entry), + ); + return { + globalFlags: walkGlobalFlags(rootCommandForFeatures()), + commands: base, + variants: { warehouse: sortedRecord(differing) }, + } satisfies CommandSurface; +}); diff --git a/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts b/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts index 6193c832b2..c28303dee4 100644 --- a/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts +++ b/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts @@ -11,7 +11,7 @@ const srcDir = fileURLToPath(new URL("../..", import.meta.url)); const VARIANTS: ReadonlyArray = [ undefined, - { stackBackend: "stack", computeEnabled: true }, + { stackBackend: "stack", computeEnabled: true, warehouseEnabled: true }, ]; const consentDefaultByLeaf: ReadonlyMap = new Map( @@ -135,6 +135,7 @@ describe("hosted consent coverage", () => { "test db": "no", "vanity-subdomains activate": "no", "vanity-subdomains delete": "no", + "warehouse enable": "no", } `); }); diff --git a/apps/cli/src/command-internal/target/target-policy.unit.test.ts b/apps/cli/src/command-internal/target/target-policy.unit.test.ts index dbe7ef8626..0bae66a710 100644 --- a/apps/cli/src/command-internal/target/target-policy.unit.test.ts +++ b/apps/cli/src/command-internal/target/target-policy.unit.test.ts @@ -19,6 +19,7 @@ const VARIANTS: ReadonlyArray<{ readonly name: string; readonly variant: Permiss projectState: Exit.succeed("stack"), stackBackend: "stack", computeEnabled: true, + warehouseEnabled: true, } satisfies Required>, }, ]; diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts new file mode 100644 index 0000000000..fbc4df3791 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -0,0 +1,388 @@ +import { BunServices } from "@effect/platform-bun"; +import { describe, expect, it } from "@effect/vitest"; +import openApiSpec from "@supabase/api/openapi.json"; +import { Effect, Layer, Predicate, Schema, Stdio } from "effect"; +import { CliOutput, Command } from "effect/cli"; + +import { commandSurface } from "../../command-internal/command-surface/command-surface.ts"; +import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; +import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; +import { + VALID_REF, + VALID_TOKEN, + buildTestRuntime, + mockCommandPlatformApi, + mockCommandSettings, + useTempWorkdir, + withConfigEnv, +} from "../../../tests/helpers/command-mocks.ts"; +import { + mockOutput, + mockRuntimeInfo, + mockStdin, + mockTelemetryRuntime, + mockTty, +} from "../../../tests/helpers/mocks.ts"; +import { commandNames } from "./api-command-names.ts"; +import type { ApiCommandName } from "./api-command-names.ts"; +import { apiCommands } from "./generated.ts"; +import { apiCommandSchemas } from "./generated.schemas.ts"; +import { apiCommandGroups } from "./runtime.ts"; + +type Json = Readonly>; + +const asRecord = (value: unknown): Json => (Predicate.isObject(value) ? value : {}); +const asList = (value: unknown): ReadonlyArray => (Array.isArray(value) ? value : []); + +const spec = asRecord(openApiSpec); +const componentSchemas = asRecord(asRecord(spec["components"])["schemas"]); + +/** Follows `$ref`s to the component schema they name. */ +const resolveRef = (schema: unknown): Json => { + const node = asRecord(schema); + const ref = node["$ref"]; + return typeof ref === "string" + ? resolveRef(componentSchemas[ref.replace("#/components/schemas/", "")]) + : node; +}; + +const at = (schema: unknown, path: readonly string[]): Json => + path.reduce((node, key) => resolveRef(node[key]), resolveRef(schema)); + +interface SpecOperation { + readonly method: string; + readonly template: string; + readonly parameters: ReadonlyArray; + readonly requestSchema: Json | undefined; + readonly responseStatus: number; + readonly responseSchema: Json; +} + +const operationOf = (operationId: string): SpecOperation => { + for (const [template, item] of Object.entries(asRecord(spec["paths"]))) { + for (const [method, raw] of Object.entries(asRecord(item))) { + const operation = asRecord(raw); + if (operation["operationId"] !== operationId) continue; + const success = Object.entries(asRecord(operation["responses"])).find(([status]) => + status.startsWith("2"), + ); + if (success === undefined) throw new Error(`${operationId} has no 2xx response`); + const json = (content: unknown) => asRecord(asRecord(content)["application/json"])["schema"]; + const request = json(asRecord(operation["requestBody"])["content"]); + return { + method: method.toUpperCase(), + template, + parameters: asList(operation["parameters"]).map(asRecord), + requestSchema: request === undefined ? undefined : resolveRef(request), + responseStatus: Number(success[0]), + responseSchema: resolveRef(json(asRecord(success[1])["content"])), + }; + } + } + throw new Error(`${operationId} is not in openapi.json`); +}; + +/** The JSON Schema types of a node, with OpenAPI 3.0 `nullable` folded in as a `null` type. */ +const typesOf = (node: Json): ReadonlyArray => { + const declared = node["type"]; + const types = (Array.isArray(declared) ? declared : declared === undefined ? [] : [declared]).map( + String, + ); + return (node["nullable"] === true ? [...types, "null"] : types) + .filter((type, index, all) => all.indexOf(type) === index) + .toSorted((a, b) => a.localeCompare(b)); +}; + +/** A structural fingerprint of a schema that ignores descriptions, examples and titles. */ +const shapeOf = (schema: unknown): unknown => { + const node = resolveRef(schema); + return { + types: typesOf(node), + enum: node["enum"] ?? null, + properties: Object.fromEntries( + Object.entries(asRecord(node["properties"])).map(([key, value]) => [key, shapeOf(value)]), + ), + required: asList(node["required"]) + .map(String) + .toSorted((a, b) => a.localeCompare(b)), + items: node["items"] === undefined ? null : shapeOf(node["items"]), + }; +}; + +const PATTERN_SAMPLES: Readonly> = { + "^[a-f0-9]{64}$": "ab".repeat(32), + "^[a-z]+$": "zyxwvutsrqponmlkjihg", +}; + +/** A value the field's schema accepts; an unknown string pattern fails loudly instead of guessing. */ +const sampleOf = (schema: unknown): unknown => { + const node = resolveRef(schema); + const choices = asList(node["enum"]); + if (choices.length > 0) return choices[0]; + switch (node["type"]) { + case "boolean": + return true; + case "integer": + case "number": + return 1; + case "array": + return [sampleOf(node["items"]), `${String(sampleOf(node["items"]))}-2`]; + case "string": { + const pattern = node["pattern"]; + if (pattern === undefined) return "sample"; + const sample = typeof pattern === "string" ? PATTERN_SAMPLES[pattern] : undefined; + if (sample === undefined) throw new Error(`no sample for string pattern ${String(pattern)}`); + return sample; + } + default: + throw new Error(`no sample for schema type ${String(node["type"])}`); + } +}; + +interface Input { + readonly location: "query" | "body"; + readonly field: string; + readonly flag: string; + readonly pointer: string | undefined; + readonly required: boolean; + readonly sample: unknown; +} + +const names: Readonly> = commandNames; + +/** Every non-path input of the operation, read from openapi.json and the command name table. */ +const inputsOf = (operationId: string, operation: SpecOperation): ReadonlyArray => { + const flagFor = (field: string) => + names[operationId]?.flags?.[field] ?? field.replaceAll("_", "-"); + const queries = operation.parameters + .filter((parameter) => parameter["in"] === "query") + .map((parameter): Input => { + const field = String(parameter["name"]); + return { + location: "query", + field, + flag: flagFor(field), + pointer: undefined, + required: parameter["required"] === true, + sample: sampleOf(parameter["schema"]), + }; + }); + if (operation.requestSchema === undefined) return queries; + const attributes = at(operation.requestSchema, [ + "properties", + "data", + "properties", + "attributes", + ]); + const envelope = Object.keys(attributes).length > 0; + const container = envelope ? attributes : operation.requestSchema; + const required = asList(container["required"]); + const fields = Object.entries(asRecord(container["properties"])).map( + ([field, schema]): Input => ({ + location: "body", + field, + flag: flagFor(field), + pointer: `${envelope ? "/data/attributes" : ""}/${field}`, + required: required.includes(field), + sample: sampleOf(schema), + }), + ); + return [...queries, ...fields]; +}; + +const argvOf = (inputs: ReadonlyArray): ReadonlyArray => + inputs.flatMap((input) => + Array.isArray(input.sample) + ? input.sample.flatMap((item) => [`--${input.flag}`, String(item)]) + : [`--${input.flag}`, String(input.sample)], + ); + +const expectedQuery = (inputs: ReadonlyArray): Readonly> => + Object.fromEntries( + inputs + .filter((input) => input.location === "query") + .map((input) => [input.field, String(input.sample)]), + ); + +const expectedBody = (operation: SpecOperation, inputs: ReadonlyArray): unknown => { + if (operation.requestSchema === undefined) return undefined; + const attributes = Object.fromEntries( + inputs.filter((input) => input.location === "body").map((input) => [input.field, input.sample]), + ); + const type = asList( + at(operation.requestSchema, ["properties", "data", "properties", "type"])["enum"], + )[0]; + return { data: { type, attributes } }; +}; + +const tempRoot = useTempWorkdir("supabase-api-bindings-int-"); + +const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); + +interface Sent { + readonly method: string; + readonly path: string; + readonly search: string; + readonly body: unknown; +} + +const TARGET_LOOKUP_PATH = `/v1/projects/${VALID_REF}`; + +/** Replaces `globalThis.fetch` while `body` runs and answers every call with `status` and `{}`. */ +const withApi = (status: number, sent: Array) => { + const stub = (input: string | URL | Request, init?: RequestInit): Promise => { + const request = input instanceof Request ? input : new Request(String(input), init); + const url = new URL(request.url); + if (url.pathname === TARGET_LOOKUP_PATH) { + return Promise.resolve( + new Response("{}", { status: 200, headers: { "content-type": "application/json" } }), + ); + } + return request.text().then((text) => { + sent.push({ + method: request.method, + path: url.pathname, + search: url.search.replace(/^\?/, ""), + body: text === "" ? undefined : decodeJson(text), + }); + return new Response("{}", { status, headers: { "content-type": "application/json" } }); + }); + }; + return (body: Effect.Effect) => + Effect.acquireUseRelease( + Effect.sync(() => { + const previous = globalThis.fetch; + globalThis.fetch = Object.assign(stub, { preconnect: previous.preconnect }); + return previous; + }), + () => body, + (previous) => + Effect.sync(() => { + globalThis.fetch = previous; + }), + ); +}; + +const warehouseRoot = Command.make("supabase").pipe( + Command.withSubcommands(apiCommandGroups(["warehouse"])), + Command.withGlobalFlags(GLOBAL_FLAGS), +); + +/** Runs the real parser and generated leaf for `path` and `argv`; only `fetch` is stubbed. */ +const send = (path: ReadonlyArray, argv: ReadonlyArray, status: number) => { + const args = [...path, ...argv, `--remote=${VALID_REF}`, "--yes"]; + const sent: Array = []; + const layer = Layer.mergeAll( + buildTestRuntime({ + out: mockOutput({ format: "text" }), + api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), + cliSettings: mockCommandSettings({ workdir: tempRoot.current }), + tty: mockTty({ stdinIsTty: false, stdoutIsTty: false }), + stdin: mockStdin(false), + cliArgs: args, + }), + BunServices.layer, + CliOutput.layer(textCliOutputFormatter()), + Layer.succeed(ExperimentalFlag, false), + mockTelemetryRuntime({ configDir: tempRoot.current }), + mockRuntimeInfo({ cwd: tempRoot.current, homeDir: tempRoot.current }), + Stdio.layerTest({ args: Effect.succeed(args) }), + ); + return withConfigEnv( + { SUPABASE_ACCESS_TOKEN: VALID_TOKEN, SUPABASE_NO_KEYRING: "1" }, + Command.runWith(warehouseRoot, { version: "0.0.0-test" })(args), + ).pipe( + withApi(status, sent), + Effect.provide(layer), + Effect.map(() => sent), + ); +}; + +const surface = await Effect.runPromise(commandSurface()); +const rows = [...Object.values(surface.commands), ...Object.values(surface.variants.warehouse)] + .flatMap((entry) => (entry.api === undefined ? [] : [{ ...entry, api: entry.api }])) + .toSorted((a, b) => a.api.operationId.localeCompare(b.api.operationId)); + +const bindingKey = (binding: { readonly location: string; readonly name: string }): string => + JSON.stringify(binding); + +describe("generated command bindings", () => { + it("covers every generated command", () => { + expect(rows.map((row) => row.api.operationId)).toEqual( + apiCommands.map((entry) => entry.operationId).toSorted(), + ); + }); + + for (const row of rows) { + const { operationId } = row.api; + const operation = operationOf(operationId); + const inputs = inputsOf(operationId, operation); + const expectedPath = operation.template.replace("{ref}", VALID_REF); + + describe(row.path.join(" "), () => { + it("binds the path reference and every other input to the spec's location", () => { + expect(operation.template.match(/\{[^}]+\}/g)).toEqual(["{ref}"]); + const expected = [ + { location: "path", name: "ref", source: "target" }, + ...inputs.map((input) => + input.location === "query" + ? { location: "query", name: input.field, source: "flag", flag: input.flag } + : { + location: "body", + name: input.field, + pointer: input.pointer, + source: "flag", + flag: input.flag, + }, + ), + ]; + expect(row.api.bindings.map(bindingKey).toSorted()).toEqual( + expected.map(bindingKey).toSorted(), + ); + }); + + it.effect("sends every input at its binding", () => + Effect.gen(function* () { + const requests = yield* send(row.path, argvOf(inputs), operation.responseStatus); + expect(requests).toHaveLength(1); + const [request] = requests; + expect(request?.method).toBe(operation.method); + expect(request?.path).toBe(expectedPath); + expect(Object.fromEntries(new URLSearchParams(request?.search))).toEqual( + expectedQuery(inputs), + ); + expect(request?.body).toEqual(expectedBody(operation, inputs)); + }), + ); + + it.effect("sends only the inputs the spec requires when no other flag is given", () => + Effect.gen(function* () { + const required = inputs.filter((input) => input.required); + const requests = yield* send(row.path, argvOf(required), operation.responseStatus); + expect(requests).toHaveLength(1); + const [request] = requests; + expect(Object.fromEntries(new URLSearchParams(request?.search))).toEqual( + expectedQuery(required), + ); + expect(request?.body).toEqual(expectedBody(operation, required)); + }), + ); + + it("declares the operation's success response as the response result", () => { + expect(Object.keys(apiCommandSchemas)).toContain(operationId); + const branches = asList(asRecord(row.result)["oneOf"]).map(asRecord); + expect(shapeOf(branches.find((branch) => branch["title"] === "response"))).toEqual( + shapeOf(operation.responseSchema), + ); + const waitRead = names[operationId]?.wait?.read; + const waited = branches.find((branch) => branch["title"] === "waited"); + if (waitRead === undefined) { + expect(waited).toBeUndefined(); + return; + } + expect(Object.keys(apiCommandSchemas)).toContain(waitRead); + expect(shapeOf(waited)).toEqual(shapeOf(operationOf(waitRead).responseSchema)); + }); + }); + } +}); diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts new file mode 100644 index 0000000000..f0a105a848 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -0,0 +1,301 @@ +import type { OperationId, OperationInput } from "@supabase/api/effect"; +import { operationPermissions } from "@supabase/api/permissions"; +import { Duration, Effect, Option, Predicate, Ref, Schedule, Schema } from "effect"; +import * as HttpClientError from "effect/http/HttpClientError"; +import * as Headers from "effect/http/Headers"; +import type * as HttpClientResponse from "effect/http/HttpClientResponse"; + +import { CommandPlatformApi } from "../../auth/command-platform-api.service.ts"; +import { sanitizeErrorBody } from "../../command-internal/http-errors.ts"; +import { encodeStructYaml, shapeAny } from "../../command-internal/struct-output.encoders.ts"; +import { Output } from "../../shared/output/output.service.ts"; +import { readPointer } from "./api-command-pointer.ts"; +import { decodeInput, definitionOf } from "./api-command-request.ts"; +import { + ApiCommandOperationFailedError, + ApiCommandStatusError, + ApiCommandWaitTimeoutError, +} from "./api-command.errors.ts"; +import type { ApiCommandEntry, ApiCommandWait } from "./api-command.model.ts"; +import { apiCommands } from "./generated.ts"; + +const POLL_BASE_DELAY = "1 second"; +const POLL_MAX_DELAY_MILLIS = 10_000; + +const decodeJsonText = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown)); + +const textDecoder = new TextDecoder(); +const encodeJsonValue = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); + +/** How a generated command prints its result: the API's JSON untouched, or the same document as YAML. */ +export type ApiOutputFormat = "json" | "yaml"; + +/** Writes `value` as one document in `format`. */ +export const writeDocument = Effect.fnUntraced(function* (value: unknown, format: ApiOutputFormat) { + const output = yield* Output; + return yield* output.raw( + format === "yaml" ? encodeStructYaml(value, shapeAny) : `${encodeJsonValue(value)}\n`, + ); +}); + +const stringField = (source: unknown, key: string): string | undefined => { + if (!Predicate.isObject(source)) return undefined; + const value: unknown = Reflect.get(source, key); + return typeof value === "string" ? value : undefined; +}; + +/** Reads a response body; a body that cannot be read is a transport failure. */ +const readBytes = (response: HttpClientResponse.HttpClientResponse) => + response.arrayBuffer.pipe( + Effect.map((buffer) => new Uint8Array(buffer)), + Effect.mapError( + (cause) => + new HttpClientError.HttpClientError({ + reason: new HttpClientError.TransportError({ request: response.request, cause }), + }), + ), + ); + +const permissionHint = (operationId: string): string | undefined => { + const sets = operationPermissions[operationId]?.fga ?? []; + if (sets.length === 0) return undefined; + const alternatives = sets.map((set) => set.join(" + ")).join(" or "); + return `Your token needs the permissions: ${alternatives}.`; +}; + +const statusHint = (operationId: string, status: number): string | undefined => + status === 401 + ? "Run `supabase login`" + : status === 403 + ? permissionHint(operationId) + : undefined; + +/** + * The error fields of a Management API failure body: v2 nests `{code, message, description?}` + * under `error`, v1 puts `message` (and sometimes `code`, `hint`) at the top level. + */ +const apiErrorFields = (body: unknown) => { + const nested = Predicate.isObject(body) ? Reflect.get(body, "error") : undefined; + const source = Predicate.isObject(nested) ? nested : body; + const message = stringField(source, "message"); + const description = stringField(source, "description"); + return { + message: + message === undefined || message === "" + ? description + : description === undefined || description === "" + ? message + : `${message}: ${description}`, + apiCode: stringField(source, "code"), + hint: stringField(source, "hint"), + }; +}; + +const statusError = Effect.fnUntraced(function* ( + operationId: string, + response: HttpClientResponse.HttpClientResponse, +) { + const text = textDecoder.decode( + yield* readBytes(response).pipe(Effect.orElseSucceed(() => new Uint8Array())), + ); + const fields = apiErrorFields(Option.getOrUndefined(decodeJsonText(text))); + return yield* new ApiCommandStatusError({ + status: response.status, + message: + fields.message === undefined || fields.message === "" + ? `Unexpected status ${response.status}` + : sanitizeErrorBody(fields.message), + apiCode: fields.apiCode, + hint: fields.hint ?? statusHint(operationId, response.status), + }); +}); + +/** A 2xx response of an executed operation, with its body read once. */ +export interface ApiCommandResponse { + readonly status: number; + readonly bytes: Uint8Array; + readonly headers: Headers.Headers; +} + +/** + * Sends the decoded input of `entry` and returns the 2xx response; any other status fails with + * the API's own message, code and hint. + */ +export const sendApiRequest = Effect.fnUntraced(function* ( + entry: ApiCommandEntry, + decoded: OperationInput, +) { + const api = yield* CommandPlatformApi; + const response = yield* api.executeRaw(definitionOf(entry), decoded); + if (response.status < 200 || response.status >= 300) { + return yield* statusError(entry.operationId, response); + } + const result: ApiCommandResponse = { + status: response.status, + bytes: yield* readBytes(response), + headers: response.headers, + }; + return result; +}); + +const parseResponse = (response: ApiCommandResponse): unknown => + Option.getOrUndefined(decodeJsonText(textDecoder.decode(response.bytes))); + +/** + * Writes a success response. `json` passes JSON bytes through untouched, prints text as a JSON + * string and an empty body as `null`; `yaml` encodes that same document. + */ +export const writeApiResponse = Effect.fnUntraced(function* ( + entry: ApiCommandEntry, + response: ApiCommandResponse, + format: ApiOutputFormat, +) { + const hasBody = response.bytes.length > 0; + const text = textDecoder.decode(response.bytes); + if (format === "json" && entry.response.kind === "json" && hasBody) { + const output = yield* Output; + return yield* output.rawBytes(response.bytes); + } + const document = + !hasBody || entry.response.kind === "empty" + ? null + : entry.response.kind === "text" + ? text + : Option.getOrElse(decodeJsonText(text), () => text); + return yield* writeDocument(document, format); +}); + +interface WaitInput { + readonly wait: ApiCommandWait; + /** The operation that produced `changed`. */ + readonly changedEntry: ApiCommandEntry; + readonly ref: string; + /** The change response the read parameters are taken from. */ + readonly changed: ApiCommandResponse; + readonly timeoutMillis: number; +} + +export interface PollOutcome { + readonly done: boolean; + readonly response: ApiCommandResponse; +} + +/** The delay a `Retry-After` header asks for, as delta-seconds or an HTTP date. */ +const retryAfterMillis = (headers: Headers.Headers, now: number): number | undefined => { + const value = Option.getOrUndefined(Headers.get(headers, "retry-after"))?.trim(); + if (value === undefined || value === "") return undefined; + if (/^\d+$/u.test(value)) return Number(value) * 1000; + const date = Date.parse(value); + return Number.isNaN(date) ? undefined : Math.max(0, date - now); +}; + +/** Backoff from 1s doubling to a 10s cap; a longer `Retry-After` on the last read wins. */ +export const pollSchedule = Schedule.exponential(POLL_BASE_DELAY).pipe( + Schedule.setInputType(), + Schedule.modifyDelay(({ input, duration, now }) => + Effect.succeed( + Math.max( + Math.min(Duration.toMillis(duration), POLL_MAX_DELAY_MILLIS), + retryAfterMillis(input.response.headers, now) ?? 0, + ), + ), + ), +); + +const failureReason = (reason: unknown): string | undefined => { + if (reason === undefined || reason === null || reason === "") return undefined; + return sanitizeErrorBody(typeof reason === "string" ? reason : encodeJsonValue(reason)); +}; + +const classify = (wait: ApiCommandWait, response: ApiCommandResponse, statusHint: string) => { + const body = parseResponse(response); + const status = readPointer(body, wait.status); + const reason = + wait.error === undefined ? undefined : failureReason(readPointer(body, wait.error)); + const failedStatus = typeof status === "string" && wait.failed.includes(status); + if (reason !== undefined || failedStatus) { + return Effect.fail( + new ApiCommandOperationFailedError({ + status: typeof status === "string" ? status : "unknown", + message: reason ?? `The operation failed with status "${String(status)}".`, + hint: statusHint, + }), + ); + } + const done = typeof status === "string" && wait.succeeded.includes(status); + return Effect.succeed({ done, response }); +}; + +/** The command that re-reads the operation's state, built from the values the wait polls with. */ +const statusCommand = ( + readEntry: ApiCommandEntry, + ref: string, + readInput: Readonly>, +): string => { + const flags = readEntry.bindings.flatMap((binding) => { + if (binding.source !== "flag") return []; + const value = readInput[binding.name]; + return value === undefined ? [] : [`--${binding.flag} ${String(value)}`]; + }); + return ["supabase", ...readEntry.command, ...flags, `--remote=${ref}`].join(" "); +}; + +/** + * Polls the read operation until it reports a terminal status and returns the final response with + * the operation that produced it. A failed status or failure reason, a timeout, or any non-2xx + * read (a 409 included) ends the wait with an error. A change response that lacks a value the + * read needs is returned as it is, without waiting. + */ +export const waitForOperation = Effect.fn("api-command.wait")(function* (input: WaitInput) { + const { wait } = input; + const readEntry = apiCommands.find((candidate) => candidate.operationId === wait.read); + if (readEntry === undefined) { + return yield* Effect.die(new Error(`Unknown wait read operation ${wait.read}`)); + } + const changedBody = parseResponse(input.changed); + const readInput: Record = { ref: input.ref }; + for (const [param, pointer] of Object.entries(wait.params)) { + const value = readPointer(changedBody, pointer); + if (value === undefined) { + yield* Effect.annotateCurrentSpan({ "wait.outcome": "skipped" }); + return { entry: input.changedEntry, response: input.changed }; + } + readInput[param] = value; + } + const decoded = yield* decodeInput(readEntry, readInput); + const hint = `Check it with \`${statusCommand(readEntry, input.ref, readInput)}\`.`; + const attempts = yield* Ref.make(0); + + const poll = Ref.update(attempts, (count) => count + 1).pipe( + Effect.andThen(sendApiRequest(readEntry, decoded)), + Effect.flatMap((response) => classify(wait, response, hint)), + Effect.withTracerEnabled(false), + ); + + const outcome = yield* poll.pipe( + Effect.repeat({ schedule: pollSchedule, until: (result) => result.done }), + Effect.timeoutOrElse({ + duration: input.timeoutMillis, + orElse: () => + Effect.fail( + new ApiCommandWaitTimeoutError({ + message: `Timed out waiting for ${wait.read} to report ${wait.succeeded.join(" or ")}.`, + timeoutMillis: input.timeoutMillis, + hint, + }), + ), + }), + Effect.tapError((error) => + Ref.get(attempts).pipe( + Effect.flatMap((count) => + Effect.annotateCurrentSpan({ "wait.attempts": count, "wait.outcome": error._tag }), + ), + ), + ), + ); + yield* Effect.annotateCurrentSpan({ + "wait.attempts": yield* Ref.get(attempts), + "wait.outcome": "succeeded", + }); + return { entry: readEntry, response: outcome.response }; +}); diff --git a/apps/cli/src/commands/api/api-command-execute.unit.test.ts b/apps/cli/src/commands/api/api-command-execute.unit.test.ts new file mode 100644 index 0000000000..1f1f1bfdc9 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-execute.unit.test.ts @@ -0,0 +1,60 @@ +import { describe, expect, it } from "@effect/vitest"; +import { Effect, Fiber } from "effect"; +import * as Headers from "effect/http/Headers"; +import * as TestClock from "effect/testing/TestClock"; + +import { pollSchedule, type PollOutcome } from "./api-command-execute.ts"; + +const outcome = (headers: Record = {}): PollOutcome => ({ + done: false, + response: { status: 200, bytes: new Uint8Array(), headers: Headers.fromInput(headers) }, +}); + +/** Seconds, on the controlled clock, at which each of `reads` polls runs. */ +const pollTimes = (reads: ReadonlyArray) => + Effect.gen(function* () { + const clock = yield* TestClock.testClockWith(Effect.succeed); + const times: Array = []; + const fiber = yield* Effect.sync(() => { + const read = reads[Math.min(times.length, reads.length - 1)] ?? outcome(); + times.push(clock.currentTimeMillisUnsafe() / 1000); + return read; + }).pipe( + Effect.repeat({ schedule: pollSchedule, times: reads.length - 1 }), + Effect.forkChild({ startImmediately: true }), + ); + for (let second = 0; second < 60; second += 1) yield* TestClock.adjust("1 second"); + yield* Fiber.join(fiber); + return times; + }); + +describe("poll schedule", () => { + it.effect("backs off from 1s doubling to a 10s cap", () => + Effect.gen(function* () { + const times = yield* pollTimes(Array.from({ length: 7 }, () => outcome())); + expect(times).toEqual([0, 1, 3, 7, 15, 25, 35]); + }), + ); + + it.effect("waits for a longer Retry-After given in seconds", () => + Effect.gen(function* () { + const times = yield* pollTimes([outcome({ "retry-after": "5" }), outcome()]); + expect(times).toEqual([0, 5]); + }), + ); + + it.effect("waits for a Retry-After given as an HTTP date", () => + Effect.gen(function* () { + const date = "Thu, 01 Jan 1970 00:00:04 GMT"; + const times = yield* pollTimes([outcome({ "retry-after": date }), outcome()]); + expect(times).toEqual([0, 4]); + }), + ); + + it.effect("never waits less than the backoff for a shorter Retry-After", () => + Effect.gen(function* () { + const times = yield* pollTimes([outcome({ "retry-after": "0" }), outcome()]); + expect(times).toEqual([0, 1]); + }), + ); +}); diff --git a/apps/cli/src/commands/api/api-command-flags.ts b/apps/cli/src/commands/api/api-command-flags.ts new file mode 100644 index 0000000000..08768de8a6 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-flags.ts @@ -0,0 +1,38 @@ +import { Option } from "effect"; +import { Flag } from "effect/cli"; + +import type { ApiCommandFlag } from "./api-command.model.ts"; + +/** The value a generated flag parses to; `None` records that the flag was absent. */ +export type ApiFlagValue = string | number | boolean | ReadonlyArray; + +const scalarFlag = (flag: ApiCommandFlag): Flag.Flag => { + if (flag.choices !== undefined && flag.choices.length > 0) { + return Flag.Literals(flag.name, flag.choices); + } + switch (flag.type) { + case "string": + return Flag.String(flag.name); + case "integer": + return Flag.Int(flag.name); + case "number": + return Flag.Finite(flag.name); + case "boolean": + return Flag.Boolean(flag.name); + } +}; + +/** + * Builds a flag that keeps absence distinct from every value: `Flag.optional` is the outermost + * wrapper, a repeatable flag needs at least one occurrence once present, and a boolean can be + * given as `false`. + */ +export const apiFlag = (flag: ApiCommandFlag): Flag.Flag> => { + const described = scalarFlag(flag).pipe( + Flag.withDescription(flag.description ?? `Set ${flag.name}.`), + ); + const shaped: Flag.Flag = flag.repeatable + ? Flag.map(Flag.atLeast(described, 1), (values): ApiFlagValue => values) + : Flag.map(described, (value): ApiFlagValue => value); + return Flag.optional(shaped); +}; diff --git a/apps/cli/src/commands/api/api-command-names.ts b/apps/cli/src/commands/api/api-command-names.ts new file mode 100644 index 0000000000..9838f4dd88 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-names.ts @@ -0,0 +1,53 @@ +import type { OpenApiOperationId } from "@supabase/api/effect"; +import type { ApiCommandWait } from "./api-command.model.ts"; + +/** Verbs every generated command may use; anything else needs `customVerb`. */ +export const verbVocabulary = [ + "list", + "get", + "create", + "update", + "delete", + "enable", + "disable", +] as const; + +export interface ApiNoun { + readonly description: string; + /** Feature that gates every command under the noun. */ + readonly feature?: string; +} + +export interface ApiCommandName { + /** Dot-separated noun path, e.g. `warehouse`. Its first segment must be a key of `nouns`. */ + readonly group: string; + readonly method: string; + /** Allows a `method` outside `verbVocabulary`. */ + readonly customVerb?: true; + /** API field name to flag name. */ + readonly flags?: Readonly>; + /** Credential-like body fields that were reviewed and are secrets. */ + readonly sensitive?: readonly string[]; + readonly wait?: ApiCommandWait; +} + +export const nouns = { + warehouse: { description: "Manage the data warehouse for a project", feature: "warehouse" }, +} as const satisfies Readonly>; + +export const commandNames = { + "v2-enable-warehouse": { + group: "warehouse", + method: "enable", + flags: { tables: "table" }, + wait: { + read: "v2-get-warehouse-setup", + params: { selection_id: "/data/attributes/selection_id" }, + status: "/data/attributes/status", + succeeded: ["succeeded"], + failed: ["failed"], + error: "/data/attributes/status_error", + }, + }, + "v2-get-warehouse-setup": { group: "warehouse", method: "status", customVerb: true }, +} as const satisfies Partial>; diff --git a/apps/cli/src/commands/api/api-command-pointer.ts b/apps/cli/src/commands/api/api-command-pointer.ts new file mode 100644 index 0000000000..0139ac169d --- /dev/null +++ b/apps/cli/src/commands/api/api-command-pointer.ts @@ -0,0 +1,33 @@ +import { Predicate } from "effect"; + +const segmentsOf = (pointer: string): ReadonlyArray => + pointer === "" + ? [] + : pointer + .slice(1) + .split("/") + .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~")); + +/** Reads the value at an RFC 6901 JSON pointer, or `undefined` when any step is missing. */ +export const readPointer = (root: unknown, pointer: string): unknown => { + let current: unknown = root; + for (const segment of segmentsOf(pointer)) { + if (!Predicate.isObject(current)) return undefined; + current = Reflect.get(current, segment); + } + return current; +}; + +const isPlainRecord = (value: unknown): value is Readonly> => + Predicate.isObject(value) && !Array.isArray(value); + +/** Returns a copy of `root` with `value` written at the pointer, creating missing objects. */ +export const writePointer = (root: unknown, pointer: string, value: unknown): unknown => { + const write = (node: unknown, segments: ReadonlyArray): unknown => { + const [head, ...rest] = segments; + if (head === undefined) return value; + const record = isPlainRecord(node) ? node : {}; + return { ...record, [head]: write(record[head], rest) }; + }; + return write(root, segmentsOf(pointer)); +}; diff --git a/apps/cli/src/commands/api/api-command-request.ts b/apps/cli/src/commands/api/api-command-request.ts new file mode 100644 index 0000000000..2978c18677 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-request.ts @@ -0,0 +1,240 @@ +import { operationDefinitions } from "@supabase/api/effect"; +import { Effect, FileSystem, Option, Predicate, Schema, type SchemaIssue } from "effect"; + +import { Stdin } from "../../shared/runtime/stdin.service.ts"; +import type { ApiFlagValue } from "./api-command-flags.ts"; +import { writePointer } from "./api-command-pointer.ts"; +import { ApiCommandUsageError } from "./api-command.errors.ts"; +import type { ApiCommandEntry } from "./api-command.model.ts"; + +/** Parsed flag values keyed by flag name; `None` means the flag was absent. */ +export type ApiFlagValues = Readonly>>; + +const REDACTED_PREVIEW_VALUE = "[redacted]"; + +const isRecord = (value: unknown): value is Readonly> => + Predicate.isObject(value) && !Array.isArray(value); + +/** The operation's typed definition; the entry names it as a key of `operationDefinitions`. */ +export const definitionOf = (entry: ApiCommandEntry) => operationDefinitions[entry.definition]; + +const parseBodyText = Effect.fnUntraced(function* (text: string, source: string) { + const parsed = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe( + Effect.mapError( + () => + new ApiCommandUsageError({ + message: `${source} is not valid JSON.`, + hint: "Pass the whole request body as one JSON object.", + }), + ), + ); + if (!isRecord(parsed)) { + return yield* new ApiCommandUsageError({ + message: `${source} must be a JSON object.`, + hint: "Pass the whole request body as one JSON object.", + }); + } + return parsed; +}); + +/** Reads the whole-body override from `--body` (JSON text) or `--file` (a JSON file, `-` for stdin). */ +export const readBodyOverride = Effect.fn("api-command.read-body")(function* (input: { + readonly body: Option.Option; + readonly file: Option.Option; +}) { + if (Option.isSome(input.body) && Option.isSome(input.file)) { + return yield* new ApiCommandUsageError({ + message: "--body and --file cannot be used together.", + hint: "Pass the request body with one of them.", + }); + } + if (Option.isSome(input.body)) { + return Option.some(yield* parseBodyText(input.body.value, "--body")); + } + if (Option.isSome(input.file)) { + const path = input.file.value; + if (path === "-") { + const stdin = yield* Stdin; + const piped = yield* stdin.readPipedText; + if (Option.isNone(piped)) { + return yield* new ApiCommandUsageError({ + message: "--file - found no body on stdin.", + hint: "Pipe the request body into the command, or pass --body.", + }); + } + return Option.some(yield* parseBodyText(piped.value, "--file -")); + } + const fs = yield* FileSystem.FileSystem; + const text = yield* fs.readFileString(path).pipe( + Effect.mapError( + () => + new ApiCommandUsageError({ + message: `Cannot read the --file body at ${path}.`, + hint: "Check that the file exists and is readable.", + }), + ), + ); + return Option.some(yield* parseBodyText(text, `--file ${path}`)); + } + return Option.none>>(); +}); + +const initialBody = (entry: ApiCommandEntry): Readonly> | undefined => { + if (entry.body === undefined) return undefined; + if (entry.body.kind === "json-envelope") { + return { data: { type: entry.body.type, attributes: {} } }; + } + return {}; +}; + +/** + * The flat operation input `{...bodyFields, ...query, ref}`. A body override is the starting point + * when given, else the synthesized envelope; only flags that were passed are written, each at its + * own pointer. An override may only carry top-level fields the request body declares, and the + * path and query values are applied last so body data cannot retarget the request. + */ +export const assembleInput = Effect.fnUntraced(function* ( + entry: ApiCommandEntry, + ref: string, + flagValues: ApiFlagValues, + bodyOverride: Option.Option>>, +) { + if (Option.isSome(bodyOverride)) { + const { requestBody } = definitionOf(entry); + const declared: ReadonlyArray = requestBody.kind === "json" ? requestBody.fields : []; + const unknown = Object.keys(bodyOverride.value).find((key) => !declared.includes(key)); + if (unknown !== undefined) { + return yield* new ApiCommandUsageError({ + message: `--body/--file has the field "${unknown}", which the request body does not take.`, + hint: + declared.length === 0 + ? "This command takes no request body." + : `Top-level fields: ${declared.join(", ")}.`, + }); + } + } + let body: unknown = Option.getOrElse(bodyOverride, () => initialBody(entry)); + const query: Record = {}; + for (const binding of entry.bindings) { + if (binding.source !== "flag") continue; + const value = flagValues[binding.flag]; + if (value === undefined || Option.isNone(value)) continue; + if (binding.location === "query") query[binding.name] = value.value; + if (binding.location === "body") body = writePointer(body, binding.pointer, value.value); + } + return { ...(isRecord(body) ? body : {}), ...query, ref }; +}); + +type Path = ReadonlyArray; + +/** Paths of the required keys an issue tree reports missing; `undefined` when it holds any other failure. */ +const missingKeyPaths = (issue: SchemaIssue.Issue, path: Path): ReadonlyArray | undefined => { + switch (issue._tag) { + case "MissingKey": + return [path]; + case "Pointer": + return missingKeyPaths(issue.issue, [...path, ...issue.path]); + case "Filter": + case "Encoding": + return missingKeyPaths(issue.issue, path); + case "Composite": + case "AnyOf": { + const paths: Path[] = []; + for (const child of issue.issues) { + const childPaths = missingKeyPaths(child, path); + if (childPaths === undefined) return undefined; + paths.push(...childPaths); + } + return paths.length === 0 ? undefined : paths; + } + default: + return undefined; + } +}; + +/** The flag that supplies the input field at `path`, if an entry binding covers it. */ +const flagAt = (entry: ApiCommandEntry, path: Path): string | undefined => { + const pointer = `/${path.map(String).join("/")}`; + for (const binding of entry.bindings) { + if (binding.source !== "flag") continue; + if (binding.location === "body" && binding.pointer === pointer) return binding.flag; + if (binding.location === "query" && path.length === 1 && path[0] === binding.name) { + return binding.flag; + } + } + return undefined; +}; + +const invalidRequest = (entry: ApiCommandEntry, error: Schema.SchemaError) => { + const paths = missingKeyPaths(error.issue, []); + const flags = paths?.map((path) => flagAt(entry, path)); + if (flags !== undefined && flags.every((flag) => flag !== undefined)) { + const names = flags.map((flag) => `--${flag}`).join(", "); + return new ApiCommandUsageError({ + message: `Missing required ${flags.length === 1 ? "flag" : "flags"} ${names}`, + hint: "Pass the flag, or include the field in --body/--file.", + }); + } + return new ApiCommandUsageError({ + message: `The request is not valid: ${error.message}`, + hint: "Check the flags, or the --body/--file contents.", + }); +}; + +/** + * Decodes an assembled input with the operation's input schema, rejecting unknown keys, so a + * request that cannot be formed fails before consent or any network call. + */ +export const decodeInput = (entry: ApiCommandEntry, input: unknown) => + Schema.decodeUnknownEffect(definitionOf(entry).inputSchema, { onExcessProperty: "error" })( + input, + ).pipe(Effect.mapError((error) => invalidRequest(entry, error))); + +/** What a request would send: method, path, query and body, with sensitive flag values masked. */ +export interface ApiRequestPreview { + readonly method: string; + readonly path: string; + readonly query: Readonly>; + readonly body: unknown; +} + +const pick = (source: object, keys: ReadonlyArray): Record => { + const picked: Record = {}; + for (const key of keys) { + const value: unknown = Reflect.get(source, key); + if (value !== undefined) picked[key] = value; + } + return picked; +}; + +/** Describes the request a decoded input would send. */ +export const previewRequest = ( + entry: ApiCommandEntry, + decoded: object, + flagValues: ApiFlagValues, +): ApiRequestPreview => { + const definition = definitionOf(entry); + const path = definition.pathParams.reduce( + (current, name) => + current.replace(`{${name}}`, encodeURIComponent(String(Reflect.get(decoded, name)))), + definition.path, + ); + const sensitive = new Set(entry.flags.filter((flag) => flag.sensitive).map((flag) => flag.name)); + let body: unknown = null; + if (definition.requestBody.kind === "json") { + body = pick(decoded, definition.requestBody.fields); + for (const binding of entry.bindings) { + if (binding.location !== "body" || !sensitive.has(binding.flag)) continue; + const value = flagValues[binding.flag]; + if (value !== undefined && Option.isSome(value)) { + body = writePointer(body, binding.pointer, REDACTED_PREVIEW_VALUE); + } + } + } + return { + method: definition.method, + path, + query: pick(decoded, definition.queryParams), + body, + }; +}; diff --git a/apps/cli/src/commands/api/api-command-stage.ts b/apps/cli/src/commands/api/api-command-stage.ts new file mode 100644 index 0000000000..9dc8030293 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-stage.ts @@ -0,0 +1,37 @@ +import { Context, Effect, Option } from "effect"; +import { Command } from "effect/cli"; + +import { requireExperimental } from "../../command-internal/experimental-gate.ts"; + +/** + * How far a command's contract has settled. An experimental command is reachable only through its + * `gate`: the `--experimental` flag, or an experimental feature whose family mounts the command. + */ +export interface CommandStage { + readonly status: "experimental"; + readonly gate: { readonly kind: "flag" } | { readonly kind: "feature"; readonly feature: string }; +} + +/** Context key under which a command's stage is stored in `Command.annotations`. */ +export class CommandStageAnnotation extends Context.Service()( + "supabase/CommandStageAnnotation", +) {} + +/** Declares the command's stage; install it together with {@link enforceStage} in the handler. */ +export const withCommandStage = + (stage: CommandStage) => + ( + self: Command.Command, + ) => + self.pipe(Command.annotate(CommandStageAnnotation, stage)); + +/** The stage a command declares, or `None` for a stable command. */ +export const readCommandStage = (command: Command.Command.Any): Option.Option => + Context.getOption(command.annotations, CommandStageAnnotation); + +/** + * Enforces a stage before any other effect. A feature gate is satisfied by the family being + * mounted: the root only mounts a feature's commands while the feature is enabled. + */ +export const enforceStage = (stage: CommandStage) => + stage.gate.kind === "flag" ? requireExperimental : Effect.void; diff --git a/apps/cli/src/commands/api/api-command.annotation.ts b/apps/cli/src/commands/api/api-command.annotation.ts new file mode 100644 index 0000000000..e3c05da9ce --- /dev/null +++ b/apps/cli/src/commands/api/api-command.annotation.ts @@ -0,0 +1,29 @@ +import { Context, Option } from "effect"; +import { Command } from "effect/cli"; + +import type { ApiCommandBinding, ApiCommandEntry } from "./api-command.model.ts"; + +/** What a generated command declares about its API operation; tooling reads it from `Command.annotations`. */ +export interface ApiCommandDescriptor { + readonly operationId: string; + readonly bindings: readonly ApiCommandBinding[]; + readonly response: ApiCommandEntry["response"]; +} + +/** Context key under which a generated command's descriptor is stored in `Command.annotations`. */ +export class ApiCommandAnnotation extends Context.Service< + ApiCommandAnnotation, + ApiCommandDescriptor +>()("supabase/ApiCommandAnnotation") {} + +/** Marks a command as generated from the Management API operation `descriptor` names. */ +export const withApiCommand = + (descriptor: ApiCommandDescriptor) => + ( + self: Command.Command, + ) => + self.pipe(Command.annotate(ApiCommandAnnotation, descriptor)); + +/** The descriptor of a generated command, or `None` for a hand-written one. */ +export const readApiCommand = (command: Command.Command.Any): Option.Option => + Context.getOption(command.annotations, ApiCommandAnnotation); diff --git a/apps/cli/src/commands/api/api-command.errors.ts b/apps/cli/src/commands/api/api-command.errors.ts new file mode 100644 index 0000000000..68572d7417 --- /dev/null +++ b/apps/cli/src/commands/api/api-command.errors.ts @@ -0,0 +1,54 @@ +import { Data } from "effect"; + +import { + actionability, + type CliErrorActionabilityDeclaration, + ErrorActionabilityId, + statusCodeActionability, +} from "../../shared/telemetry/error-actionability.ts"; + +/** The Management API answered a generated command with a non-2xx status. */ +export class ApiCommandStatusError extends Data.TaggedError("ApiCommandStatusError")<{ + readonly status: number; + readonly message: string; + readonly apiCode?: string | undefined; + readonly hint?: string | undefined; +}> { + get [ErrorActionabilityId](): CliErrorActionabilityDeclaration { + return statusCodeActionability(this.status, { notFoundIsInvalidInput: true }); + } +} + +/** The invocation cannot form a valid request; nothing was sent. */ +export class ApiCommandUsageError extends Data.TaggedError("ApiCommandUsageError")<{ + readonly message: string; + readonly hint?: string | undefined; +}> { + get [ErrorActionabilityId](): CliErrorActionabilityDeclaration { + return actionability.invalidInput; + } +} + +/** `--wait` observed the operation reach a failed status. */ +export class ApiCommandOperationFailedError extends Data.TaggedError( + "ApiCommandOperationFailedError", +)<{ + readonly message: string; + readonly status: string; + readonly hint: string; +}> { + get [ErrorActionabilityId](): CliErrorActionabilityDeclaration { + return actionability.invalidInput; + } +} + +/** `--wait` reached its timeout before the operation settled. */ +export class ApiCommandWaitTimeoutError extends Data.TaggedError("ApiCommandWaitTimeoutError")<{ + readonly message: string; + readonly timeoutMillis: number; + readonly hint: string; +}> { + get [ErrorActionabilityId](): CliErrorActionabilityDeclaration { + return { ...actionability.invalidInput, fingerprint_suffix: "operation_timeout" }; + } +} diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts new file mode 100644 index 0000000000..146ba90f31 --- /dev/null +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -0,0 +1,95 @@ +import type { OperationId } from "@supabase/api/effect"; + +/** Where a generated command's input lands in the API request. */ +export type ApiCommandBinding = + | { + readonly location: "path"; + /** Path parameter name. */ + readonly name: string; + /** The value comes from the command target (`--project-ref` or the linked project), not a flag. */ + readonly source: "target"; + } + | { + readonly location: "query"; + /** Query parameter name. */ + readonly name: string; + readonly source: "flag"; + /** Name of the flag that supplies the value. */ + readonly flag: string; + } + | { + readonly location: "body"; + /** Body field name. */ + readonly name: string; + /** JSON Pointer to the field in the whole request body, e.g. `/data/attributes/schema`. */ + readonly pointer: string; + readonly source: "flag"; + readonly flag: string; + }; + +/** One flag of a generated command, derived from a query parameter or a request body field. */ +export interface ApiCommandFlag { + /** Kebab-case flag name without the leading dashes. */ + readonly name: string; + readonly type: "string" | "integer" | "number" | "boolean"; + readonly choices?: readonly string[]; + readonly repeatable: boolean; + readonly required: boolean; + /** A body field the name table reviewed as a secret; its value is never echoed or recorded. */ + readonly sensitive?: true; + readonly description?: string; +} + +/** What `--wait` polls after a change and when it is done. */ +export interface ApiCommandWait { + /** Operation id of the read operation to poll. */ + readonly read: string; + /** Read parameter name to JSON pointer into the change response. */ + readonly params: Readonly>; + /** JSON pointer to the status in the read response. */ + readonly status: string; + readonly succeeded: readonly string[]; + readonly failed: readonly string[]; + /** JSON pointer to the failure reason in the read response. */ + readonly error?: string; +} + +/** A generated command as plain data; the runtime turns each entry into a CLI command. */ +export interface ApiCommandEntry { + /** Noun path followed by the verb, e.g. `["warehouse", "enable"]`. */ + readonly command: readonly string[]; + /** Kebab-case operation id from the OpenAPI spec. */ + readonly operationId: string; + /** Key of the operation in the typed client's `operationDefinitions`. */ + readonly definition: OperationId; + readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; + readonly apiPath: string; + readonly summary: string; + readonly description?: string; + readonly scope: "project"; + readonly readOnly: boolean; + readonly stability: "experimental"; + /** Feature that gates the command's noun. */ + readonly feature?: string; + /** Request body shape; `json-envelope` bodies wrap fields in `data.attributes`. */ + readonly body?: { + readonly contentType: "application/json"; + readonly kind: "json-object" | "json-envelope"; + /** The envelope's `data.type` value. */ + readonly type?: string; + }; + /** Success response shape from the first 2xx response. */ + readonly response: { + readonly status: number; + readonly kind: "json" | "text" | "empty"; + }; + readonly flags: readonly ApiCommandFlag[]; + readonly bindings: readonly ApiCommandBinding[]; + readonly wait?: ApiCommandWait; +} + +/** OpenAPI schemas of one operation with every `$ref` inlined. */ +export interface ApiCommandSchemas { + readonly request?: { readonly contentType: "application/json"; readonly schema: unknown }; + readonly result: unknown; +} diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts new file mode 100644 index 0000000000..7c03f9d121 --- /dev/null +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -0,0 +1,194 @@ +import { BunServices } from "@effect/platform-bun"; +import { expect, it } from "@effect/vitest"; +import { Data, Effect, FileSystem, Path, Schema } from "effect"; + +import { makeTempHome, requireCliSuccess, runSupabaseEffect } from "../../../tests/helpers/cli.ts"; + +class ApiCommandsE2eSetupError extends Data.TaggedError("ApiCommandsE2eSetupError")<{ + readonly cause: unknown; +}> { + override get message(): string { + return this.cause instanceof Error ? this.cause.message : String(this.cause); + } +} + +const REF = "abcdefghijklmnopqrst"; +const ACCESS_TOKEN = `sbp_${"a".repeat(40)}`; +const SEL = "ab".repeat(32); +const ENABLE_PATH = `/v2/projects/${REF}/warehouse/enable`; +const STATUS_PATH = `/v2/projects/${REF}/warehouse/setups/current`; + +const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); + +interface Served { + readonly status: number; + readonly body: string; +} + +const json = (status: number, body: unknown): Served => ({ + status, + body: JSON.stringify(body), +}); + +const statusBody = (state: string) => + json(200, { + data: { type: "warehouse_setup", attributes: { selection_id: SEL, status: state } }, + }); + +/** + * Runs the compiled CLI against a local Management API that answers `route`; the project + * lookup every `--remote` run makes is answered here. + */ +const runWarehouse = ( + args: ReadonlyArray, + route: (request: { readonly method: string; readonly pathname: string }) => Served, + options: { readonly stdin?: string } = {}, +) => + Effect.gen(function* () { + const requests: Array = []; + const server = yield* Effect.acquireRelease( + Effect.try({ + try: () => + Bun.serve({ + hostname: "127.0.0.1", + port: 0, + fetch(incoming) { + const { pathname } = new URL(incoming.url); + if (pathname === `/v1/projects/${REF}`) return Response.json({}); + requests.push(`${incoming.method} ${pathname}`); + const served = route({ method: incoming.method, pathname }); + return new Response(served.body, { + status: served.status, + headers: { "content-type": "application/json" }, + }); + }, + }), + catch: (cause) => new ApiCommandsE2eSetupError({ cause }), + }), + (running) => Effect.promise(() => running.stop(true)), + ); + const home = yield* makeTempHome.pipe( + Effect.mapError((cause) => new ApiCommandsE2eSetupError({ cause })), + ); + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const profilePath = path.join(home.dir, "api-commands-profile.yaml"); + yield* fs.writeFileString( + profilePath, + [ + "name: api-commands-e2e", + `api_url: "${server.url.origin}"`, + `dashboard_url: "${server.url.origin}"`, + 'project_host: "example.invalid"', + "", + ].join("\n"), + ); + const result = yield* runSupabaseEffect(["warehouse", ...args, `--remote=${REF}`], { + cwd: home.dir, + home: home.dir, + ...(options.stdin === undefined ? {} : { stdin: options.stdin }), + env: { + SUPABASE_ACCESS_TOKEN: ACCESS_TOKEN, + SUPABASE_EXPERIMENTAL_WAREHOUSE: "1", + SUPABASE_NO_KEYRING: "1", + SUPABASE_PROFILE: profilePath, + SUPABASE_TELEMETRY_DISABLED: "1", + SUPABASE_WORKDIR: home.dir, + SUPABASE_YES: undefined, + }, + }); + return { result, requests }; + }).pipe(Effect.scoped); + +it.live("warehouse enable prints the accepted response byte for byte", () => + Effect.gen(function* () { + const accepted = `{"data":{"type":"warehouse_setup","attributes":{"selection_id":"${SEL}","status":"pending","future_field":{"nested":[1, 2]}}}}`; + const { result, requests } = yield* runWarehouse( + ["enable", "--schema", "public", "--yes", "-o", "json"], + () => ({ status: 202, body: accepted }), + ); + + requireCliSuccess(result, "warehouse enable --yes -o json"); + expect(result.stdout, result.stderr).toBe(accepted); + expect(requests).toEqual([`POST ${ENABLE_PATH}`]); + }).pipe(Effect.provide(BunServices.layer)), +); + +it.live("warehouse status reports a 409 as a conflict failure document on stderr", () => + Effect.gen(function* () { + const { result } = yield* runWarehouse(["status", "-o", "json"], () => + json(409, { + error: { + code: "selection_conflict", + message: "The selection changed", + description: "Re-run enable.", + }, + }), + ); + + expect(result.exitCode, result.stderr).toBe(1); + expect(result.stdout).toBe(""); + const lastLine = result.stderr.trimEnd().split("\n").at(-1) ?? ""; + expect(decodeJson(lastLine)).toMatchObject({ + code: "conflict", + status: 409, + api_code: "selection_conflict", + message: expect.stringContaining("The selection changed"), + }); + }).pipe(Effect.provide(BunServices.layer)), +); + +it.live("warehouse enable without --yes refuses to run when stdin is piped", () => + Effect.gen(function* () { + const { result, requests } = yield* runWarehouse( + ["enable", "--schema", "public", "-o", "json"], + () => json(202, {}), + { stdin: "" }, + ); + + expect(result.exitCode, result.stderr).toBe(2); + expect(result.stdout).toBe(""); + const lastLine = result.stderr.trimEnd().split("\n").at(-1) ?? ""; + expect(decodeJson(lastLine)).toMatchObject({ + code: "usage_error", + hint: expect.stringContaining("Pass --yes"), + }); + expect(requests).toEqual([]); + }).pipe(Effect.provide(BunServices.layer)), +); + +it.live("warehouse enable --wait prints the final status read", () => + Effect.gen(function* () { + const reads = [statusBody("running"), statusBody("succeeded")]; + let read = 0; + const { result, requests } = yield* runWarehouse( + ["enable", "--schema", "public", "--yes", "--wait", "--timeout", "30s", "-o", "json"], + ({ method }) => { + if (method === "POST") return json(202, { data: { attributes: { selection_id: SEL } } }); + const next = reads[Math.min(read, reads.length - 1)] ?? statusBody("succeeded"); + read += 1; + return next; + }, + ); + + requireCliSuccess(result, "warehouse enable --wait"); + expect(result.stdout, result.stderr).toBe(statusBody("succeeded").body); + expect(requests).toEqual([`POST ${ENABLE_PATH}`, `GET ${STATUS_PATH}`, `GET ${STATUS_PATH}`]); + }).pipe(Effect.provide(BunServices.layer)), +); + +it.live("warehouse enable --file - reads the request body piped on stdin", () => + Effect.gen(function* () { + const accepted = `{"data":{"type":"warehouse_setup","attributes":{"selection_id":"${SEL}"}}}`; + const body = '{"data":{"type":"warehouse_setup","attributes":{"schema":"public"}}}'; + const { result, requests } = yield* runWarehouse( + ["enable", "--file", "-", "--yes", "-o", "json"], + () => ({ status: 202, body: accepted }), + { stdin: body }, + ); + + requireCliSuccess(result, "warehouse enable --file -"); + expect(result.stdout, result.stderr).toBe(accepted); + expect(requests).toEqual([`POST ${ENABLE_PATH}`]); + }).pipe(Effect.provide(BunServices.layer)), +); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts new file mode 100644 index 0000000000..ae854a10c4 --- /dev/null +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -0,0 +1,883 @@ +import { BunServices } from "@effect/platform-bun"; +import { describe, expect, it } from "@effect/vitest"; +import { Effect, Exit, Fiber, FileSystem, Layer, Option, Path, Schema, Stdio } from "effect"; +import { CliOutput, Command } from "effect/cli"; +import * as HttpClientError from "effect/http/HttpClientError"; +import * as TestClock from "effect/testing/TestClock"; + +import { respondToComplete } from "../../cli/complete.ts"; +import { rootCommandForFeatures } from "../../cli/root.ts"; +import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; +import { HostedMutationConsentRequiredError } from "../../command-internal/hosted-consent/hosted-consent.errors.ts"; +import { InvalidOutputFormatError } from "../../command-internal/output-formats.ts"; +import { ExperimentalFeatureFlagError } from "../../shared/config/experimental-feature.ts"; +import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; +import { commandTreeFor } from "../../../tests/helpers/command-flags.ts"; +import { + VALID_REF, + VALID_TOKEN, + buildTestRuntime, + mockCommandPlatformApi, + mockCommandSettings, + useTempWorkdir, + withConfigEnv, +} from "../../../tests/helpers/command-mocks.ts"; +import { describeHostedConsent } from "../../../tests/helpers/hosted-consent.ts"; +import { + mockOutput, + mockRuntimeInfo, + mockStdin, + mockTelemetryRuntime, + mockTty, +} from "../../../tests/helpers/mocks.ts"; +import { + ApiCommandOperationFailedError, + ApiCommandStatusError, + ApiCommandUsageError, + ApiCommandWaitTimeoutError, +} from "./api-command.errors.ts"; +import type { ApiCommandEntry } from "./api-command.model.ts"; +import { apiCommands } from "./generated.ts"; +import { readApiCommand } from "./api-command.annotation.ts"; +import { readCommandStage } from "./api-command-stage.ts"; +import { apiCommandGroup, apiCommandGroups } from "./runtime.ts"; +import { resolveWarehouseEnabled } from "./warehouse-backend.ts"; + +const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); +const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); + +const entryOf = (path: string): ApiCommandEntry => { + const entry = apiCommands.find((candidate) => candidate.command.join(" ") === path); + if (entry === undefined) throw new Error(`no generated command "${path}"`); + return entry; +}; + +const enable = entryOf("warehouse enable"); +const status = entryOf("warehouse status"); + +const ENABLE_PATH = `/v2/projects/${VALID_REF}/warehouse/enable`; +const STATUS_PATH = `/v2/projects/${VALID_REF}/warehouse/setups/current`; +const TARGET_LOOKUP_PATH = `/v1/projects/${VALID_REF}`; + +const SEL = "ab".repeat(32); + +const ACCEPTED = { + data: { + type: "warehouse_setup", + id: SEL, + attributes: { selection_id: SEL, status: "pending", future_field: { nested: [1, 2] } }, + }, +}; + +const statusBody = (state: string, statusError?: string) => ({ + data: { + type: "warehouse_setup", + attributes: { + selection_id: SEL, + status: state, + ...(statusError === undefined ? {} : { status_error: statusError }), + }, + }, +}); + +/** One request the CLI sent to the stubbed Management API. */ +interface Sent { + readonly method: string; + readonly path: string; + readonly search: string; + readonly body: unknown; +} + +/** A canned API answer; a string body is sent as is, anything else as JSON. */ +interface Reply { + readonly status: number; + readonly body?: unknown; + /** Fails the body stream mid-read, after the status line was delivered. */ + readonly unreadable?: boolean; +} + +type Route = (request: Sent) => Reply; + +const ok = + (body: unknown): Route => + () => ({ status: 200, body }); +const accepted: Route = () => ({ status: 202, body: ACCEPTED }); + +/** Answers the enable POST with `ACCEPTED` and each later read with the next of `reads`. */ +const enableThenPoll = (reads: ReadonlyArray): Route => { + let read = 0; + return (request) => { + if (request.method === "POST") return { status: 202, body: ACCEPTED }; + const next = reads[Math.min(read, reads.length - 1)]; + read += 1; + return next ?? { status: 200, body: {} }; + }; +}; + +const replyOf = (reply: Reply): Response => { + if (reply.unreadable === true) { + const broken = new ReadableStream({ + pull: (controller) => controller.error(new Error("connection reset")), + }); + return new Response(broken, { + status: reply.status, + headers: { "content-type": "application/json" }, + }); + } + const text = + reply.body === undefined + ? null + : typeof reply.body === "string" + ? reply.body + : encodeJson(reply.body); + return new Response(text, { + status: reply.status, + headers: reply.body === undefined ? {} : { "content-type": "application/json" }, + }); +}; + +/** Replaces `globalThis.fetch` while `body` runs: the one in-process seam under the real leaf. */ +const withApi = (route: Route, sent: Array) => { + const stub = (input: string | URL | Request, init?: RequestInit): Promise => { + const request = input instanceof Request ? input : new Request(String(input), init); + const url = new URL(request.url); + if (url.pathname === TARGET_LOOKUP_PATH) { + return Promise.resolve(replyOf({ status: 200, body: {} })); + } + return request.text().then((text) => { + const entry: Sent = { + method: request.method, + path: url.pathname, + search: url.search.replace(/^\?/, ""), + body: text === "" ? undefined : decodeJson(text), + }; + sent.push(entry); + return replyOf(route(entry)); + }); + }; + return (body: Effect.Effect) => + Effect.acquireUseRelease( + Effect.sync(() => { + const previous = globalThis.fetch; + globalThis.fetch = Object.assign(stub, { preconnect: previous.preconnect }); + return previous; + }), + () => body, + (previous) => + Effect.sync(() => { + globalThis.fetch = previous; + }), + ); +}; + +const warehouseRoot = Command.make("supabase").pipe( + Command.withSubcommands(apiCommandGroups(["warehouse"])), + Command.withGlobalFlags(GLOBAL_FLAGS), +); + +const tempRoot = useTempWorkdir("supabase-api-commands-int-"); + +/** What the real root needs around a leaf that is not part of the command tree under test. */ +const cliServices = (workdir: string, args: ReadonlyArray) => + Layer.mergeAll( + BunServices.layer, + CliOutput.layer(textCliOutputFormatter()), + Layer.succeed(ExperimentalFlag, false), + mockTelemetryRuntime({ configDir: workdir }), + mockRuntimeInfo({ cwd: workdir, homeDir: workdir }), + Stdio.layerTest({ args: Effect.succeed(args) }), + ); + +interface CliOpts { + readonly yes?: boolean; + readonly route: Route; + readonly root?: typeof warehouseRoot; +} + +/** + * Runs `argv` through the real parser and the real generated leaf; only `globalThis.fetch` is + * stubbed. `run` still needs the test runtime layers (see {@link setup}). + */ +const execute = (argv: ReadonlyArray, opts: CliOpts) => { + const args = [...argv, `--remote=${VALID_REF}`, ...(opts.yes === true ? ["--yes"] : [])]; + const sent: Array = []; + const run = withConfigEnv( + { SUPABASE_ACCESS_TOKEN: VALID_TOKEN, SUPABASE_NO_KEYRING: "1" }, + Command.runWith(opts.root ?? warehouseRoot, { version: "0.0.0-test" })(args), + ).pipe(withApi(opts.route, sent)); + return { args, sent, run }; +}; + +const setup = (argv: ReadonlyArray, opts: CliOpts) => { + const out = mockOutput({ format: "text" }); + const { args, sent, run } = execute(argv, opts); + const layer = Layer.mergeAll( + buildTestRuntime({ + out, + api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), + cliSettings: mockCommandSettings({ workdir: tempRoot.current }), + tty: mockTty({ stdinIsTty: false, stdoutIsTty: false }), + stdin: mockStdin(false), + cliArgs: args, + }), + cliServices(tempRoot.current, args), + ); + return { out, sent, run: run.pipe(Effect.provide(layer)) }; +}; + +const failureOf = (exit: Exit.Exit): unknown => + Exit.isFailure(exit) ? Exit.findErrorOption(exit).pipe(Option.getOrUndefined) : undefined; + +const bodiesOf = (sent: ReadonlyArray) => sent.map((request) => request.body); + +describe("generated warehouse commands", () => { + describe("warehouse enable request", () => { + it.effect("sends only the schema when no other flag is given", () => { + const { sent, run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + yield* run; + expect(sent.map((request) => `${request.method} ${request.path}`)).toEqual([ + `POST ${ENABLE_PATH}`, + ]); + expect(bodiesOf(sent)).toEqual([ + { data: { type: "warehouse_setup", attributes: { schema: "public" } } }, + ]); + }); + }); + + it.effect("maps a repeated --table to tables and keeps a false boolean", () => { + const { sent, run } = setup( + [ + "warehouse", + "enable", + "--schema", + "public", + "--table", + "a", + "--table", + "b", + "--install-fdw", + "false", + ], + { yes: true, route: accepted }, + ); + return Effect.gen(function* () { + yield* run; + expect(bodiesOf(sent)).toEqual([ + { + data: { + type: "warehouse_setup", + attributes: { schema: "public", tables: ["a", "b"], install_fdw: false }, + }, + }, + ]); + }); + }); + + it.effect("lets a flag win only at its own pointer when merged into --body", () => { + const body = encodeJson({ + data: { + type: "warehouse_setup", + attributes: { schema: "from-body", install_fdw: true, tables: ["t1"] }, + }, + }); + const { sent, run } = setup( + ["warehouse", "enable", "--body", body, "--schema", "from-flag"], + { + yes: true, + route: accepted, + }, + ); + return Effect.gen(function* () { + yield* run; + expect(bodiesOf(sent)).toEqual([ + { + data: { + type: "warehouse_setup", + attributes: { schema: "from-flag", install_fdw: true, tables: ["t1"] }, + }, + }, + ]); + }); + }); + + it.effect("reads the whole body from --file", () => { + const { sent, run } = setup( + ["warehouse", "enable", "--file", `${tempRoot.current}/enable.json`], + { yes: true, route: accepted }, + ); + return Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + yield* fs.writeFileString( + path.join(tempRoot.current, "enable.json"), + encodeJson({ data: { type: "warehouse_setup", attributes: { schema: "file" } } }), + ); + yield* run; + expect(bodiesOf(sent)).toEqual([ + { data: { type: "warehouse_setup", attributes: { schema: "file" } } }, + ]); + }).pipe(Effect.provide(BunServices.layer)); + }); + + it.effect("rejects an unknown key in --body as a usage error and sends nothing", () => { + const body = encodeJson({ + data: { type: "warehouse_setup", attributes: { schema: "public", bogus: 1 } }, + }); + const { sent, run } = setup(["warehouse", "enable", "--body", body], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + expect(failureOf(yield* Effect.exit(run))).toBeInstanceOf(ApiCommandUsageError); + expect(sent).toEqual([]); + }); + }); + + it.effect.each([ + { + name: "ref", + body: { + ref: "zyxwvutsrqponmlkjihg", + data: { type: "warehouse_setup", attributes: { schema: "public" } }, + }, + }, + { name: "bogus", body: { bogus: 1 } }, + ])( + "rejects the top-level $name key in --body, naming it, and sends nothing", + ({ name, body }) => { + const { sent, run } = setup(["warehouse", "enable", "--body", encodeJson(body)], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(failure).toBeInstanceOf(ApiCommandUsageError); + expect(failure).toMatchObject({ message: expect.stringContaining(`"${name}"`) }); + expect(sent).toEqual([]); + }); + }, + ); + + it.effect("names the missing --schema flag and sends nothing", () => { + const { sent, run } = setup(["warehouse", "enable", "--install-fdw", "true"], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(failure).toBeInstanceOf(ApiCommandUsageError); + expect(failure).toMatchObject({ + message: "Missing required flag --schema", + hint: "Pass the flag, or include the field in --body/--file.", + }); + expect(sent).toEqual([]); + }); + }); + }); + + describe("consent and dry run", () => { + it.effect("prints exactly the request preview and sends nothing under --dry-run", () => { + const { out, sent, run } = setup( + ["warehouse", "enable", "--schema", "public", "--table", "a", "--dry-run"], + { route: accepted }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([]); + expect(decodeJson(out.stdoutText)).toEqual({ + method: "POST", + path: ENABLE_PATH, + query: {}, + body: { + data: { type: "warehouse_setup", attributes: { schema: "public", tables: ["a"] } }, + }, + }); + }); + }); + + it.effect("previews a read with a null body", () => { + const { out, run } = setup(["warehouse", "status", "--inspect-fdw", "false", "--dry-run"], { + route: ok({}), + }); + return Effect.gen(function* () { + yield* run; + expect(decodeJson(out.stdoutText)).toEqual({ + method: "GET", + path: STATUS_PATH, + query: { inspect_fdw: "false" }, + body: null, + }); + }); + }); + + it.effect("prints the dry-run preview as YAML under -o yaml", () => { + const { out, run } = setup( + ["warehouse", "enable", "--schema", "public", "--dry-run", "-o", "yaml"], + { route: accepted }, + ); + return Effect.gen(function* () { + yield* run; + expect(Bun.YAML.parse(out.stdoutText)).toEqual({ + method: "POST", + path: ENABLE_PATH, + query: {}, + body: { data: { type: "warehouse_setup", attributes: { schema: "public" } } }, + }); + }); + }); + + it.effect.each([ + { name: "a send", argv: ["warehouse", "enable", "--schema", "public"] }, + { name: "a dry run", argv: ["warehouse", "enable", "--schema", "public", "--dry-run"] }, + { name: "a read", argv: ["warehouse", "status"] }, + ])("rejects -o env for $name as a usage error and sends nothing", ({ argv }) => { + const { sent, run } = setup([...argv, "-o", "env"], { yes: true, route: accepted }); + return Effect.gen(function* () { + expect(failureOf(yield* Effect.exit(run))).toBeInstanceOf(InvalidOutputFormatError); + expect(sent).toEqual([]); + }); + }); + + it.effect("refuses a non-interactive mutation without --yes", () => { + const { sent, run } = setup(["warehouse", "enable", "--schema", "public"], { + route: accepted, + }); + return Effect.gen(function* () { + expect(failureOf(yield* Effect.exit(run))).toBeInstanceOf( + HostedMutationConsentRequiredError, + ); + expect(sent).toEqual([]); + }); + }); + }); + + describe("responses", () => { + it.effect( + "writes a JSON response with unknown fields unchanged and without a target key", + () => { + const { out, run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(encodeJson(ACCEPTED)); + expect(out.stdoutText).not.toContain('"target"'); + }); + }, + ); + + it.effect.each([ + { + name: "a v1 body with a top-level message and code", + reply: { status: 422, body: { message: "selection rejected", code: "selection_conflict" } }, + expected: { status: 422, message: "selection rejected", apiCode: "selection_conflict" }, + }, + { + name: "a v2 body nesting the error, with its description", + reply: { + status: 409, + body: { + error: { code: "conflict", message: "Setup exists", description: "Run status." }, + }, + }, + expected: { status: 409, message: "Setup exists: Run status.", apiCode: "conflict" }, + }, + { + name: "a v2 401 body", + reply: { + status: 401, + body: { error: { code: "unauthenticated", message: "Invalid access token" } }, + }, + expected: { + status: 401, + message: "Invalid access token", + apiCode: "unauthenticated", + }, + }, + { + name: "a body that carries no message", + reply: { status: 503, body: "bad gateway" }, + expected: { status: 503, message: "Unexpected status 503", apiCode: undefined }, + }, + ])("fails with the parsed API error for $name", ({ reply, expected }) => { + const { run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: () => reply, + }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(failure).toBeInstanceOf(ApiCommandStatusError); + expect(failure).toMatchObject(expected); + }); + }); + + it.effect("fails with a network error when the success body cannot be read", () => { + const { out, run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: () => ({ status: 202, unreadable: true }), + }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(HttpClientError.isHttpClientError(failure)).toBe(true); + expect(out.stdoutText).toBe(""); + }); + }); + + it.effect.each([ + { + name: "a 401", + reply: { status: 401, body: { message: "Invalid access token" } }, + hint: "Run `supabase login`", + }, + { + name: "a 403", + reply: { status: 403, body: { message: "Forbidden" } }, + hint: "Your token needs the permissions:", + }, + { + name: "a 401 that carries its own hint", + reply: { + status: 401, + body: { message: "Expired", hint: "Rotate the token in the dashboard." }, + }, + hint: "Rotate the token in the dashboard.", + }, + ])("hints at the fix for $name", ({ reply, hint }) => { + const { run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: () => reply, + }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(failure).toBeInstanceOf(ApiCommandStatusError); + expect(failure).toMatchObject({ hint: expect.stringContaining(hint) }); + }); + }); + + it.effect("prints a JSON response as YAML of the parsed document under -o yaml", () => { + const { out, run } = setup(["warehouse", "enable", "--schema", "public", "-o", "yaml"], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + yield* run; + expect(Bun.YAML.parse(out.stdoutText)).toEqual(ACCEPTED); + }); + }); + + it.effect("sends status --inspect-fdw false as the inspect_fdw=false query", () => { + const { sent, out, run } = setup(["warehouse", "status", "--inspect-fdw", "false"], { + route: ok(statusBody("succeeded")), + }); + return Effect.gen(function* () { + yield* run; + expect(sent.map((request) => request.method)).toEqual(["GET"]); + expect(sent[0]?.path).toBe(STATUS_PATH); + expect(sent[0]?.search).toBe("inspect_fdw=false"); + expect(decodeJson(out.stdoutText)).toEqual(statusBody("succeeded")); + }); + }); + + it.effect("sends no query when no status flag is given", () => { + const { sent, run } = setup(["warehouse", "status"], { route: ok(statusBody("succeeded")) }); + return Effect.gen(function* () { + yield* run; + expect(sent[0]?.search).toBe(""); + }); + }); + }); + + describe("--wait", () => { + const driveClock = (fiber: Fiber.Fiber) => + Effect.raceFirst(Effect.forever(TestClock.adjust("2 seconds")), Fiber.await(fiber)); + + it.effect("polls the read operation until the setup succeeds and prints its response", () => { + const { sent, out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([ + { status: 200, body: statusBody("pending") }, + { status: 200, body: statusBody("pending") }, + { status: 200, body: statusBody("succeeded") }, + ]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + yield* Fiber.join(fiber); + const gets = sent.filter((request) => request.method === "GET"); + expect(gets).toHaveLength(3); + expect(gets.every((request) => request.path === STATUS_PATH)).toBe(true); + expect(gets.every((request) => request.search === `selection_id=${SEL}`)).toBe(true); + expect(out.stdoutText).toBe(encodeJson(statusBody("succeeded"))); + }); + }); + + it.effect("fails with the reported status_error when the setup fails", () => { + const { run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([{ status: 200, body: statusBody("failed", "pipeline crashed") }]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + const failure = yield* Fiber.join(fiber); + expect(failure).toBeInstanceOf(ApiCommandOperationFailedError); + expect(failure).toMatchObject({ message: expect.stringContaining("pipeline crashed") }); + }); + }); + + it.effect("times out on the controlled clock when the status never settles", () => { + const { sent, run } = setup( + ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "10s"], + { yes: true, route: enableThenPoll([{ status: 200, body: statusBody("pending") }]) }, + ); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + expect(yield* Fiber.join(fiber)).toBeInstanceOf(ApiCommandWaitTimeoutError); + expect(sent.filter((request) => request.method === "GET").length).toBeGreaterThan(1); + }); + }); + + it.effect("treats a 409 on the read as terminal and does not poll again", () => { + const { sent, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([ + { + status: 409, + body: { error: { code: "selection_conflict", message: "selection changed" } }, + }, + ]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + const failure = yield* Fiber.join(fiber); + expect(failure).toBeInstanceOf(ApiCommandStatusError); + expect(failure).toMatchObject({ status: 409, apiCode: "selection_conflict" }); + expect(sent.filter((request) => request.method === "GET")).toHaveLength(1); + }); + }); + + it.effect( + "prints the original response and reads nothing when the change gives no selection_id", + () => { + const noSelection = { + data: { type: "warehouse_setup", attributes: { status: "pending" } }, + }; + const { sent, out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: () => ({ status: 202, body: noSelection }), + }); + return Effect.gen(function* () { + yield* run; + expect(sent.map((request) => request.method)).toEqual(["POST"]); + expect(out.stdoutText).toBe(encodeJson(noSelection)); + }); + }, + ); + + it.effect("fails when the status_error pointer is set, whatever the status", () => { + const { run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([{ status: 200, body: statusBody("pending", "disk full") }]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + const failure = yield* Fiber.join(fiber); + expect(failure).toBeInstanceOf(ApiCommandOperationFailedError); + expect(failure).toMatchObject({ status: "pending", message: "disk full" }); + }); + }); + + it.effect("names the status command when the setup fails and when the wait times out", () => { + const failing = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([{ status: 200, body: statusBody("failed", "boom") }]), + }); + const stalling = setup( + ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "10s"], + { yes: true, route: enableThenPoll([{ status: 200, body: statusBody("pending") }]) }, + ); + const command = `supabase warehouse status --selection-id ${SEL} --remote=${VALID_REF}`; + return Effect.gen(function* () { + for (const { run } of [failing, stalling]) { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + expect(yield* Fiber.join(fiber)).toMatchObject({ + hint: expect.stringContaining(command), + }); + } + }); + }); + + it.effect("prints the final status read as YAML under -o yaml", () => { + const { out, run } = setup( + ["warehouse", "enable", "--schema", "public", "--wait", "-o", "yaml"], + { + yes: true, + route: enableThenPoll([ + { status: 200, body: statusBody("pending") }, + { status: 200, body: statusBody("succeeded") }, + ]), + }, + ); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + yield* Fiber.join(fiber); + expect(Bun.YAML.parse(out.stdoutText)).toEqual(statusBody("succeeded")); + }); + }); + + it.effect("rejects an invalid --timeout before sending anything", () => { + const { sent, run } = setup( + ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "soon"], + { yes: true, route: accepted }, + ); + return Effect.gen(function* () { + expect(failureOf(yield* Effect.exit(run))).toBeInstanceOf(ApiCommandUsageError); + expect(sent).toEqual([]); + }); + }); + }); + + describe("generic response writing", () => { + const fixture: ApiCommandEntry = { + ...status, + command: ["fixture", "read"], + }; + const fixtureRoot = (entry: ApiCommandEntry) => + Command.make("supabase").pipe( + Command.withSubcommands([apiCommandGroup("fixture", "Fixture commands", [entry])]), + Command.withGlobalFlags(GLOBAL_FLAGS), + ); + + it.effect.each([ + { + name: "a text body as one JSON string", + kind: "text" as const, + reply: { status: 200, body: "plain text\nsecond line" }, + stdout: '"plain text\\nsecond line"\n', + }, + { + name: "an empty body as null", + kind: "empty" as const, + reply: { status: 204 }, + stdout: "null\n", + }, + { + name: "a JSON body byte for byte, unknown fields and spacing included", + kind: "json" as const, + reply: { status: 200, body: '{"z": 1, "known": {"future": [1, 2]}}' }, + stdout: '{"z": 1, "known": {"future": [1, 2]}}', + }, + ])("writes $name", ({ kind, reply, stdout }) => { + const entry: ApiCommandEntry = { + ...fixture, + response: { status: reply.status, kind }, + }; + const { out, run } = setup(["fixture", "read"], { + root: fixtureRoot(entry), + route: () => reply, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(stdout); + }); + }); + }); + + describe("feature gate", () => { + const resolve = (env: Record, cwd: string) => + withConfigEnv(env, resolveWarehouseEnabled({ args: ["warehouse"], cwd })).pipe( + Effect.provide(BunServices.layer), + ); + + const withConfig = (config: string) => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + yield* fs.makeDirectory(path.join(tempRoot.current, "supabase"), { recursive: true }); + yield* fs.writeFileString(path.join(tempRoot.current, "supabase", "config.toml"), config); + }).pipe(Effect.provide(BunServices.layer)); + + it.effect("is off by default and absent from the tree and completion", () => + Effect.gen(function* () { + expect(yield* resolve({}, tempRoot.current)).toBe(false); + expect(commandTreeFor(undefined).has("warehouse enable")).toBe(false); + const completion = respondToComplete(rootCommandForFeatures(), ["__complete", "ware"]); + expect(completion?.candidates ?? []).toHaveLength(0); + }), + ); + + it.effect("is on with SUPABASE_EXPERIMENTAL_WAREHOUSE", () => + Effect.gen(function* () { + expect(yield* resolve({ SUPABASE_EXPERIMENTAL_WAREHOUSE: "1" }, tempRoot.current)).toBe( + true, + ); + const root = rootCommandForFeatures({ warehouseEnabled: true }); + const completion = respondToComplete(root, ["__complete", "ware"]); + expect(completion?.candidates).toContainEqual( + expect.objectContaining({ name: "warehouse" }), + ); + const tree = commandTreeFor({ warehouseEnabled: true }); + expect(tree.has("warehouse enable")).toBe(true); + expect(tree.has("warehouse status")).toBe(true); + }), + ); + + it("marks each mounted leaf with its operation and experimental feature stage", () => { + const tree = commandTreeFor({ warehouseEnabled: true }); + for (const entry of [enable, status]) { + const command = tree.get(entry.command.join(" "))?.command; + if (command === undefined) throw new Error(`${entry.command.join(" ")} is not mounted`); + expect(Option.map(readApiCommand(command), (api) => api.operationId)).toEqual( + Option.some(entry.operationId), + ); + expect(readCommandStage(command)).toEqual( + Option.some({ status: "experimental", gate: { kind: "feature", feature: "warehouse" } }), + ); + } + }); + + it.effect("is on with experimental.warehouse in the project config", () => + Effect.gen(function* () { + yield* withConfig("[experimental]\nwarehouse = true\n"); + expect(yield* resolve({}, tempRoot.current)).toBe(true); + }), + ); + + it.effect("fails with a typed error for an invalid environment value", () => + Effect.gen(function* () { + const error = yield* resolve( + { SUPABASE_EXPERIMENTAL_WAREHOUSE: "maybe" }, + tempRoot.current, + ).pipe(Effect.flip); + expect(error).toBeInstanceOf(ExperimentalFeatureFlagError); + }), + ); + }); +}); + +const consentCommand = commandTreeFor({ warehouseEnabled: true }).get("warehouse enable")?.command; + +describeHostedConsent("warehouse enable", { + ...(consentCommand === undefined ? {} : { command: consentCommand }), + invoke: ({ workdir, yes }) => { + const { args, sent, run } = execute(["warehouse", "enable", "--schema", "public"], { + yes, + route: accepted, + }); + return { + run: run.pipe(Effect.provide(cliServices(workdir, args))), + mutations: () => sent.filter((request) => request.method !== "GET").length, + }; + }, +}); diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts new file mode 100644 index 0000000000..3c19b03fb1 --- /dev/null +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -0,0 +1,437 @@ +// Generated by scripts/generate-api-commands.ts. Do not edit. +import type { ApiCommandSchemas } from "./api-command.model.ts"; + +export const apiCommandSchemas = { + "v2-enable-warehouse": { + request: { + contentType: "application/json", + schema: { + $schema: "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { + data: { + type: "object", + properties: { + type: { + type: "string", + description: "Resource type.", + enum: ["warehouse_setup"], + }, + attributes: { + type: "object", + properties: { + warehouse_region: { + description: + "Optional Warehouse compute region, independent of the source and catalog regions. Defaults to the existing assignment, or ap-southeast-1 in staging and eu-west-1 in production for a new assignment. DNS routing requires a registered cluster in that environment. Unsupported regions and changes to an existing assignment are rejected. Ignored when targets is empty.", + type: "string", + minLength: 1, + examples: ["ap-southeast-1"], + }, + destination_project_ref: { + description: + "Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. Defaults to this project on first setup and to the configured destination on later requests. The destination must be active and healthy, and another project requires SQL and Storage admin write permissions. An existing destination cannot be changed through setup. Ignored when targets is empty.", + type: "string", + minLength: 20, + maxLength: 20, + pattern: "^[a-z]+$", + examples: ["zyxwvutsrqponmlkjihg"], + }, + install_fdw: { + description: + "Whether to configure and install the Warehouse FDW in the project database. Defaults to false. Ignored when targets is empty.", + type: "boolean", + examples: [false], + }, + schema: { + type: "string", + minLength: 1, + description: + "Source PostgreSQL schema. Without tables, selects its currently eligible tables only.", + examples: ["public"], + }, + tables: { + description: + "Table names in schema. Omit to select the currently eligible tables in that schema.", + "x-ignore-array-items-must-be-objects": true, + minItems: 1, + type: "array", + items: { + type: "string", + minLength: 1, + }, + }, + }, + required: ["schema"], + additionalProperties: false, + }, + }, + required: ["type", "attributes"], + }, + }, + required: ["data"], + }, + }, + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { + data: { + type: "object", + properties: { + type: { + type: "string", + description: "Resource type.", + enum: ["warehouse_setup"], + }, + id: { + type: "string", + }, + attributes: { + type: "object", + properties: { + tables: { + type: "array", + items: { + type: "object", + properties: { + schema: { + type: "string", + minLength: 1, + description: "Postgres schema name", + examples: ["public"], + }, + name: { + type: "string", + minLength: 1, + description: "Postgres table name", + examples: ["orders"], + }, + state: { + type: "string", + enum: ["syncing", "live", "error"], + description: "Warehouse copy sync state derived from replication status", + examples: ["live"], + }, + lag_ms: { + description: "Replication lag in milliseconds, when available", + type: "integer", + minimum: 0, + maximum: 9007199254740991, + examples: [12000], + }, + last_synced_at: { + description: "Last sync timestamp, when available", + type: "string", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + examples: ["2026-06-23T17:48:00Z"], + }, + copy_name: { + type: "string", + description: + "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + examples: ['"abcjuqabhgwjjutfvtpa"."public"."orders"'], + }, + warehouse_size_bytes: { + description: "Warehouse table size in bytes, when available", + type: "integer", + minimum: 0, + maximum: 9007199254740991, + examples: [197912092672], + }, + }, + required: ["schema", "name", "state", "copy_name"], + }, + description: "Tables with Warehouse copies", + }, + pipeline_id: { + type: ["string", "null"], + minLength: 1, + description: + "Warehouse replication pipeline ID, or null when Warehouse disable has been requested", + examples: ["03dg2o5teb2eucxr9ggh3uie6"], + }, + accepted: { + type: "boolean", + enum: [true], + }, + selected_tables: { + type: "array", + items: { + type: "object", + properties: { + id: { + type: "integer", + maximum: 4294967295, + exclusiveMinimum: 0, + }, + schema: { + type: "string", + minLength: 1, + }, + name: { + type: "string", + minLength: 1, + }, + }, + required: ["id", "schema", "name"], + }, + }, + selection_id: { + type: "string", + pattern: "^[a-f0-9]{64}$", + description: + "Identity of the accepted selection. Pass to the current setup read to reject a changed selection while waiting.", + }, + }, + required: ["tables", "pipeline_id", "accepted", "selected_tables", "selection_id"], + }, + }, + required: ["type", "id", "attributes"], + }, + }, + required: ["data"], + }, + }, + "v2-get-warehouse-setup": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { + data: { + type: "object", + properties: { + type: { + type: "string", + description: "Resource type.", + enum: ["warehouse_setup"], + }, + id: { + type: "string", + }, + attributes: { + type: "object", + properties: { + dns: { + description: + "Warehouse DNS delivery status. Ready means the DNS API accepted the route; client DNS caches may still be updating.", + type: "object", + properties: { + hostname: { + type: "string", + }, + region: { + type: "string", + }, + status: { + type: "string", + enum: ["pending", "ready", "error", "removed"], + }, + }, + required: ["hostname", "region", "status"], + }, + delete_data: { + description: "Whether the current disable request deletes DuckLake data.", + type: "boolean", + }, + error: { + description: "Warehouse cleanup failure, when present.", + type: "string", + }, + setup_status: { + type: "string", + enum: [ + "not_started", + "setting_up", + "copying", + "complete", + "error", + "disabling", + "disabled", + "deletion_failed", + ], + description: + "Overall Warehouse lifecycle status, using persisted state during teardown and replication state during setup", + examples: ["copying"], + }, + pipeline_id: { + description: "Warehouse replication pipeline ID when it exists", + type: "string", + minLength: 1, + examples: ["03dg2o5teb2eucxr9ggh3uie6"], + }, + steps: { + type: "array", + items: { + type: "object", + properties: { + name: { + type: "string", + enum: ["warehouse_pipeline", "warehouse_copy", "warehouse_fdw"], + description: "Observable Warehouse setup phase", + examples: ["warehouse_copy"], + }, + status: { + type: "string", + enum: ["waiting", "running", "completed", "skipped", "error"], + description: "Derived Warehouse setup step status", + examples: ["running"], + }, + message: { + description: + "Best-effort progress or error message derived from Warehouse state", + type: "string", + examples: ["Pending initial copy: public.orders:copying_table"], + }, + }, + required: ["name", "status"], + }, + description: "Warehouse setup phases in execution order", + }, + tables: { + type: "array", + items: { + type: "object", + properties: { + schema: { + type: "string", + minLength: 1, + description: "Postgres schema name", + examples: ["public"], + }, + name: { + type: "string", + minLength: 1, + description: "Postgres table name", + examples: ["orders"], + }, + state: { + type: "string", + enum: ["syncing", "live", "error"], + description: "Warehouse copy sync state derived from replication status", + examples: ["live"], + }, + lag_ms: { + description: "Replication lag in milliseconds, when available", + type: "integer", + minimum: 0, + maximum: 9007199254740991, + examples: [12000], + }, + last_synced_at: { + description: "Last sync timestamp, when available", + type: "string", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + examples: ["2026-06-23T17:48:00Z"], + }, + copy_name: { + type: "string", + description: + "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + examples: ['"abcjuqabhgwjjutfvtpa"."public"."orders"'], + }, + warehouse_size_bytes: { + description: "Warehouse table size in bytes, when available", + type: "integer", + minimum: 0, + maximum: 9007199254740991, + examples: [197912092672], + }, + id: { + type: "integer", + maximum: 4294967295, + exclusiveMinimum: 0, + }, + replication_state: { + type: ["string", "null"], + }, + }, + required: ["schema", "name", "state", "copy_name", "id", "replication_state"], + }, + }, + fdw_status: { + type: ["object", "null"], + properties: { + extension_available: { + type: "boolean", + description: + "Whether fdw_warehouse is available to install on the project database instance", + examples: [true], + }, + extension_installed: { + type: "boolean", + description: + "Whether the fdw_warehouse extension exists in the project database", + examples: [true], + }, + wrapper_installed: { + type: "boolean", + description: + "Whether the Warehouse foreign data wrapper exists in the project database", + examples: [true], + }, + server_configured: { + type: "boolean", + description: + "Whether the Warehouse foreign server exists in the project database", + examples: [true], + }, + schema_created: { + type: "boolean", + description: + "Whether the local Warehouse schema exists in the project database", + examples: [true], + }, + foreign_schema_imported: { + type: "boolean", + description: + "Whether the Warehouse foreign schema import has exposed the Warehouse snapshots table", + examples: [true], + }, + }, + required: [ + "extension_available", + "extension_installed", + "wrapper_installed", + "server_configured", + "schema_created", + "foreign_schema_imported", + ], + description: + "Project database FDW setup markers; null during or after teardown, when setup inspection is inapplicable.", + }, + status: { + type: "string", + enum: ["running", "succeeded", "failed"], + description: + "Current enablement readiness. Success requires initial copy, a running pipeline and ready routing; this is not a historical operation result or a query connectivity check.", + }, + status_error: { + description: + "Reason current enablement readiness failed. Separate from Studio setup or cleanup errors.", + type: "string", + }, + replication_state: { + type: "string", + }, + }, + required: [ + "setup_status", + "steps", + "tables", + "fdw_status", + "status", + "replication_state", + ], + }, + }, + required: ["type", "id", "attributes"], + }, + }, + required: ["data"], + }, + }, +} as const satisfies Readonly>; diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts new file mode 100644 index 0000000000..2262ba47b3 --- /dev/null +++ b/apps/cli/src/commands/api/generated.ts @@ -0,0 +1,178 @@ +// Generated by scripts/generate-api-commands.ts. Do not edit. +import type { ApiCommandEntry } from "./api-command.model.ts"; + +export const apiCommands = [ + { + command: ["warehouse", "enable"], + operationId: "v2-enable-warehouse", + definition: "v2EnableWarehouse", + method: "POST", + apiPath: "/v2/projects/{ref}/warehouse/enable", + summary: "Enable Warehouse replication", + description: + "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.\n\nThis endpoint is currently in its **Alpha** stage.", + scope: "project", + readOnly: false, + stability: "experimental", + feature: "warehouse", + body: { + contentType: "application/json", + kind: "json-envelope", + type: "warehouse_setup", + }, + response: { + status: 202, + kind: "json", + }, + flags: [ + { + name: "warehouse-region", + type: "string", + repeatable: false, + required: false, + description: + "Optional Warehouse compute region, independent of the source and catalog regions. Defaults to the existing assignment, or ap-southeast-1 in staging and eu-west-1 in production for a new assignment. DNS routing requires a registered cluster in that environment. Unsupported regions and changes to an existing assignment are rejected. Ignored when targets is empty.", + }, + { + name: "destination-project-ref", + type: "string", + repeatable: false, + required: false, + description: + "Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. Defaults to this project on first setup and to the configured destination on later requests. The destination must be active and healthy, and another project requires SQL and Storage admin write permissions. An existing destination cannot be changed through setup. Ignored when targets is empty.", + }, + { + name: "install-fdw", + type: "boolean", + repeatable: false, + required: false, + description: + "Whether to configure and install the Warehouse FDW in the project database. Defaults to false. Ignored when targets is empty.", + }, + { + name: "schema", + type: "string", + repeatable: false, + required: true, + description: + "Source PostgreSQL schema. Without tables, selects its currently eligible tables only.", + }, + { + name: "table", + type: "string", + repeatable: true, + required: false, + description: + "Table names in schema. Omit to select the currently eligible tables in that schema.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "body", + name: "warehouse_region", + pointer: "/data/attributes/warehouse_region", + source: "flag", + flag: "warehouse-region", + }, + { + location: "body", + name: "destination_project_ref", + pointer: "/data/attributes/destination_project_ref", + source: "flag", + flag: "destination-project-ref", + }, + { + location: "body", + name: "install_fdw", + pointer: "/data/attributes/install_fdw", + source: "flag", + flag: "install-fdw", + }, + { + location: "body", + name: "schema", + pointer: "/data/attributes/schema", + source: "flag", + flag: "schema", + }, + { + location: "body", + name: "tables", + pointer: "/data/attributes/tables", + source: "flag", + flag: "table", + }, + ], + wait: { + read: "v2-get-warehouse-setup", + params: { + selection_id: "/data/attributes/selection_id", + }, + status: "/data/attributes/status", + succeeded: ["succeeded"], + failed: ["failed"], + error: "/data/attributes/status_error", + }, + }, + { + command: ["warehouse", "status"], + operationId: "v2-get-warehouse-setup", + definition: "v2GetWarehouseSetup", + method: "GET", + apiPath: "/v2/projects/{ref}/warehouse/setups/current", + summary: "Get Warehouse initial synchronization status", + description: + "Returns setup phases, linked tables, pipeline and routing state, cleanup errors, and optional FDW inspection. Set inspect_fdw=false to skip database FDW inspection. A null table replication_state means no observation is available. Status succeeded requires initial copy, a running pipeline and ready routing; it does not verify query connectivity. Pass the selection_id returned by enable to reject a changed selection while waiting.\n\nThis endpoint is currently in its **Alpha** stage.", + scope: "project", + readOnly: true, + stability: "experimental", + feature: "warehouse", + response: { + status: 200, + kind: "json", + }, + flags: [ + { + name: "inspect-fdw", + type: "string", + choices: ["true", "false"], + repeatable: false, + required: false, + description: + "Inspect database FDW state. Defaults to true for current-status reads and false when selection_id is supplied.", + }, + { + name: "selection-id", + type: "string", + repeatable: false, + required: false, + description: + "Accepted selection identity returned by enable. A different current nonempty selection returns a conflict.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "query", + name: "inspect_fdw", + source: "flag", + flag: "inspect-fdw", + }, + { + location: "query", + name: "selection_id", + source: "flag", + flag: "selection-id", + }, + ], + }, +] as const satisfies readonly ApiCommandEntry[]; diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts new file mode 100644 index 0000000000..187dd79cc2 --- /dev/null +++ b/apps/cli/src/commands/api/runtime.ts @@ -0,0 +1,271 @@ +import { Effect, Layer, Option } from "effect"; +import { Command, Flag } from "effect/cli"; + +import { withPermissions } from "../../command-internal/command-permissions/command-permissions.annotation.ts"; +import { compose, type OperationEntry } from "../../command-internal/command-permissions/model.ts"; +import { parseDuration } from "../../command-internal/duration.ts"; +import { OutputFlag } from "../../command-internal/global-flags.ts"; +import { requireHostedMutationConsent } from "../../command-internal/hosted-consent/hosted-consent.ts"; +import { managementApiRuntimeLayer } from "../../command-internal/management-api-runtime.layer.ts"; +import { branchResolution } from "../../command-internal/target/branch-resolution.ts"; +import { resolveProjectTarget } from "../../command-internal/target/resolve-project-target.ts"; +import { projectTargetFlags } from "../../command-internal/target/target-flags.ts"; +import { withTargetPolicy } from "../../command-internal/target/target-policy.ts"; +import { projectRefPicker } from "../../config/project-ref.layer.ts"; +import { stdinLayer } from "../../shared/runtime/stdin.layer.ts"; +import { withCommandTelemetry } from "../../telemetry/command-telemetry.ts"; +import { LinkedProjectCache } from "../../telemetry/linked-project-cache.service.ts"; +import { linkedProjectCache } from "../../telemetry/linked-project-cache.layer.ts"; +import { TelemetryState } from "../../telemetry/telemetry-state.service.ts"; +import { + type ApiOutputFormat, + sendApiRequest, + waitForOperation, + writeApiResponse, + writeDocument, +} from "./api-command-execute.ts"; +import { apiFlag } from "./api-command-flags.ts"; +import { + assembleInput, + decodeInput, + previewRequest, + readBodyOverride, +} from "./api-command-request.ts"; +import { type CommandStage, enforceStage, withCommandStage } from "./api-command-stage.ts"; +import { withApiCommand } from "./api-command.annotation.ts"; +import { ApiCommandUsageError } from "./api-command.errors.ts"; +import type { ApiCommandEntry } from "./api-command.model.ts"; +import { apiCommands } from "./generated.ts"; +import { withStandardErrors } from "../../command-internal/command-errors/command-errors.annotation.ts"; +import { nouns } from "./api-command-names.ts"; + +const DEFAULT_WAIT_TIMEOUT = "10m"; +const NANOSECONDS_PER_MILLISECOND = 1_000_000; + +const stageOf = (entry: ApiCommandEntry): CommandStage => ({ + status: "experimental", + gate: + entry.feature === undefined ? { kind: "flag" } : { kind: "feature", feature: entry.feature }, +}); + +/** The flag config of a generated command: target flags, runtime flags and one flag per API field. */ +const flagConfig = (entry: ApiCommandEntry) => ({ + ...projectTargetFlags(), + ...(entry.body === undefined + ? {} + : { + body: Flag.optional( + Flag.String("body").pipe( + Flag.withDescription( + "Whole request body as JSON; other flags replace fields at their own location.", + ), + ), + ), + file: Flag.optional( + Flag.String("file").pipe( + Flag.withDescription("Read the whole request body from a JSON file, or - for stdin."), + ), + ), + }), + dryRun: Flag.Boolean("dry-run").pipe( + Flag.withDescription("Print the request that would be sent and send nothing."), + Flag.withDefault(false), + ), + ...(entry.wait === undefined + ? {} + : { + wait: Flag.Boolean("wait").pipe( + Flag.withDescription("Wait until the operation reaches a final status."), + Flag.withDefault(false), + ), + timeout: Flag.String("timeout").pipe( + Flag.withDescription("How long --wait polls, as a duration such as 90s or 10m."), + Flag.withDefault(DEFAULT_WAIT_TIMEOUT), + ), + }), + api: Object.fromEntries(entry.flags.map((flag) => [flag.name, apiFlag(flag)])), +}); + +const parseTimeoutMillis = (value: string) => + Effect.try({ + try: () => parseDuration(value) / NANOSECONDS_PER_MILLISECOND, + catch: () => + new ApiCommandUsageError({ + message: `--timeout ${value} is not a valid duration.`, + hint: "Use a duration such as 90s or 10m.", + }), + }).pipe( + Effect.filterOrFail( + (millis) => millis > 0, + () => + new ApiCommandUsageError({ + message: `--timeout ${value} must be greater than zero.`, + hint: "Use a duration such as 90s or 10m.", + }), + ), + ); + +const consentAction = (entry: ApiCommandEntry): string => entry.summary.replace(/\.$/, ""); + +const OUTPUT_FORMATS: ReadonlyArray = ["json", "yaml"]; + +/** The parsed flags of a generated command. */ +interface ApiCommandFlags { + readonly remote: Parameters[0]["remote"]; + readonly projectRef: Parameters[0]["projectRef"]; + readonly body?: Option.Option; + readonly file?: Option.Option; + readonly dryRun: boolean; + readonly wait?: boolean; + readonly timeout?: string; + readonly api: Parameters[2]; +} + +/** Runs one generated command: assemble and validate the request, consent, send, optionally wait, print. */ +const handle = Effect.fn("api-command.run")(function* ( + entry: ApiCommandEntry, + flags: ApiCommandFlags, +) { + yield* Effect.annotateCurrentSpan("operation.id", entry.operationId); + const telemetryState = yield* TelemetryState; + const cache = yield* LinkedProjectCache; + const outputFlag = yield* OutputFlag; + const format: ApiOutputFormat = Option.getOrUndefined(outputFlag) === "yaml" ? "yaml" : "json"; + yield* Effect.gen(function* () { + yield* enforceStage(stageOf(entry)); + const ref = yield* resolveProjectTarget(flags); + yield* Effect.gen(function* () { + const timeoutMillis = + entry.wait !== undefined && flags.wait === true + ? yield* parseTimeoutMillis(flags.timeout ?? DEFAULT_WAIT_TIMEOUT) + : 0; + const override = yield* readBodyOverride({ + body: flags.body ?? Option.none(), + file: flags.file ?? Option.none(), + }); + const input = yield* assembleInput(entry, ref, flags.api, override); + const decoded = yield* decodeInput(entry, input); + + if (flags.dryRun) { + yield* Effect.annotateCurrentSpan("run.outcome", "dry_run"); + return yield* writeDocument(previewRequest(entry, decoded, flags.api), format); + } + if (!entry.readOnly) { + yield* requireHostedMutationConsent({ action: consentAction(entry) }); + } + + const response = yield* sendApiRequest(entry, decoded); + if (entry.wait !== undefined && flags.wait === true) { + const settled = yield* waitForOperation({ + wait: entry.wait, + changedEntry: entry, + ref, + changed: response, + timeoutMillis, + }); + yield* Effect.annotateCurrentSpan( + "run.outcome", + settled.entry === entry ? "wait_skipped" : "waited", + ); + return yield* writeApiResponse(settled.entry, settled.response, format); + } + yield* Effect.annotateCurrentSpan("run.outcome", "sent"); + return yield* writeApiResponse(entry, response, format); + }).pipe(Effect.ensuring(cache.cache(ref))); + }).pipe(Effect.ensuring(telemetryState.flush)); +}); + +const exampleFor = (entry: ApiCommandEntry): string => { + const required = entry.flags + .filter((flag) => flag.required) + .map((flag) => `--${flag.name}${flag.type === "boolean" ? "" : ` <${flag.name}>`}`); + return ["supabase", ...entry.command, ...required].join(" "); +}; + +const permissionsOf = (entry: ApiCommandEntry) => { + const operations: ReadonlyArray = [ + { operationId: entry.operationId, kind: "required" }, + ...(entry.wait === undefined + ? [] + : [ + { + operationId: entry.wait.read, + kind: "required" as const, + when: [{ flag: "wait", is: true }], + }, + ]), + ]; + const noApiEffectFlags = [ + "dry-run", + ...(entry.body === undefined ? [] : ["body", "file"]), + ...(entry.wait === undefined ? [] : ["timeout"]), + ...entry.flags.map((flag) => flag.name), + ]; + return compose( + { operations, noApiEffectFlags }, + projectRefPicker, + linkedProjectCache, + branchResolution, + ); +}; + +const leafOf = (entry: ApiCommandEntry) => { + const verb = entry.command[entry.command.length - 1] ?? entry.operationId; + const config = flagConfig(entry); + return Command.make(verb, config).pipe( + Command.withDescription(entry.description ?? entry.summary), + Command.withShortDescription(`${entry.summary} (experimental)`), + Command.withExamples([{ command: exampleFor(entry), description: entry.summary }]), + withApiCommand({ + operationId: entry.operationId, + bindings: entry.bindings, + response: entry.response, + }), + withPermissions(permissionsOf(entry)), + withCommandStage(stageOf(entry)), + withStandardErrors, + Command.withHandler((flags) => { + const { api: _generated, ...recorded } = flags; + return handle(entry, flags).pipe( + withCommandTelemetry({ flags: recorded, outputFormats: OUTPUT_FORMATS }), + ); + }), + // `stdinLayer`: `--file -` reads the request body from piped stdin. + Command.provide(Layer.mergeAll(managementApiRuntimeLayer(entry.command), stdinLayer)), + withTargetPolicy({ group: "hosted", consent: entry.readOnly ? "none" : "no" }), + ); +}; + +/** The command group of `noun`, with one leaf per entry whose command path sits under it. */ +export const apiCommandGroup = ( + noun: string, + description: string, + entries: ReadonlyArray, +) => { + const leaves = entries + .filter((entry) => entry.command.slice(0, -1).join(".") === noun) + .map(leafOf); + return Command.make(noun).pipe( + Command.withDescription(`${description} (experimental)`), + Command.withShortDescription(`${description} (experimental)`), + Command.withSubcommands(leaves), + ); +}; + +const groupCache = new Map>(); + +/** + * The noun groups of the generated Management API commands, one per noun whose feature is + * enabled (or that has no feature); a group is built on first use. + */ +export const apiCommandGroups = (enabledFeatures: ReadonlyArray) => + Object.entries(nouns).flatMap(([noun, definition]) => { + if (definition.feature !== undefined && !enabledFeatures.includes(definition.feature)) { + return []; + } + const cached = groupCache.get(noun); + if (cached !== undefined) return [cached]; + const group = apiCommandGroup(noun, definition.description, apiCommands); + groupCache.set(noun, group); + return [group]; + }); diff --git a/apps/cli/src/commands/api/warehouse-backend.ts b/apps/cli/src/commands/api/warehouse-backend.ts new file mode 100644 index 0000000000..96868e80cb --- /dev/null +++ b/apps/cli/src/commands/api/warehouse-backend.ts @@ -0,0 +1,35 @@ +import { Effect, FileSystem, Path } from "effect"; + +import { extractCommandPath, hasRootVersionFlag } from "../../shared/cli/run.ts"; +import { + type ExperimentalFeatureFlagError, + readExperimentalFeatureConfig, + resolveExperimentalFeature, +} from "../../shared/config/experimental-feature.ts"; + +/** Resolves `experimental.warehouse` only for invocations that can reach the `warehouse` group. */ +export const resolveWarehouseEnabled = (input: { + readonly args: ReadonlyArray; + readonly cwd: string; +}): Effect.Effect => + Effect.gen(function* () { + const routingArgs = + input.args[0] === "__complete" || input.args[0] === "__completeNoDesc" + ? input.args.slice(0, -1) + : input.args; + if (hasRootVersionFlag(routingArgs)) return false; + const commandPath = extractCommandPath(routingArgs); + const completePath = + commandPath[0] === "__complete" || commandPath[0] === "__completeNoDesc" + ? commandPath.slice(1) + : commandPath; + if (completePath[0] !== undefined && completePath[0] !== "warehouse") return false; + return yield* resolveExperimentalFeature({ + feature: "warehouse", + configValue: readExperimentalFeatureConfig({ + feature: "warehouse", + ...input, + args: routingArgs, + }), + }); + }); diff --git a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md new file mode 100644 index 0000000000..3473fe7b27 --- /dev/null +++ b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md @@ -0,0 +1,86 @@ +# `supabase warehouse enable` + +Target: hosted, consent `no` (confirm unless `--yes`; a non-interactive run without `--yes` is a usage error), see [Command target](../../../../../docs/command-target.md) + +## Feature gate + +Registered only when `experimental.warehouse` is enabled: set `[experimental] warehouse = true` or +`SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. `--experimental` alone does not expose it. When disabled the +`warehouse` group is absent from help and completion and from the generated command documentation. +The command is generated from the Management API contract (`generated.ts`). + +## Files Read + +| Path | Format | When | +| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | +| `/supabase/config.json` | JSON | when present, to resolve `experimental.warehouse` before the command tree is built | +| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | +| `` | JSON | only with `--file `: the whole request body (`--file -` reads stdin) | +| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential | +| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | +| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | + +## Files Written + +| Path | Format | When | +| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | +| `/telemetry.json` | JSON | always, flushed on success and on failure | +| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref | + +## API Routes + +| Method | Path | Auth | Request body | Response (used fields) | +| ------ | --------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `POST` | `/v2/projects/{ref}/warehouse/enable` | Bearer token | `{"data":{"type":"warehouse_setup","attributes":{…}}}`; only the flags that were given are present | passed through unchanged; `data.attributes.selection_id` feeds `--wait` | +| `GET` | `/v2/projects/{ref}/warehouse/setups/current` | Bearer token | none | `data.attributes.status`, `status_error`; polled with backoff from 1s doubling to a 10s cap (a longer `Retry-After` wins), only with `--wait` | +| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive (project picker) | + +`--body` or `--file` supply the whole body; a flag replaces its own field and nothing else. The +input is validated before consent and before any request, so a top-level body key outside the +declared request-body fields, an unknown nested field or a missing `--schema` fails with nothing sent. `--dry-run` prints `{method, path, query, body}` and sends +nothing, before consent. + +## Exit Codes + +| Code | Condition | +| ----- | ------------------------------------------------------------------------ | +| `0` | success (the request was accepted, or with `--wait` the setup succeeded) | +| `2` | `usage_error`: invalid flags or body, or consent needed without `--yes` | +| `130` | consent declined at the prompt (`cancelled`) | +| `1` | API error (non-2xx) | +| `1` | with `--wait`: `operation_failed` (failed status) or `wait_timeout` | + +## Environment Variables + +| Variable | Purpose | Required? | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | +| `SUPABASE_EXPERIMENTAL_WAREHOUSE` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.warehouse`) | no | +| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | +| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | +| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to `supabase/.temp/project-ref`) | +| `SUPABASE_WORKDIR` | project directory the command acts on | no (falls back to `--workdir`, then the cwd) | +| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) | + +## Telemetry Events Fired + +| Event | When | Notable properties / groups | +| ---------------------- | ------------------------------------------ | ----------------------------------- | +| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | + +Generated flag values are never recorded; only the target flags and the `--dry-run`, `--wait` +and `--timeout` runtime flags appear in `flags`. + +## Output + +| Mode | stdout | +| -------------- | --------------------------------------------------------------------------------- | +| text (default) | the API's JSON response bytes, unchanged; with `--wait` the final status response | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML; other `-o` values are a usage error | +| `--dry-run` | the request preview as JSON | + +## Notes + +- Repeating the same selection is safe; the API rejects a different existing selection. +- A response without `data.attributes.selection_id` is printed as is, without waiting. +- `--wait` never resumes after a 409; any non-2xx while polling ends the command with the API error. diff --git a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md new file mode 100644 index 0000000000..07781913ed --- /dev/null +++ b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md @@ -0,0 +1,74 @@ +# `supabase warehouse status` + +Target: hosted, no consent, see [Command target](../../../../../docs/command-target.md) + +## Feature gate + +Registered only when `experimental.warehouse` is enabled: set `[experimental] warehouse = true` or +`SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. `--experimental` alone does not expose it. When disabled the +`warehouse` group is absent from help and completion and from the generated command documentation. +The command is generated from the Management API contract (`generated.ts`). + +## Files Read + +| Path | Format | When | +| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | +| `/supabase/config.json` | JSON | when present, to resolve `experimental.warehouse` before the command tree is built | +| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | +| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential | +| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | +| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | + +## Files Written + +| Path | Format | When | +| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | +| `/telemetry.json` | JSON | always, flushed on success and on failure | +| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref | + +## API Routes + +| Method | Path | Auth | Request body | Response (used fields) | +| ------ | --------------------------------------------- | ------------ | ------------ | -------------------------------------------------------- | +| `GET` | `/v2/projects/{ref}/warehouse/setups/current` | Bearer token | none | passed through unchanged | +| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive | + +Query: `inspect_fdw=true|false` and `selection_id=`, each only when its flag was given. +`--dry-run` prints `{method, path, query, body}` and sends nothing. + +## Exit Codes + +| Code | Condition | +| ---- | ---------------------------------- | +| `0` | success | +| `2` | `usage_error`: invalid flags | +| `1` | API error (non-2xx, including 409) | + +## Environment Variables + +| Variable | Purpose | Required? | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | +| `SUPABASE_EXPERIMENTAL_WAREHOUSE` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.warehouse`) | no | +| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | +| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | +| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to `supabase/.temp/project-ref`) | +| `SUPABASE_WORKDIR` | project directory the command acts on | no (falls back to `--workdir`, then the cwd) | +| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) | + +## Telemetry Events Fired + +| Event | When | Notable properties / groups | +| ---------------------- | ------------------------------------------ | ----------------------------------- | +| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | + +Generated flag values are never recorded; only the target flags and the `--dry-run`, `--wait` +and `--timeout` runtime flags appear in `flags`. + +## Output + +| Mode | stdout | +| -------------- | ---------------------------------------- | +| text (default) | the API's JSON response bytes, unchanged | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML | +| `--dry-run` | the request preview as JSON | diff --git a/apps/cli/src/config/cli-config-flag-ownership.unit.test.ts b/apps/cli/src/config/cli-config-flag-ownership.unit.test.ts index 9574efc248..3862db6796 100644 --- a/apps/cli/src/config/cli-config-flag-ownership.unit.test.ts +++ b/apps/cli/src/config/cli-config-flag-ownership.unit.test.ts @@ -14,7 +14,7 @@ const declarations: ReadonlyArray<{ path: string; names: ReadonlyArray } const ownerOf = new Map(declarations.flatMap(({ path, names }) => names.map((n) => [n, path]))); const commands = walkCommandTree( - rootCommandForFeatures({ stackBackend: "stack", computeEnabled: true }), + rootCommandForFeatures({ stackBackend: "stack", computeEnabled: true, warehouseEnabled: true }), ); const ownedFlags = commands.flatMap((entry) => diff --git a/apps/cli/src/shared/cli/agent-output.ts b/apps/cli/src/shared/cli/agent-output.ts index 87f9316aaa..428ae6f6b0 100644 --- a/apps/cli/src/shared/cli/agent-output.ts +++ b/apps/cli/src/shared/cli/agent-output.ts @@ -17,7 +17,7 @@ interface AgentOutputOptions { readonly isBuiltInTextRequest?: boolean; } -function readLongFlag(args: ReadonlyArray, name: string): string | undefined { +export function readLongFlag(args: ReadonlyArray, name: string): string | undefined { const prefix = `${name}=`; for (let i = 0; i < args.length; i++) { const arg = args[i]; @@ -33,7 +33,7 @@ function readLongFlag(args: ReadonlyArray, name: string): string | undef } } -function readOutputFlag(args: ReadonlyArray): string | undefined { +export function readOutputFlag(args: ReadonlyArray): string | undefined { for (let i = 0; i < args.length; i++) { const arg = args[i]; if (arg === undefined) { diff --git a/apps/cli/src/shared/cli/run.ts b/apps/cli/src/shared/cli/run.ts index 74a648b875..d9af96f4b3 100644 --- a/apps/cli/src/shared/cli/run.ts +++ b/apps/cli/src/shared/cli/run.ts @@ -45,7 +45,7 @@ import { ttyLayer } from "../runtime/tty.layer.ts"; import { CommandRuntime } from "../runtime/command-runtime.service.ts"; import { ProcessControl } from "../runtime/process-control.service.ts"; import type { RuntimeInfo } from "../runtime/runtime-info.service.ts"; -import type { Tty } from "../runtime/tty.service.ts"; +import { Tty } from "../runtime/tty.service.ts"; import type { Analytics } from "../telemetry/analytics.service.ts"; import { aiToolLayer } from "../telemetry/ai-tool.layer.ts"; import { AiTool } from "../telemetry/ai-tool.service.ts"; @@ -72,6 +72,13 @@ import { } from "./remote-argv.ts"; import { SuccessTrailer, successTrailerLayer } from "./success-trailer.ts"; import type { CliErrorSuggestionContext } from "./subcommand-flag-suggestions.ts"; +import { + errorsContractForRun, + isMachineFailureMode, + standardFailureFor, + writeStandardFailure, + type PendingStandardFailure, +} from "./standard-errors.ts"; import { flagAliasesFor, isRemoteFlagMisuse, @@ -705,7 +712,16 @@ export function cliProgramFor< class CliNonZeroExit { readonly _tag = "CliNonZeroExit"; readonly name = "CliNonZeroExit"; - constructor(readonly code: number) {} + constructor( + readonly code: number, + readonly pending?: PendingStandardFailure, + ) {} +} + +/** How a run ends: its exit code, plus a standard failure still to be written before exit. */ +interface RunOutcome { + readonly exitCode: number; + readonly pending?: PendingStandardFailure; } export const runCli = Effect.fnUntraced(function* < @@ -730,6 +746,8 @@ export const runCli = Effect.fnUntraced(function* < // Same shape `formatterLayerFor` builds below, so `normalizeCause`'s fallback path can reuse // `formatCliErrorsForDisplay` and surface the same subcommand-flag hint the formatters would. const suggestionContext = suggestionContextFor(rootCommand, args, options.stackRootCommand); + const usesStandardErrors = + errorsContractForRun(rootCommand, extractCommandPath(args)) === "standard"; const useGlobalSignalInterrupt = shouldUseGlobalSignalInterrupt(args); const outputFormat = yield* Effect.gen(function* () { const aiTool = yield* AiTool; @@ -832,41 +850,60 @@ export const runCli = Effect.fnUntraced(function* < const cause = failureBesideClosedStdout(exit.cause); if (cause === undefined) { // The reader is gone, so there is nobody left for a report, a notice, or a trailer. - return (yield* processControl.getExitCode) ?? 0; + return { exitCode: (yield* processControl.getExitCode) ?? 0 } satisfies RunOutcome; } const exitCode = exitCodeForFailure(cause); + if (usesStandardErrors && exitCode !== 0) { + const tty = yield* Tty; + const mapped = standardFailureFor(cause, suggestionContext); + return { + exitCode: mapped.exitCode, + pending: { ...mapped, machine: isMachineFailureMode(args, tty.stdoutIsTty) }, + } satisfies RunOutcome; + } // See `shouldReportFailure` and `exitCodeForFailure` for the exit-code/reporting rules; a // literal `--help` never reaches this branch — it exits 0 via the success path below. if (shouldReportFailure(exitCode)) { yield* ignoreStdoutClosed(output.fail(normalizeCause(cause, suggestionContext))); } yield* afterSuccess(exitCode, true); - return exitCode; + return { exitCode } satisfies RunOutcome; } const exitCode = yield* processControl.getExitCode; yield* afterSuccess(exitCode ?? 0, false); - return exitCode ?? 0; + return { exitCode: exitCode ?? 0 } satisfies RunOutcome; }).pipe(Effect.provide(runToExitCodeLayer)); // The exit code is resolved inside the traced scope so its flush completes before - // `processControl.exit`, which skips finalizers. + // `processControl.exit`, which skips finalizers. A standard failure is written after that scope + // closes, so its document is the last thing on stderr. const handledProgram = (program: Effect.Effect) => Effect.gen(function* () { const processControl = yield* ProcessControl; - const exitCode = yield* resolveTraceSettings.pipe( + const outcome: RunOutcome = yield* resolveTraceSettings.pipe( Effect.flatMap((settings) => withTraceExport(settings, { "process.boot_ms": bootMs })( runToExitCode(program).pipe( - Effect.tap((code) => Effect.annotateCurrentSpan("process.exit_code", code)), - Effect.flatMap((code) => - code === 0 ? Effect.succeed(code) : Effect.fail(new CliNonZeroExit(code)), + Effect.tap((result) => + Effect.annotateCurrentSpan("process.exit_code", result.exitCode), + ), + Effect.flatMap((result) => + result.exitCode === 0 + ? Effect.succeed(result) + : Effect.fail(new CliNonZeroExit(result.exitCode, result.pending)), ), ), ), ), - Effect.catchTag("CliNonZeroExit", (failure) => Effect.succeed(failure.code)), + Effect.catchTag("CliNonZeroExit", (failure) => + Effect.succeed({ + exitCode: failure.code, + ...(failure.pending === undefined ? {} : { pending: failure.pending }), + }), + ), ); - return yield* processControl.exit(exitCode); + if (outcome.pending !== undefined) yield* writeStandardFailure(outcome.pending); + return yield* processControl.exit(outcome.exitCode); }).pipe( Effect.withTracerEnabled(false), Effect.provideService(HttpClient.TracerPropagationEnabled, false), diff --git a/apps/cli/src/shared/cli/standard-errors.integration.test.ts b/apps/cli/src/shared/cli/standard-errors.integration.test.ts new file mode 100644 index 0000000000..e78c351330 --- /dev/null +++ b/apps/cli/src/shared/cli/standard-errors.integration.test.ts @@ -0,0 +1,153 @@ +import { BunServices } from "@effect/platform-bun"; +import { describe, expect, it } from "@effect/vitest"; +import { Effect, FileSystem, Schema, Stream } from "effect"; +import { ChildProcess, ChildProcessSpawner } from "effect/process"; +import { fileURLToPath } from "node:url"; + +const FIXTURE = fileURLToPath( + new URL("../../../tests/fixtures/standard-errors-cli.ts", import.meta.url), +); + +/** + * `runCli` ends with `process.exit`, so the exit code and the stderr ordering are only observable + * from a subprocess running the fixture CLI through the real run path. + */ +const runFixture = Effect.fn("StandardErrorsTest.run")(function* ( + args: ReadonlyArray, + env: Record = {}, +) { + const fs = yield* FileSystem.FileSystem; + const home = yield* fs.makeTempDirectoryScoped({ prefix: "supabase-standard-errors-" }); + const bun = yield* Effect.fromNullishOr(Bun.which("bun")); + const spawner = yield* ChildProcessSpawner.ChildProcessSpawner; + const child = yield* spawner.spawn( + ChildProcess.make(bun, [FIXTURE, ...args], { + env: { + SUPABASE_HOME: home, + SUPABASE_NO_KEYRING: "1", + SUPABASE_TELEMETRY_DISABLED: "1", + SUPABASE_NO_UPDATE_NOTIFIER: "1", + ...env, + }, + extendEnv: true, + stdin: "ignore", + }), + ); + const [exitCode, stdout, stderr] = yield* Effect.all( + [ + child.exitCode, + Stream.mkString(Stream.decodeText(child.stdout)), + Stream.mkString(Stream.decodeText(child.stderr)), + ], + { concurrency: "unbounded" }, + ); + return { exitCode: Number(exitCode), stdout, stderr }; +}, Effect.scoped); + +const lastLine = (text: string) => text.trimEnd().split("\n").at(-1) ?? ""; +const decodeJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown)); + +describe("errors.standard failure contract", () => { + it.live("reports an API conflict as the last stderr line and nothing on stdout", () => + Effect.gen(function* () { + const { exitCode, stdout, stderr } = yield* runFixture(["conflict", "-o", "json"]); + expect(stdout).toBe(""); + expect(exitCode).toBe(1); + expect(stderr.endsWith("\n")).toBe(true); + expect(yield* decodeJson(lastLine(stderr))).toEqual({ + code: "conflict", + status: 409, + message: "Resource already exists", + hint: "Pick another name", + api_code: "already_exists", + }); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.live( + "a run that cannot ask for consent is a usage error telling the caller to pass --yes", + () => + Effect.gen(function* () { + const { exitCode, stdout, stderr } = yield* runFixture(["needs-consent"]); + expect(stdout).toBe(""); + expect(exitCode).toBe(2); + expect(yield* decodeJson(lastLine(stderr))).toMatchObject({ + code: "usage_error", + hint: "Pass --yes", + }); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.live("conflicting target selectors are a usage error that keeps the suggestion", () => + Effect.gen(function* () { + const { exitCode, stdout, stderr } = yield* runFixture([ + "select", + "--remote=abcdefghijklmnopqrst", + "--project-ref", + "tsrqponmlkjihgfedcba", + ]); + expect(stdout).toBe(""); + expect(exitCode).toBe(2); + expect(yield* decodeJson(lastLine(stderr))).toMatchObject({ + code: "usage_error", + message: expect.stringContaining("--project-ref cannot be combined with --remote"), + hint: expect.stringContaining("--remote"), + }); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.live("a declined confirmation exits 130 as cancelled", () => + Effect.gen(function* () { + const { exitCode, stderr } = yield* runFixture(["declined"]); + expect(exitCode).toBe(130); + expect(yield* decodeJson(lastLine(stderr))).toMatchObject({ code: "cancelled" }); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.live("an unknown flag is a usage error after the help text", () => + Effect.gen(function* () { + const { exitCode, stdout, stderr } = yield* runFixture(["conflict", "--nope"]); + expect(stdout).toBe(""); + expect(exitCode).toBe(2); + expect(stderr).toContain("USAGE"); + expect(yield* decodeJson(lastLine(stderr))).toMatchObject({ + code: "usage_error", + message: expect.stringContaining("--nope"), + }); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.live("a defect is an internal error", () => + Effect.gen(function* () { + const { exitCode, stderr } = yield* runFixture(["crash"]); + expect(exitCode).toBe(1); + expect(yield* decodeJson(lastLine(stderr))).toMatchObject({ code: "internal_error" }); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.live("a terminal run prints the message and hint as text with the same exit code", () => + Effect.gen(function* () { + const { exitCode, stdout, stderr } = yield* runFixture(["conflict"], { + STANDARD_ERRORS_FIXTURE_TTY: "1", + }); + expect(stdout).toBe(""); + expect(exitCode).toBe(1); + expect(stderr).toContain("Resource already exists"); + expect(lastLine(stderr)).toBe("Pick another name"); + expect(stderr).not.toContain('"code"'); + }).pipe(Effect.provide(BunServices.layer)), + ); +}); + +describe("commands without the standard marker", () => { + it.live("keep the legacy JSON envelope on stdout and exit 1", () => + Effect.gen(function* () { + const { exitCode, stdout, stderr } = yield* runFixture(["legacy", "--output-format", "json"]); + expect(exitCode).toBe(1); + expect(stdout).toBe( + '{"_tag":"Error","error":{"code":"LegacyBoomError","message":"legacy boom"}}\n', + ); + expect(stderr).toBe(""); + }).pipe(Effect.provide(BunServices.layer)), + ); +}); diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts new file mode 100644 index 0000000000..faeed3e7cc --- /dev/null +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -0,0 +1,241 @@ +import { styleText } from "node:util"; + +import { Cause, Effect, Option, Predicate, Stdio } from "effect"; +import { CliError, type Command } from "effect/cli"; +import * as HttpClientError from "effect/http/HttpClientError"; +import { InvalidAccessTokenError, AccessTokenRequiredError } from "../../auth/errors.ts"; +import { + readCommandErrorsContract, + type CommandErrorsContract, +} from "../../command-internal/command-errors/command-errors.annotation.ts"; +import { + HostedMutationConsentRequiredError, + HostedMutationDeclinedError, +} from "../../command-internal/hosted-consent/hosted-consent.errors.ts"; +import { + ApiCommandOperationFailedError, + ApiCommandStatusError, + ApiCommandUsageError, + ApiCommandWaitTimeoutError, +} from "../../commands/api/api-command.errors.ts"; +import { normalizeCause } from "../output/normalize-error.ts"; +import { writeStdio } from "../output/output.layer.ts"; +import { + classifyCliErrorActionability, + CliErrorCategory, + CliErrorKind, +} from "../telemetry/error-actionability.ts"; +import { isMachineResourceFormat } from "../output/resource-format.ts"; +import { readLongFlag, readOutputFlag } from "./agent-output.ts"; +import { + findCommand, + resolvedCommandPathForArgv, + type CliErrorSuggestionContext, +} from "./subcommand-flag-suggestions.ts"; + +/** The closed set of failure codes an `errors.standard` command reports. */ +type StandardErrorCode = + | "unauthenticated" + | "forbidden" + | "not_found" + | "conflict" + | "rate_limited" + | "invalid_input" + | "api_error" + | "network_error" + | "usage_error" + | "operation_failed" + | "wait_timeout" + | "cancelled" + | "internal_error"; + +/** The failure document an `errors.standard` command writes as the last line of stderr. */ +interface StandardErrorDocument { + readonly code: StandardErrorCode; + readonly status: number | null; + readonly message: string; + readonly hint: string | null; + readonly api_code?: string; + readonly context?: Readonly>; +} + +/** A mapped failure: the process exit code and the document to report. */ +export interface StandardFailure { + readonly exitCode: number; + readonly document: StandardErrorDocument; +} + +/** A standard failure waiting to be written once the run has finished its cleanup. */ +export interface PendingStandardFailure extends StandardFailure { + readonly machine: boolean; +} + +const EXIT_FAILURE = 1; +const EXIT_USAGE = 2; +const EXIT_CANCELLED = 130; + +const documentForStatus = ( + status: number, + message: string, + extras: { readonly apiCode?: string | undefined; readonly hint?: string | undefined }, +): StandardErrorDocument => { + const code: StandardErrorCode = + status === 400 || status === 422 + ? "invalid_input" + : status === 401 + ? "unauthenticated" + : status === 403 + ? "forbidden" + : status === 404 + ? "not_found" + : status === 409 + ? "conflict" + : status === 429 + ? "rate_limited" + : "api_error"; + return { + code, + status, + message, + hint: extras.hint ?? null, + ...(extras.apiCode === undefined ? {} : { api_code: extras.apiCode }), + }; +}; + +const failure = ( + exitCode: number, + code: StandardErrorCode, + message: string, + hint: string | null = null, + extras: Pick = {}, +): StandardFailure => ({ + exitCode, + document: { code, status: null, message, hint, ...extras }, +}); + +const messageOf = (error: unknown, fallback: string): string => + error instanceof Error && error.message.trim().length > 0 ? error.message : fallback; + +const failureForError = ( + error: unknown, + cause: Cause.Cause, + context: CliErrorSuggestionContext | undefined, +): StandardFailure => { + if (Predicate.isTagged(error, "UserError") && "cause" in error && error.cause !== undefined) { + return failureForError(error.cause, cause, context); + } + if (error instanceof ApiCommandStatusError) { + return { + exitCode: EXIT_FAILURE, + document: documentForStatus(error.status, error.message, error), + }; + } + if (error instanceof ApiCommandUsageError) { + return failure(EXIT_USAGE, "usage_error", error.message, error.hint ?? null); + } + if (error instanceof HostedMutationConsentRequiredError) { + return failure(EXIT_USAGE, "usage_error", error.message, "Pass --yes"); + } + if (error instanceof HostedMutationDeclinedError) { + return failure(EXIT_CANCELLED, "cancelled", error.message); + } + if (error instanceof ApiCommandOperationFailedError) { + return failure(EXIT_FAILURE, "operation_failed", error.message, error.hint, { + context: { status: error.status }, + }); + } + if (error instanceof ApiCommandWaitTimeoutError) { + return failure(EXIT_FAILURE, "wait_timeout", error.message, error.hint, { + context: { timeout_ms: error.timeoutMillis }, + }); + } + if (error instanceof AccessTokenRequiredError || error instanceof InvalidAccessTokenError) { + return failure(EXIT_FAILURE, "unauthenticated", error.message); + } + if (Predicate.isTagged(error, "SupabaseApiConfigError")) { + return failure(EXIT_FAILURE, "unauthenticated", messageOf(error, "Missing access token")); + } + if (HttpClientError.isHttpClientError(error)) { + const status = error.response?.status; + return { + exitCode: EXIT_FAILURE, + document: + status === undefined + ? error.reason._tag === "DecodeError" || error.reason._tag === "EmptyBodyError" + ? failure(EXIT_FAILURE, "api_error", error.message).document + : failure(EXIT_FAILURE, "network_error", error.message).document + : documentForStatus(status, error.message, {}), + }; + } + if (CliError.isCliError(error)) { + const normalized = normalizeCause(cause, context); + return failure(EXIT_USAGE, "usage_error", normalized.message, normalized.suggestion ?? null); + } + const declared = classifyCliErrorActionability(error); + if ( + declared.error_kind === CliErrorKind.UserActionable && + declared.error_category === CliErrorCategory.InvalidInput + ) { + const normalized = normalizeCause(cause, context); + return failure(EXIT_USAGE, "usage_error", normalized.message, normalized.suggestion ?? null); + } + return failure(EXIT_FAILURE, "internal_error", normalizeCause(cause).message); +}; + +/** Maps a failure cause to the exit code and document `errors.standard` commands report. */ +export const standardFailureFor = ( + cause: Cause.Cause, + context?: CliErrorSuggestionContext, +): StandardFailure => { + if (Cause.hasInterruptsOnly(cause)) { + return failure(EXIT_CANCELLED, "cancelled", "Interrupted"); + } + const error = Option.getOrElse(Cause.findErrorOption(cause), () => Cause.squash(cause)); + return failureForError(error, cause, context); +}; + +/** The mounted command node a run resolves to: the longest subcommand prefix of the argv's positionals. */ +const resolveCommandNode = ( + rootCommand: Command.Command.Any, + positionals: ReadonlyArray, +): Command.Command.Any | undefined => + findCommand(rootCommand, resolvedCommandPathForArgv(rootCommand, positionals).slice(1)); + +/** The failure contract the run's resolved command node declares. */ +export const errorsContractForRun = ( + rootCommand: Command.Command.Any, + positionals: ReadonlyArray, +): CommandErrorsContract => { + const node = resolveCommandNode(rootCommand, positionals); + return node === undefined ? "legacy" : readCommandErrorsContract(node); +}; + +/** Whether failures render as the JSON document: a machine `-o` or `--output-format`, or stdout that is not a TTY. */ +export const isMachineFailureMode = ( + args: ReadonlyArray, + stdoutIsTty: boolean, +): boolean => { + const outputFormat = readLongFlag(args, "--output-format"); + return ( + !stdoutIsTty || + outputFormat === "json" || + outputFormat === "stream-json" || + isMachineResourceFormat(Option.fromNullishOr(readOutputFlag(args))) + ); +}; + +/** Renders the failure as the stderr text: a leading blank line plus JSON, or a human message and hint. */ +const renderStandardFailure = (pending: PendingStandardFailure): string => { + if (pending.machine) return `\n${JSON.stringify(pending.document)}\n`; + const { message, hint } = pending.document; + return `${styleText("red", message)}\n${hint === null ? "" : `${hint}\n`}`; +}; + +/** Writes the pending failure to stderr; a closed or failing stderr never changes the exit code. */ +export const writeStandardFailure = Effect.fn("StandardErrors.write")(function* ( + pending: PendingStandardFailure, +) { + const stdio = yield* Stdio.Stdio; + yield* writeStdio(stdio, "stderr", renderStandardFailure(pending)).pipe(Effect.ignore); + yield* Effect.annotateCurrentSpan("standard_error.code", pending.document.code); +}); diff --git a/apps/cli/src/shared/cli/standard-errors.unit.test.ts b/apps/cli/src/shared/cli/standard-errors.unit.test.ts new file mode 100644 index 0000000000..a0ae14fd57 --- /dev/null +++ b/apps/cli/src/shared/cli/standard-errors.unit.test.ts @@ -0,0 +1,178 @@ +import { describe, expect, it } from "@effect/vitest"; +import { Cause } from "effect"; +import { CliError } from "effect/cli"; +import * as HttpClientError from "effect/http/HttpClientError"; +import { HttpClientRequest, HttpClientResponse } from "effect/http"; +import { AccessTokenRequiredError } from "../../auth/errors.ts"; +import { InvalidOutputFormatError } from "../../command-internal/output-formats.ts"; +import { TargetSelectorConflictError } from "../../command-internal/target/target.errors.ts"; +import { + HostedMutationConsentRequiredError, + HostedMutationDeclinedError, +} from "../../command-internal/hosted-consent/hosted-consent.errors.ts"; +import { + ApiCommandOperationFailedError, + ApiCommandStatusError, + ApiCommandUsageError, + ApiCommandWaitTimeoutError, +} from "../../commands/api/api-command.errors.ts"; +import { standardFailureFor } from "./standard-errors.ts"; + +const request = HttpClientRequest.get("https://api.example.test/v1/projects"); +const statusError = (status: number) => + new HttpClientError.HttpClientError({ + reason: new HttpClientError.StatusCodeError({ + request, + response: HttpClientResponse.fromWeb(request, new Response("", { status })), + }), + }); +const transportError = new HttpClientError.HttpClientError({ + reason: new HttpClientError.TransportError({ request }), +}); +const apiStatus = (status: number) => + new ApiCommandStatusError({ status, message: `status ${status}`, apiCode: "some_code" }); + +describe("standardFailureFor", () => { + const cases: ReadonlyArray<{ + readonly name: string; + readonly cause: Cause.Cause; + readonly expected: { + readonly exitCode: number; + readonly code: string; + readonly status: number | null; + readonly hint: string | null; + readonly apiCode?: string; + }; + }> = [ + ...[ + [400, "invalid_input"], + [422, "invalid_input"], + [401, "unauthenticated"], + [403, "forbidden"], + [404, "not_found"], + [409, "conflict"], + [429, "rate_limited"], + [500, "api_error"], + [418, "api_error"], + ].map(([status, code]) => ({ + name: `API status ${status}`, + cause: Cause.fail(apiStatus(Number(status))), + expected: { + exitCode: 1, + code: String(code), + status: Number(status), + hint: null, + apiCode: "some_code", + }, + })), + { + name: "API status hint", + cause: Cause.fail( + new ApiCommandStatusError({ status: 409, message: "m", hint: "Rename it" }), + ), + expected: { exitCode: 1, code: "conflict", status: 409, hint: "Rename it" }, + }, + { + name: "API usage error", + cause: Cause.fail(new ApiCommandUsageError({ message: "bad", hint: "Use --name" })), + expected: { exitCode: 2, code: "usage_error", status: null, hint: "Use --name" }, + }, + { + name: "consent required", + cause: Cause.fail(new HostedMutationConsentRequiredError({ message: "m", suggestion: "s" })), + expected: { exitCode: 2, code: "usage_error", status: null, hint: "Pass --yes" }, + }, + { + name: "declined confirmation", + cause: Cause.fail(new HostedMutationDeclinedError({ message: "no" })), + expected: { exitCode: 130, code: "cancelled", status: null, hint: null }, + }, + { + name: "interruption", + cause: Cause.interrupt(), + expected: { exitCode: 130, code: "cancelled", status: null, hint: null }, + }, + { + name: "operation failed", + cause: Cause.fail( + new ApiCommandOperationFailedError({ message: "m", status: "FAILED", hint: "Check it" }), + ), + expected: { exitCode: 1, code: "operation_failed", status: null, hint: "Check it" }, + }, + { + name: "wait timeout", + cause: Cause.fail( + new ApiCommandWaitTimeoutError({ message: "m", timeoutMillis: 5, hint: "Check it" }), + ), + expected: { exitCode: 1, code: "wait_timeout", status: null, hint: "Check it" }, + }, + { + name: "missing access token", + cause: Cause.fail(new AccessTokenRequiredError({ message: "log in" })), + expected: { exitCode: 1, code: "unauthenticated", status: null, hint: null }, + }, + { + name: "client 401 response", + cause: Cause.fail(statusError(401)), + expected: { exitCode: 1, code: "unauthenticated", status: 401, hint: null }, + }, + { + name: "client transport failure", + cause: Cause.fail(transportError), + expected: { exitCode: 1, code: "network_error", status: null, hint: null }, + }, + { + name: "parse error", + cause: Cause.fail( + new CliError.UnrecognizedOption({ + option: "--nope", + command: ["supabase"], + suggestions: [], + }), + ), + expected: { exitCode: 2, code: "usage_error", status: null, hint: null }, + }, + { + name: "invalid output format", + cause: Cause.fail(new InvalidOutputFormatError({ message: "invalid output format" })), + expected: { exitCode: 2, code: "usage_error", status: null, hint: null }, + }, + { + name: "target selector conflict keeps its suggestion", + cause: Cause.fail( + new TargetSelectorConflictError({ + flags: ["--remote", "--local"], + message: "--remote and --local cannot be combined", + suggestion: "Pass only one target flag.", + }), + ), + expected: { + exitCode: 2, + code: "usage_error", + status: null, + hint: "Pass only one target flag.", + }, + }, + { + name: "defect", + cause: Cause.die(new Error("boom")), + expected: { exitCode: 1, code: "internal_error", status: null, hint: null }, + }, + { + name: "unknown typed failure", + cause: Cause.fail("nope"), + expected: { exitCode: 1, code: "internal_error", status: null, hint: null }, + }, + ]; + + it.each(cases)("maps $name", ({ cause, expected }) => { + const { exitCode, document } = standardFailureFor(cause); + expect({ + exitCode, + code: document.code, + status: document.status, + hint: document.hint, + apiCode: document.api_code, + }).toEqual({ ...expected, apiCode: expected.apiCode }); + }); +}); diff --git a/apps/cli/src/shared/cli/subcommand-flag-suggestions.ts b/apps/cli/src/shared/cli/subcommand-flag-suggestions.ts index 2670340179..95f7964147 100644 --- a/apps/cli/src/shared/cli/subcommand-flag-suggestions.ts +++ b/apps/cli/src/shared/cli/subcommand-flag-suggestions.ts @@ -95,7 +95,8 @@ function commandFlagsFor(command: Command.Command.Any): ReadonlyArray, ): Command.Command.Any | undefined { diff --git a/apps/cli/src/shared/cli/value-consuming-flags.ts b/apps/cli/src/shared/cli/value-consuming-flags.ts index 5b82208bff..e97b55db2c 100644 --- a/apps/cli/src/shared/cli/value-consuming-flags.ts +++ b/apps/cli/src/shared/cli/value-consuming-flags.ts @@ -1,3 +1,4 @@ +import { apiCommands } from "../../commands/api/generated.ts"; import { GEN_TYPES_LANGUAGE_VALUE_FLAG_NAMES } from "../../commands/gen/types/types.languages.ts"; /** @@ -110,6 +111,12 @@ export const VALUE_CONSUMING_LONG_FLAGS = new Set([ "stack", "stack-id", "preparation", + // Runtime flags of the generated API commands, plus each generated flag that is not a boolean. + "body", + "timeout", + ...apiCommands.flatMap((entry) => + entry.flags.filter((flag) => flag.type !== "boolean").map((flag) => flag.name), + ), ]); /** Single-character short flags (no `-` prefix) that consume the next token. */ diff --git a/apps/cli/src/shared/config/experimental-feature.ts b/apps/cli/src/shared/config/experimental-feature.ts index 5d0d9c14c4..a38a3b6264 100644 --- a/apps/cli/src/shared/config/experimental-feature.ts +++ b/apps/cli/src/shared/config/experimental-feature.ts @@ -23,6 +23,7 @@ export class ExperimentalFeatureFlagError extends Data.TaggedError("Experimental const featureSchemas = { stack: CliConfigSchema.fields.experimental.to.fields.stack, compute: CliConfigSchema.fields.experimental.to.fields.compute, + warehouse: CliConfigSchema.fields.experimental.to.fields.warehouse, } as const; const firstExplicitLongFlagValue = ( @@ -76,6 +77,7 @@ export const readExperimentalFeatureConfig = (input: { const featureKeys = { stack: CliConfigKeys.experimental.stack, compute: CliConfigKeys.experimental.compute, + warehouse: CliConfigKeys.experimental.warehouse, } as const; /** diff --git a/apps/cli/src/shared/telemetry/__fixtures__/error-tags.txt b/apps/cli/src/shared/telemetry/__fixtures__/error-tags.txt index 163dd46d37..11601b007e 100644 --- a/apps/cli/src/shared/telemetry/__fixtures__/error-tags.txt +++ b/apps/cli/src/shared/telemetry/__fixtures__/error-tags.txt @@ -1,4 +1,8 @@ AccessTokenRequiredError +ApiCommandOperationFailedError +ApiCommandStatusError +ApiCommandUsageError +ApiCommandWaitTimeoutError ApiMaxRetriesError BackupListNetworkError BackupListUnexpectedStatusError diff --git a/apps/cli/tests/fixtures/standard-errors-cli.ts b/apps/cli/tests/fixtures/standard-errors-cli.ts new file mode 100644 index 0000000000..80619e72b0 --- /dev/null +++ b/apps/cli/tests/fixtures/standard-errors-cli.ts @@ -0,0 +1,69 @@ +import { Config, Data, Effect, Result } from "effect"; +import { Command } from "effect/cli"; +import { ROOT_GLOBAL_FLAGS } from "../../src/command-internal/global-flags.ts"; +import { withStandardErrors } from "../../src/command-internal/command-errors/command-errors.annotation.ts"; +import { + HostedMutationConsentRequiredError, + HostedMutationDeclinedError, +} from "../../src/command-internal/hosted-consent/hosted-consent.errors.ts"; +import { parseTargetSelector } from "../../src/command-internal/target/target-selector.ts"; +import { projectTargetFlags } from "../../src/command-internal/target/target-flags.ts"; +import { ApiCommandStatusError } from "../../src/commands/api/api-command.errors.ts"; +import { runCli } from "../../src/shared/cli/run.ts"; +import { mockAnalytics } from "../helpers/mocks.ts"; + +class LegacyBoomError extends Data.TaggedError("LegacyBoomError")<{ readonly message: string }> {} + +const standard = (name: string, handler: Effect.Effect) => + Command.make(name, {}, () => handler).pipe(withStandardErrors); + +const root = Command.make("supabase").pipe( + Command.withSubcommands([ + standard( + "conflict", + Effect.fail( + new ApiCommandStatusError({ + status: 409, + message: "Resource already exists", + apiCode: "already_exists", + hint: "Pick another name", + }), + ), + ), + standard( + "needs-consent", + Effect.fail( + new HostedMutationConsentRequiredError({ + message: "Confirmation required: delete things", + suggestion: "Re-run with --yes to confirm.", + }), + ), + ), + Command.make("select", projectTargetFlags(), (flags) => + Result.match( + parseTargetSelector({ + remote: flags.remote, + projectRef: flags.projectRef, + local: false, + linked: false, + }), + { onFailure: Effect.fail, onSuccess: Effect.succeed }, + ), + ).pipe(withStandardErrors), + standard("declined", Effect.fail(new HostedMutationDeclinedError({ message: "Declined" }))), + standard("crash", Effect.die(new Error("boom"))), + Command.make("legacy", {}, () => Effect.fail(new LegacyBoomError({ message: "legacy boom" }))), + ]), + Command.withGlobalFlags(ROOT_GLOBAL_FLAGS), +); + +const simulateTty = await Effect.runPromise( + Config.Boolean("STANDARD_ERRORS_FIXTURE_TTY").pipe(Config.withDefault(false)), +); +if (simulateTty) { + Object.defineProperty(process.stdout, "isTTY", { value: true }); +} + +await Effect.runPromise( + runCli(root, { agentDefaultOutputFormat: "text", analyticsLayer: mockAnalytics().layer }), +); diff --git a/apps/cli/tests/helpers/command-flags.unit.test.ts b/apps/cli/tests/helpers/command-flags.unit.test.ts index 8375f88d86..cf615f67de 100644 --- a/apps/cli/tests/helpers/command-flags.unit.test.ts +++ b/apps/cli/tests/helpers/command-flags.unit.test.ts @@ -53,5 +53,7 @@ describe("commandTreeFor", () => { it("only includes feature-gated commands for the variant that enables them", () => { expect(tree.has("compute list")).toBe(false); expect(commandTreeFor({ computeEnabled: true }).has("compute list")).toBe(true); + expect(tree.has("warehouse enable")).toBe(false); + expect(commandTreeFor({ warehouseEnabled: true }).has("warehouse enable")).toBe(true); }); }); diff --git a/apps/cli/tests/helpers/hosted-consent.ts b/apps/cli/tests/helpers/hosted-consent.ts index a3a6997799..81f129b95a 100644 --- a/apps/cli/tests/helpers/hosted-consent.ts +++ b/apps/cli/tests/helpers/hosted-consent.ts @@ -37,6 +37,8 @@ type HostedConsentServices = Layer.Success>; interface HostedConsentEnv { readonly workdir: string; + /** Whether this case grants consent with `--yes`, for scenarios that run through argv. */ + readonly yes: boolean; readonly out: ReturnType; readonly api: ReturnType; } @@ -134,7 +136,7 @@ export function describeHostedConsent(path: string, scenario: HostedConsentScena yield* scenario.setup(workdir).pipe(Effect.provide(BunServices.layer)); } - const invocation = scenario.invoke({ workdir, out, api }); + const invocation = scenario.invoke({ workdir, yes: options.yes ?? false, out, api }); const shellEnv = (body: Effect.Effect) => options.shellYes === true ? withConfigEnv({ SUPABASE_YES: "1" }, body) diff --git a/knip.jsonc b/knip.jsonc index 4e26102ccd..08f8c2e873 100644 --- a/knip.jsonc +++ b/knip.jsonc @@ -25,6 +25,9 @@ // Referenced from package.json#release.plugins; knip's Semantic Release plugin only // reads the root manifest. "scripts/analyze-commits-title.js", + // Data modules the generated command runtime and the contract extraction will consume. + "src/commands/api/generated.ts", + "src/commands/api/generated.schemas.ts", // tests/smoke-test.ts picks the platform file from a string map and spawns it. "tests/smoke-test-*.ts", ], diff --git a/package.json b/package.json index 9f828a33c2..37eed06468 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "scripts": { "prepare": "effect-tsgo patch --no-typescript --oxlint && husky", "build": "pnpm exec turbo run build", - "generate": "pnpm exec turbo run @supabase/api#generate @supabase/stack#generate && pnpm exec turbo run supabase#schemas:generate", + "generate": "pnpm exec turbo run @supabase/api#generate @supabase/stack#generate supabase#api-commands:generate && pnpm exec turbo run supabase#schemas:generate", "test:live": "pnpm exec turbo run supabase#test:live --concurrency=1 --", "record": "pnpm exec turbo run @supabase/cli-e2e#record --", "test:smoke": "pnpm exec turbo run supabase#test:smoke --", @@ -14,7 +14,7 @@ "test:integration": "pnpm exec turbo run test:integration:run --continue=always --", "test:e2e": "pnpm exec turbo run supabase#build && pnpm exec turbo run test:e2e:run --only --concurrency=1 --continue=always --", "test:vitest": "bun --bun vitest run --project '!*e2e*' --project '!*live*'", - "check:all": "pnpm exec turbo run types:check lint:check fmt:check knip:check lint:actions:check", + "check:all": "pnpm exec turbo run types:check lint:check fmt:check knip:check lint:actions:check api-commands:check", "fix:all": "pnpm exec turbo run knip:fix && pnpm exec turbo run lint:fix && pnpm exec turbo run fmt:fix", "lint:check": "oxlint --config .oxlintrc.json", "lint:fix": "oxlint --config .oxlintrc.json --fix --fix-suggestions", diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 0d43e170f2..5dde7a771d 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -152,5 +152,725 @@ "path": "/components/schemas/SnippetResponse_Output/properties/content/nullable", "value": true, "$comment": "The platform returns a null `content` for a snippet that has no stored content." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1enable", + "value": { + "post": { + "description": "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-enable-warehouse", + "parameters": [ + { + "name": "ref", + "required": true, + "in": "path", + "description": "Project ref", + "schema": { + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$", + "example": "abcdefghijklmnopqrst", + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseEnableRequest" + } + } + } + }, + "responses": { + "202": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseEnableAcceptedResponse_Output" + } + } + } + }, + "400": { + "description": "Empty or unsupported selection", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "402": { + "description": "This feature requires the Pro, Team, or Enterprise organization plan.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "403": { + "description": "Forbidden action", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "409": { + "description": "Existing selection or lifecycle conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "503": { + "description": "Warehouse setup unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Enable Warehouse replication", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Pro", "Team", "Enterprise"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-cli": { + "group": "warehouse", + "method": "enable", + "flags": { + "tables": "table" + }, + "wait": { + "read": "v2-get-warehouse-setup", + "params": { + "ref": "/data/id", + "selection_id": "/data/attributes/selection_id" + }, + "status": "/data/attributes/status", + "succeeded": ["succeeded"], + "failed": ["failed"], + "error": "/data/attributes/status_error" + } + }, + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write"]], + "x-oauth-scope": "database:write", + "x-scalar-stability": "experimental" + } + }, + "$comment": "Staging-only operation; remove once the production Management API ships it." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1setups~1current", + "value": { + "get": { + "description": "Returns setup phases, linked tables, pipeline and routing state, cleanup errors, and optional FDW inspection. Set inspect_fdw=false to skip database FDW inspection. A null table replication_state means no observation is available. Status succeeded requires initial copy, a running pipeline and ready routing; it does not verify query connectivity. Pass the selection_id returned by enable to reject a changed selection while waiting.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-setup", + "parameters": [ + { + "name": "ref", + "required": true, + "in": "path", + "description": "Project ref", + "schema": { + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$", + "example": "abcdefghijklmnopqrst", + "type": "string" + } + }, + { + "name": "inspect_fdw", + "required": false, + "in": "query", + "description": "Inspect database FDW state. Defaults to true for current-status reads and false when selection_id is supplied.", + "schema": { + "type": "string", + "enum": ["true", "false"] + } + }, + { + "name": "selection_id", + "required": false, + "in": "query", + "description": "Accepted selection identity returned by enable. A different current nonempty selection returns a conflict.", + "schema": { + "pattern": "^[a-f0-9]{64}$", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseSetupStatusResponse_Output" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "403": { + "description": "Forbidden action", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "409": { + "description": "The accepted selection changed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "503": { + "description": "Warehouse status unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get Warehouse initial synchronization status", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-cli": { + "group": "warehouse.setups", + "method": "get", + "wait": { + "status": "/data/attributes/status", + "succeeded": ["succeeded"], + "failed": ["failed"], + "error": "/data/attributes/status_error" + } + }, + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-scalar-stability": "experimental" + } + }, + "$comment": "Staging-only operation; remove once the production Management API ships it." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseEnableRequest", + "value": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Resource type.", + "enum": ["warehouse_setup"] + }, + "attributes": { + "type": "object", + "properties": { + "warehouse_region": { + "description": "Optional Warehouse compute region, independent of the source and catalog regions. Defaults to the existing assignment, or ap-southeast-1 in staging and eu-west-1 in production for a new assignment. DNS routing requires a registered cluster in that environment. Unsupported regions and changes to an existing assignment are rejected. Ignored when targets is empty.", + "example": "ap-southeast-1", + "type": "string", + "minLength": 1 + }, + "destination_project_ref": { + "description": "Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. Defaults to this project on first setup and to the configured destination on later requests. The destination must be active and healthy, and another project requires SQL and Storage admin write permissions. An existing destination cannot be changed through setup. Ignored when targets is empty.", + "example": "zyxwvutsrqponmlkjihg", + "type": "string", + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$" + }, + "install_fdw": { + "description": "Whether to configure and install the Warehouse FDW in the project database. Defaults to false. Ignored when targets is empty.", + "example": false, + "type": "boolean" + }, + "schema": { + "type": "string", + "minLength": 1, + "description": "Source PostgreSQL schema. Without tables, selects its currently eligible tables only.", + "example": "public" + }, + "tables": { + "description": "Table names in schema. Omit to select the currently eligible tables in that schema.", + "x-ignore-array-items-must-be-objects": true, + "minItems": 1, + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + } + }, + "required": ["schema"], + "additionalProperties": false + } + }, + "required": ["type", "attributes"] + } + }, + "required": ["data"] + }, + "$comment": "Staging-only operation; remove once the production Management API ships it." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseEnableAcceptedResponse_Output", + "value": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Resource type.", + "enum": ["warehouse_setup"] + }, + "id": { + "type": "string" + }, + "attributes": { + "type": "object", + "properties": { + "tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "schema": { + "type": "string", + "minLength": 1, + "description": "Postgres schema name", + "example": "public" + }, + "name": { + "type": "string", + "minLength": 1, + "description": "Postgres table name", + "example": "orders" + }, + "state": { + "type": "string", + "enum": ["syncing", "live", "error"], + "description": "Warehouse copy sync state derived from replication status", + "example": "live" + }, + "lag_ms": { + "description": "Replication lag in milliseconds, when available", + "example": 12000, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "last_synced_at": { + "description": "Last sync timestamp, when available", + "example": "2026-06-23T17:48:00Z", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "copy_name": { + "type": "string", + "description": "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + "example": "\"abcjuqabhgwjjutfvtpa\".\"public\".\"orders\"" + }, + "warehouse_size_bytes": { + "description": "Warehouse table size in bytes, when available", + "example": 197912092672, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "required": ["schema", "name", "state", "copy_name"] + }, + "description": "Tables with Warehouse copies" + }, + "pipeline_id": { + "type": "string", + "minLength": 1, + "description": "Warehouse replication pipeline ID, or null when Warehouse disable has been requested", + "example": "03dg2o5teb2eucxr9ggh3uie6", + "nullable": true + }, + "accepted": { + "type": "boolean", + "enum": [true] + }, + "selected_tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0 + }, + "schema": { + "type": "string", + "minLength": 1 + }, + "name": { + "type": "string", + "minLength": 1 + } + }, + "required": ["id", "schema", "name"] + } + }, + "selection_id": { + "type": "string", + "pattern": "^[a-f0-9]{64}$", + "description": "Identity of the accepted selection. Pass to the current setup read to reject a changed selection while waiting." + } + }, + "required": ["tables", "pipeline_id", "accepted", "selected_tables", "selection_id"] + } + }, + "required": ["type", "id", "attributes"] + } + }, + "required": ["data"] + }, + "$comment": "Staging-only operation; remove once the production Management API ships it." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseSetupStatusResponse_Output", + "value": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Resource type.", + "enum": ["warehouse_setup"] + }, + "id": { + "type": "string" + }, + "attributes": { + "type": "object", + "properties": { + "dns": { + "description": "Warehouse DNS delivery status. Ready means the DNS API accepted the route; client DNS caches may still be updating.", + "type": "object", + "properties": { + "hostname": { + "type": "string" + }, + "region": { + "type": "string" + }, + "status": { + "type": "string", + "enum": ["pending", "ready", "error", "removed"] + } + }, + "required": ["hostname", "region", "status"] + }, + "delete_data": { + "description": "Whether the current disable request deletes DuckLake data.", + "type": "boolean" + }, + "error": { + "description": "Warehouse cleanup failure, when present.", + "type": "string" + }, + "setup_status": { + "type": "string", + "enum": [ + "not_started", + "setting_up", + "copying", + "complete", + "error", + "disabling", + "disabled", + "deletion_failed" + ], + "description": "Overall Warehouse lifecycle status, using persisted state during teardown and replication state during setup", + "example": "copying" + }, + "pipeline_id": { + "description": "Warehouse replication pipeline ID when it exists", + "example": "03dg2o5teb2eucxr9ggh3uie6", + "type": "string", + "minLength": 1 + }, + "steps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "enum": ["warehouse_pipeline", "warehouse_copy", "warehouse_fdw"], + "description": "Observable Warehouse setup phase", + "example": "warehouse_copy" + }, + "status": { + "type": "string", + "enum": ["waiting", "running", "completed", "skipped", "error"], + "description": "Derived Warehouse setup step status", + "example": "running" + }, + "message": { + "description": "Best-effort progress or error message derived from Warehouse state", + "example": "Pending initial copy: public.orders:copying_table", + "type": "string" + } + }, + "required": ["name", "status"] + }, + "description": "Warehouse setup phases in execution order" + }, + "tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "schema": { + "type": "string", + "minLength": 1, + "description": "Postgres schema name", + "example": "public" + }, + "name": { + "type": "string", + "minLength": 1, + "description": "Postgres table name", + "example": "orders" + }, + "state": { + "type": "string", + "enum": ["syncing", "live", "error"], + "description": "Warehouse copy sync state derived from replication status", + "example": "live" + }, + "lag_ms": { + "description": "Replication lag in milliseconds, when available", + "example": 12000, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "last_synced_at": { + "description": "Last sync timestamp, when available", + "example": "2026-06-23T17:48:00Z", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "copy_name": { + "type": "string", + "description": "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + "example": "\"abcjuqabhgwjjutfvtpa\".\"public\".\"orders\"" + }, + "warehouse_size_bytes": { + "description": "Warehouse table size in bytes, when available", + "example": 197912092672, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "id": { + "type": "integer", + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0 + }, + "replication_state": { + "type": "string", + "nullable": true + } + }, + "required": ["schema", "name", "state", "copy_name", "id", "replication_state"] + } + }, + "fdw_status": { + "type": "object", + "properties": { + "extension_available": { + "type": "boolean", + "description": "Whether fdw_warehouse is available to install on the project database instance", + "example": true + }, + "extension_installed": { + "type": "boolean", + "description": "Whether the fdw_warehouse extension exists in the project database", + "example": true + }, + "wrapper_installed": { + "type": "boolean", + "description": "Whether the Warehouse foreign data wrapper exists in the project database", + "example": true + }, + "server_configured": { + "type": "boolean", + "description": "Whether the Warehouse foreign server exists in the project database", + "example": true + }, + "schema_created": { + "type": "boolean", + "description": "Whether the local Warehouse schema exists in the project database", + "example": true + }, + "foreign_schema_imported": { + "type": "boolean", + "description": "Whether the Warehouse foreign schema import has exposed the Warehouse snapshots table", + "example": true + } + }, + "required": [ + "extension_available", + "extension_installed", + "wrapper_installed", + "server_configured", + "schema_created", + "foreign_schema_imported" + ], + "description": "Project database FDW setup markers; null during or after teardown, when setup inspection is inapplicable.", + "nullable": true + }, + "status": { + "type": "string", + "enum": ["running", "succeeded", "failed"], + "description": "Current enablement readiness. Success requires initial copy, a running pipeline and ready routing; this is not a historical operation result or a query connectivity check." + }, + "status_error": { + "description": "Reason current enablement readiness failed. Separate from Studio setup or cleanup errors.", + "type": "string" + }, + "replication_state": { + "type": "string" + } + }, + "required": [ + "setup_status", + "steps", + "tables", + "fdw_status", + "status", + "replication_state" + ] + } + }, + "required": ["type", "id", "attributes"] + } + }, + "required": ["data"] + }, + "$comment": "Staging-only operation; remove once the production Management API ships it." } ] diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 8cd7eb4df1..95c03eee29 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -12935,6 +12935,176 @@ export const V2DownloadProjectBackupOutput = Schema.Struct({ attributes: Schema.Struct({ file_url: Schema.String }), }), }); +export const V2EnableWarehouseInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + data: Schema.Struct({ + type: Schema.Literal("warehouse_setup").annotate({ description: "Resource type." }), + attributes: Schema.Struct({ + warehouse_region: Schema.optionalKey( + Schema.String.annotate({ + description: + "Optional Warehouse compute region, independent of the source and catalog regions. Defaults to the existing assignment, or ap-southeast-1 in staging and eu-west-1 in production for a new assignment. DNS routing requires a registered cluster in that environment. Unsupported regions and changes to an existing assignment are rejected. Ignored when targets is empty.", + }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + ), + destination_project_ref: Schema.optionalKey( + Schema.String.annotate({ + description: + "Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. Defaults to this project on first setup and to the configured destination on later requests. The destination must be active and healthy, and another project requires SQL and Storage admin write permissions. An existing destination cannot be changed through setup. Ignored when targets is empty.", + }) + .check( + Schema.isMinCodePoints(20).annotate({ + expected: "a string with at least 20 code points", + }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ + expected: "a string with at most 20 code points", + }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + ), + install_fdw: Schema.optionalKey( + Schema.Boolean.annotate({ + description: + "Whether to configure and install the Warehouse FDW in the project database. Defaults to false. Ignored when targets is empty.", + }), + ), + schema: Schema.String.annotate({ + description: + "Source PostgreSQL schema. Without tables, selects its currently eligible tables only.", + }).check(Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" })), + tables: Schema.optionalKey( + Schema.Array( + Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + ) + .annotate({ + description: + "Table names in schema. Omit to select the currently eligible tables in that schema.", + }) + .check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + ), + }), + }), +}); +export const V2EnableWarehouseOutput = Schema.Struct({ + data: Schema.Struct({ + type: Schema.Literal("warehouse_setup").annotate({ description: "Resource type." }), + id: Schema.String, + attributes: Schema.Struct({ + tables: Schema.Array( + Schema.Struct({ + schema: Schema.String.annotate({ description: "Postgres schema name" }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + name: Schema.String.annotate({ description: "Postgres table name" }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + state: Schema.Union([ + Schema.Literals(["syncing", "live", "error"]).annotate({ + description: "Warehouse copy sync state derived from replication status", + }), + OpenString, + ]), + lag_ms: Schema.optionalKey( + Schema.Number.annotate({ + description: "Replication lag in milliseconds, when available", + }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + ), + last_synced_at: Schema.optionalKey( + Schema.String.annotate({ + description: "Last sync timestamp, when available", + format: "date-time", + }), + ), + copy_name: Schema.String.annotate({ + description: + "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + }), + warehouse_size_bytes: Schema.optionalKey( + Schema.Number.annotate({ description: "Warehouse table size in bytes, when available" }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + ), + }), + ).annotate({ description: "Tables with Warehouse copies" }), + pipeline_id: Schema.Union([ + Schema.String.annotate({ + description: + "Warehouse replication pipeline ID, or null when Warehouse disable has been requested", + }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + Schema.Null, + ]), + accepted: Schema.Literal(true), + selected_tables: Schema.Array( + Schema.Struct({ + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + schema: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + name: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + }), + ), + selection_id: Schema.String.annotate({ + description: + "Identity of the accepted selection. Pass to the current setup read to reject a changed selection while waiting.", + }).check( + Schema.isPattern(new RegExp("^[a-f0-9]{64}$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-f0-9]{64}$", + }), + ), + }), + }), +}); export const V2GetAComputeInstanceInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -13915,6 +14085,207 @@ export const V2GetProjectConfigOutput = Schema.Struct({ }), }), }); +export const V2GetWarehouseSetupInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + inspect_fdw: Schema.optionalKey(Schema.Literals(["true", "false"])), + selection_id: Schema.optionalKey( + Schema.String.check( + Schema.isPattern(new RegExp("^[a-f0-9]{64}$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-f0-9]{64}$", + }), + ), + ), +}); +export const V2GetWarehouseSetupOutput = Schema.Struct({ + data: Schema.Struct({ + type: Schema.Literal("warehouse_setup").annotate({ description: "Resource type." }), + id: Schema.String, + attributes: Schema.Struct({ + dns: Schema.optionalKey( + Schema.Struct({ + hostname: Schema.String, + region: Schema.String, + status: Schema.Union([ + Schema.Literals(["pending", "ready", "error", "removed"]), + OpenString, + ]), + }).annotate({ + description: + "Warehouse DNS delivery status. Ready means the DNS API accepted the route; client DNS caches may still be updating.", + }), + ), + delete_data: Schema.optionalKey( + Schema.Boolean.annotate({ + description: "Whether the current disable request deletes DuckLake data.", + }), + ), + error: Schema.optionalKey( + Schema.String.annotate({ description: "Warehouse cleanup failure, when present." }), + ), + setup_status: Schema.Union([ + Schema.Literals([ + "not_started", + "setting_up", + "copying", + "complete", + "error", + "disabling", + "disabled", + "deletion_failed", + ]).annotate({ + description: + "Overall Warehouse lifecycle status, using persisted state during teardown and replication state during setup", + }), + OpenString, + ]), + pipeline_id: Schema.optionalKey( + Schema.String.annotate({ + description: "Warehouse replication pipeline ID when it exists", + }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + ), + steps: Schema.Array( + Schema.Struct({ + name: Schema.Union([ + Schema.Literals(["warehouse_pipeline", "warehouse_copy", "warehouse_fdw"]).annotate({ + description: "Observable Warehouse setup phase", + }), + OpenString, + ]), + status: Schema.Union([ + Schema.Literals(["waiting", "running", "completed", "skipped", "error"]).annotate({ + description: "Derived Warehouse setup step status", + }), + OpenString, + ]), + message: Schema.optionalKey( + Schema.String.annotate({ + description: "Best-effort progress or error message derived from Warehouse state", + }), + ), + }), + ).annotate({ description: "Warehouse setup phases in execution order" }), + tables: Schema.Array( + Schema.Struct({ + schema: Schema.String.annotate({ description: "Postgres schema name" }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + name: Schema.String.annotate({ description: "Postgres table name" }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + state: Schema.Union([ + Schema.Literals(["syncing", "live", "error"]).annotate({ + description: "Warehouse copy sync state derived from replication status", + }), + OpenString, + ]), + lag_ms: Schema.optionalKey( + Schema.Number.annotate({ + description: "Replication lag in milliseconds, when available", + }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + ), + last_synced_at: Schema.optionalKey( + Schema.String.annotate({ + description: "Last sync timestamp, when available", + format: "date-time", + }), + ), + copy_name: Schema.String.annotate({ + description: + "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + }), + warehouse_size_bytes: Schema.optionalKey( + Schema.Number.annotate({ description: "Warehouse table size in bytes, when available" }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + ), + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + replication_state: Schema.Union([Schema.String, Schema.Null]), + }), + ), + fdw_status: Schema.Union([ + Schema.Struct({ + extension_available: Schema.Boolean.annotate({ + description: + "Whether fdw_warehouse is available to install on the project database instance", + }), + extension_installed: Schema.Boolean.annotate({ + description: "Whether the fdw_warehouse extension exists in the project database", + }), + wrapper_installed: Schema.Boolean.annotate({ + description: + "Whether the Warehouse foreign data wrapper exists in the project database", + }), + server_configured: Schema.Boolean.annotate({ + description: "Whether the Warehouse foreign server exists in the project database", + }), + schema_created: Schema.Boolean.annotate({ + description: "Whether the local Warehouse schema exists in the project database", + }), + foreign_schema_imported: Schema.Boolean.annotate({ + description: + "Whether the Warehouse foreign schema import has exposed the Warehouse snapshots table", + }), + }).annotate({ + description: + "Project database FDW setup markers; null during or after teardown, when setup inspection is inapplicable.", + }), + Schema.Null, + ]), + status: Schema.Union([ + Schema.Literals(["running", "succeeded", "failed"]).annotate({ + description: + "Current enablement readiness. Success requires initial copy, a running pipeline and ready routing; this is not a historical operation result or a query connectivity check.", + }), + OpenString, + ]), + status_error: Schema.optionalKey( + Schema.String.annotate({ + description: + "Reason current enablement readiness failed. Separate from Studio setup or cleanup errors.", + }), + ), + replication_state: Schema.String, + }), + }), +}); export const V2ListAllComputeInstancesInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -18908,9 +19279,11 @@ export const openApiOperationIdMap = { "v2-delete-private-link-association-for-database": "v2DeletePrivateLinkAssociationForDatabase", "v2-deploy-a-compute-instance": "v2DeployAComputeInstance", "v2-download-project-backup": "v2DownloadProjectBackup", + "v2-enable-warehouse": "v2EnableWarehouse", "v2-get-a-compute-instance": "v2GetAComputeInstance", "v2-get-notebook": "v2GetNotebook", "v2-get-project-config": "v2GetProjectConfig", + "v2-get-warehouse-setup": "v2GetWarehouseSetup", "v2-list-all-compute-instances": "v2ListAllComputeInstances", "v2-list-log-drains": "v2ListLogDrains", "v2-list-notebooks": "v2ListNotebooks", @@ -22000,6 +22373,20 @@ export const operationDefinitions = { inputSchema: V2DownloadProjectBackupInput, outputSchema: V2DownloadProjectBackupOutput, }, + v2EnableWarehouse: { + id: "v2EnableWarehouse", + description: + "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "POST", + path: "/v2/projects/{ref}/warehouse/enable", + pathParams: ["ref"], + queryParams: [], + headerParams: [], + requestBody: { kind: "json", contentType: "application/json", fields: ["data"] }, + response: { kind: "json" }, + inputSchema: V2EnableWarehouseInput, + outputSchema: V2EnableWarehouseOutput, + }, v2GetAComputeInstance: { id: "v2GetAComputeInstance", description: @@ -22041,6 +22428,20 @@ export const operationDefinitions = { inputSchema: V2GetProjectConfigInput, outputSchema: V2GetProjectConfigOutput, }, + v2GetWarehouseSetup: { + id: "v2GetWarehouseSetup", + description: + "Returns setup phases, linked tables, pipeline and routing state, cleanup errors, and optional FDW inspection. Set inspect_fdw=false to skip database FDW inspection. A null table replication_state means no observation is available. Status succeeded requires initial copy, a running pipeline and ready routing; it does not verify query connectivity. Pass the selection_id returned by enable to reject a changed selection while waiting.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/setups/current", + pathParams: ["ref"], + queryParams: ["inspect_fdw", "selection_id"], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2GetWarehouseSetupInput, + outputSchema: V2GetWarehouseSetupOutput, + }, v2ListAllComputeInstances: { id: "v2ListAllComputeInstances", description: diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index c35875f901..4f9df89294 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -2996,6 +2996,22 @@ export const versionedEffectOperations = { options, ); }), + enableWarehouse: ( + input: typeof operationDefinitions.v2EnableWarehouse.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2EnableWarehouse.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2EnableWarehouse">( + operationDefinitions.v2EnableWarehouse, + input, + options, + ); + }), getAComputeInstance: ( input: typeof operationDefinitions.v2GetAComputeInstance.inputSchema.Type, options?: SupabaseApiRequestOptions, @@ -3044,6 +3060,22 @@ export const versionedEffectOperations = { options, ); }), + getWarehouseSetup: ( + input: typeof operationDefinitions.v2GetWarehouseSetup.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2GetWarehouseSetup.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2GetWarehouseSetup">( + operationDefinitions.v2GetWarehouseSetup, + input, + options, + ); + }), listAllComputeInstances: ( input: typeof operationDefinitions.v2ListAllComputeInstances.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index b8f721a59f..ef899008a8 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -31955,6 +31955,297 @@ "summary": "Retry delivery", "description": "Retry delivering the same event again.\n\nAutomatic retries are not applicable to manual retries - if the delivery fails, there won't be any automatic retries attempted.\n\nThis endpoint is heavy rate-limited to allow for 10 request within 60 seconds." } + }, + "/v2/projects/{ref}/warehouse/enable": { + "post": { + "description": "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-enable-warehouse", + "parameters": [ + { + "name": "ref", + "required": true, + "in": "path", + "description": "Project ref", + "schema": { + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$", + "example": "abcdefghijklmnopqrst", + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseEnableRequest" + } + } + } + }, + "responses": { + "202": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseEnableAcceptedResponse_Output" + } + } + } + }, + "400": { + "description": "Empty or unsupported selection", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "402": { + "description": "This feature requires the Pro, Team, or Enterprise organization plan.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "403": { + "description": "Forbidden action", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "409": { + "description": "Existing selection or lifecycle conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "503": { + "description": "Warehouse setup unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Enable Warehouse replication", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Pro", "Team", "Enterprise"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-cli": { + "group": "warehouse", + "method": "enable", + "flags": { + "tables": "table" + }, + "wait": { + "read": "v2-get-warehouse-setup", + "params": { + "ref": "/data/id", + "selection_id": "/data/attributes/selection_id" + }, + "status": "/data/attributes/status", + "succeeded": ["succeeded"], + "failed": ["failed"], + "error": "/data/attributes/status_error" + } + }, + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write"]], + "x-oauth-scope": "database:write", + "x-scalar-stability": "experimental" + } + }, + "/v2/projects/{ref}/warehouse/setups/current": { + "get": { + "description": "Returns setup phases, linked tables, pipeline and routing state, cleanup errors, and optional FDW inspection. Set inspect_fdw=false to skip database FDW inspection. A null table replication_state means no observation is available. Status succeeded requires initial copy, a running pipeline and ready routing; it does not verify query connectivity. Pass the selection_id returned by enable to reject a changed selection while waiting.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-setup", + "parameters": [ + { + "name": "ref", + "required": true, + "in": "path", + "description": "Project ref", + "schema": { + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$", + "example": "abcdefghijklmnopqrst", + "type": "string" + } + }, + { + "name": "inspect_fdw", + "required": false, + "in": "query", + "description": "Inspect database FDW state. Defaults to true for current-status reads and false when selection_id is supplied.", + "schema": { + "type": "string", + "enum": ["true", "false"] + } + }, + { + "name": "selection_id", + "required": false, + "in": "query", + "description": "Accepted selection identity returned by enable. A different current nonempty selection returns a conflict.", + "schema": { + "pattern": "^[a-f0-9]{64}$", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseSetupStatusResponse_Output" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "403": { + "description": "Forbidden action", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "409": { + "description": "The accepted selection changed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "503": { + "description": "Warehouse status unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get Warehouse initial synchronization status", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-cli": { + "group": "warehouse.setups", + "method": "get", + "wait": { + "status": "/data/attributes/status", + "succeeded": ["succeeded"], + "failed": ["failed"], + "error": "/data/attributes/status_error" + } + }, + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-scalar-stability": "experimental" + } } }, "components": { @@ -46624,6 +46915,417 @@ } }, "required": ["data"] + }, + "V2WarehouseEnableRequest": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Resource type.", + "enum": ["warehouse_setup"] + }, + "attributes": { + "type": "object", + "properties": { + "warehouse_region": { + "description": "Optional Warehouse compute region, independent of the source and catalog regions. Defaults to the existing assignment, or ap-southeast-1 in staging and eu-west-1 in production for a new assignment. DNS routing requires a registered cluster in that environment. Unsupported regions and changes to an existing assignment are rejected. Ignored when targets is empty.", + "example": "ap-southeast-1", + "type": "string", + "minLength": 1 + }, + "destination_project_ref": { + "description": "Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. Defaults to this project on first setup and to the configured destination on later requests. The destination must be active and healthy, and another project requires SQL and Storage admin write permissions. An existing destination cannot be changed through setup. Ignored when targets is empty.", + "example": "zyxwvutsrqponmlkjihg", + "type": "string", + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$" + }, + "install_fdw": { + "description": "Whether to configure and install the Warehouse FDW in the project database. Defaults to false. Ignored when targets is empty.", + "example": false, + "type": "boolean" + }, + "schema": { + "type": "string", + "minLength": 1, + "description": "Source PostgreSQL schema. Without tables, selects its currently eligible tables only.", + "example": "public" + }, + "tables": { + "description": "Table names in schema. Omit to select the currently eligible tables in that schema.", + "x-ignore-array-items-must-be-objects": true, + "minItems": 1, + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + } + }, + "required": ["schema"], + "additionalProperties": false + } + }, + "required": ["type", "attributes"] + } + }, + "required": ["data"] + }, + "V2WarehouseEnableAcceptedResponse_Output": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Resource type.", + "enum": ["warehouse_setup"] + }, + "id": { + "type": "string" + }, + "attributes": { + "type": "object", + "properties": { + "tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "schema": { + "type": "string", + "minLength": 1, + "description": "Postgres schema name", + "example": "public" + }, + "name": { + "type": "string", + "minLength": 1, + "description": "Postgres table name", + "example": "orders" + }, + "state": { + "type": "string", + "enum": ["syncing", "live", "error"], + "description": "Warehouse copy sync state derived from replication status", + "example": "live" + }, + "lag_ms": { + "description": "Replication lag in milliseconds, when available", + "example": 12000, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "last_synced_at": { + "description": "Last sync timestamp, when available", + "example": "2026-06-23T17:48:00Z", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "copy_name": { + "type": "string", + "description": "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + "example": "\"abcjuqabhgwjjutfvtpa\".\"public\".\"orders\"" + }, + "warehouse_size_bytes": { + "description": "Warehouse table size in bytes, when available", + "example": 197912092672, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "required": ["schema", "name", "state", "copy_name"] + }, + "description": "Tables with Warehouse copies" + }, + "pipeline_id": { + "type": "string", + "minLength": 1, + "description": "Warehouse replication pipeline ID, or null when Warehouse disable has been requested", + "example": "03dg2o5teb2eucxr9ggh3uie6", + "nullable": true + }, + "accepted": { + "type": "boolean", + "enum": [true] + }, + "selected_tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0 + }, + "schema": { + "type": "string", + "minLength": 1 + }, + "name": { + "type": "string", + "minLength": 1 + } + }, + "required": ["id", "schema", "name"] + } + }, + "selection_id": { + "type": "string", + "pattern": "^[a-f0-9]{64}$", + "description": "Identity of the accepted selection. Pass to the current setup read to reject a changed selection while waiting." + } + }, + "required": ["tables", "pipeline_id", "accepted", "selected_tables", "selection_id"] + } + }, + "required": ["type", "id", "attributes"] + } + }, + "required": ["data"] + }, + "V2WarehouseSetupStatusResponse_Output": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Resource type.", + "enum": ["warehouse_setup"] + }, + "id": { + "type": "string" + }, + "attributes": { + "type": "object", + "properties": { + "dns": { + "description": "Warehouse DNS delivery status. Ready means the DNS API accepted the route; client DNS caches may still be updating.", + "type": "object", + "properties": { + "hostname": { + "type": "string" + }, + "region": { + "type": "string" + }, + "status": { + "type": "string", + "enum": ["pending", "ready", "error", "removed"] + } + }, + "required": ["hostname", "region", "status"] + }, + "delete_data": { + "description": "Whether the current disable request deletes DuckLake data.", + "type": "boolean" + }, + "error": { + "description": "Warehouse cleanup failure, when present.", + "type": "string" + }, + "setup_status": { + "type": "string", + "enum": [ + "not_started", + "setting_up", + "copying", + "complete", + "error", + "disabling", + "disabled", + "deletion_failed" + ], + "description": "Overall Warehouse lifecycle status, using persisted state during teardown and replication state during setup", + "example": "copying" + }, + "pipeline_id": { + "description": "Warehouse replication pipeline ID when it exists", + "example": "03dg2o5teb2eucxr9ggh3uie6", + "type": "string", + "minLength": 1 + }, + "steps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "enum": ["warehouse_pipeline", "warehouse_copy", "warehouse_fdw"], + "description": "Observable Warehouse setup phase", + "example": "warehouse_copy" + }, + "status": { + "type": "string", + "enum": ["waiting", "running", "completed", "skipped", "error"], + "description": "Derived Warehouse setup step status", + "example": "running" + }, + "message": { + "description": "Best-effort progress or error message derived from Warehouse state", + "example": "Pending initial copy: public.orders:copying_table", + "type": "string" + } + }, + "required": ["name", "status"] + }, + "description": "Warehouse setup phases in execution order" + }, + "tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "schema": { + "type": "string", + "minLength": 1, + "description": "Postgres schema name", + "example": "public" + }, + "name": { + "type": "string", + "minLength": 1, + "description": "Postgres table name", + "example": "orders" + }, + "state": { + "type": "string", + "enum": ["syncing", "live", "error"], + "description": "Warehouse copy sync state derived from replication status", + "example": "live" + }, + "lag_ms": { + "description": "Replication lag in milliseconds, when available", + "example": 12000, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "last_synced_at": { + "description": "Last sync timestamp, when available", + "example": "2026-06-23T17:48:00Z", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "copy_name": { + "type": "string", + "description": "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + "example": "\"abcjuqabhgwjjutfvtpa\".\"public\".\"orders\"" + }, + "warehouse_size_bytes": { + "description": "Warehouse table size in bytes, when available", + "example": 197912092672, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "id": { + "type": "integer", + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0 + }, + "replication_state": { + "type": "string", + "nullable": true + } + }, + "required": [ + "schema", + "name", + "state", + "copy_name", + "id", + "replication_state" + ] + } + }, + "fdw_status": { + "type": "object", + "properties": { + "extension_available": { + "type": "boolean", + "description": "Whether fdw_warehouse is available to install on the project database instance", + "example": true + }, + "extension_installed": { + "type": "boolean", + "description": "Whether the fdw_warehouse extension exists in the project database", + "example": true + }, + "wrapper_installed": { + "type": "boolean", + "description": "Whether the Warehouse foreign data wrapper exists in the project database", + "example": true + }, + "server_configured": { + "type": "boolean", + "description": "Whether the Warehouse foreign server exists in the project database", + "example": true + }, + "schema_created": { + "type": "boolean", + "description": "Whether the local Warehouse schema exists in the project database", + "example": true + }, + "foreign_schema_imported": { + "type": "boolean", + "description": "Whether the Warehouse foreign schema import has exposed the Warehouse snapshots table", + "example": true + } + }, + "required": [ + "extension_available", + "extension_installed", + "wrapper_installed", + "server_configured", + "schema_created", + "foreign_schema_imported" + ], + "description": "Project database FDW setup markers; null during or after teardown, when setup inspection is inapplicable.", + "nullable": true + }, + "status": { + "type": "string", + "enum": ["running", "succeeded", "failed"], + "description": "Current enablement readiness. Success requires initial copy, a running pipeline and ready routing; this is not a historical operation result or a query connectivity check." + }, + "status_error": { + "description": "Reason current enablement readiness failed. Separate from Studio setup or cleanup errors.", + "type": "string" + }, + "replication_state": { + "type": "string" + } + }, + "required": [ + "setup_status", + "steps", + "tables", + "fdw_status", + "status", + "replication_state" + ] + } + }, + "required": ["type", "id", "attributes"] + } + }, + "required": ["data"] } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index 6ee17aaace..b5fc0dd7f6 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -434,4 +434,6 @@ export const operationPermissions: Readonly "v2-organizations-slug-webhooks-endpoints-id-test-post": { fga: [] }, "v2-organizations-slug-webhooks-deliveries-id-get": { fga: [] }, "v2-organizations-slug-webhooks-deliveries-id-retry-post": { fga: [] }, + "v2-enable-warehouse": { fga: [["database_write"]], oauthScope: "database:write" }, + "v2-get-warehouse-setup": { fga: [["database_read"]], oauthScope: "database:read" }, }; diff --git a/packages/config/src/experimental.ts b/packages/config/src/experimental.ts index 28cddd19a8..d41dcdf99c 100644 --- a/packages/config/src/experimental.ts +++ b/packages/config/src/experimental.ts @@ -38,6 +38,12 @@ export const experimental = Schema.Struct({ tags, }), ), + warehouse: Schema.optionalKey( + Schema.Boolean.annotate({ + description: "Enable the experimental warehouse command family.", + tags, + }), + ), stack: Schema.optionalKey( Schema.Boolean.annotate({ description: diff --git a/packages/config/src/project-config/hosted-sections.ts b/packages/config/src/project-config/hosted-sections.ts index 24a5acd3df..de27043cdd 100644 --- a/packages/config/src/project-config/hosted-sections.ts +++ b/packages/config/src/project-config/hosted-sections.ts @@ -52,6 +52,7 @@ export const DOCUMENT_ONLY_LOCAL_PATHS = [ ["realtime", "max_header_length"], ["experimental", "stack"], ["experimental", "compute"], + ["experimental", "warehouse"], ["experimental", "orioledb_version"], ["experimental", "s3_host"], ["experimental", "s3_region"], diff --git a/packages/config/src/project-config/project-config.unit.test.ts b/packages/config/src/project-config/project-config.unit.test.ts index c3254484a0..c834ef5f09 100644 --- a/packages/config/src/project-config/project-config.unit.test.ts +++ b/packages/config/src/project-config/project-config.unit.test.ts @@ -645,6 +645,7 @@ describe("fromConfigDocument — CLI-only field exclusion (CLI-2316)", () => { realtime: { enabled: false, ip_version: "IPv6", max_header_length: 1 }, experimental: { compute: true, + warehouse: true, stack: true, orioledb_version: "", s3_host: "host", diff --git a/turbo.json b/turbo.json index 57070cfac9..3bcd52e0e6 100644 --- a/turbo.json +++ b/turbo.json @@ -26,6 +26,9 @@ "fmt:fix": { "cache": false }, + "api-commands:check": { + "cache": false + }, "knip:check": { "cache": false }, @@ -82,6 +85,19 @@ ], "outputs": ["schemas/**"] }, + "supabase#api-commands:generate": { + "cache": true, + "dependsOn": ["@supabase/api#generate"], + "inputs": [ + "$TURBO_DEFAULT$", + "!src/commands/api/generated*.ts", + "$TURBO_ROOT$/mise.lock", + "$TURBO_ROOT$/.oxfmtrc.json", + "$TURBO_ROOT$/packages/api/src/generated/openapi.json", + "$TURBO_ROOT$/packages/api/src/generated/contracts.ts" + ], + "outputs": ["src/commands/api/generated.ts", "src/commands/api/generated.schemas.ts"] + }, "supabase#test:live": { "cache": false, "dependsOn": ["supabase#build"], From b4ecbc1d781bcf621ac5323931c3ac456458978d Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 16 Nov 2026 14:37:28 +0100 Subject: [PATCH 02/45] refactor(cli): read generated command metadata from the spec Generated Management API commands now take their names and polling behaviour from an `x-operation` extension and standard response `links` in the OpenAPI spec. Secrets are marked on the field, and flags follow a naming convention. The CLI keeps the noun allowlist, the verb vocabulary and an override table, which is empty today. --- apps/cli/scripts/api-command-derive.ts | 237 +++++++++++-- .../scripts/api-command-derive.unit.test.ts | 311 +++++++++++++++++- apps/cli/scripts/generate-api-commands.ts | 4 +- .../api-command-bindings.integration.test.ts | 42 ++- ...mand-names.ts => api-command-overrides.ts} | 43 ++- .../cli/src/commands/api/api-command.model.ts | 2 +- apps/cli/src/commands/api/runtime.ts | 2 +- packages/api/scripts/openapi-overrides.json | 35 +- packages/api/src/generated/openapi.json | 35 +- 9 files changed, 593 insertions(+), 118 deletions(-) rename apps/cli/src/commands/api/{api-command-names.ts => api-command-overrides.ts} (50%) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index b4dcde8eb3..a80fb6a0f2 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -1,10 +1,11 @@ import type { OperationId } from "@supabase/api/effect"; -import { Predicate, Schema } from "effect"; +import { Cause, Exit, Predicate, Schema } from "effect"; import { verbVocabulary, - type ApiCommandName, + type ApiCommandOverride, + type ApiCommandPoll, type ApiNoun, -} from "../src/commands/api/api-command-names.ts"; +} from "../src/commands/api/api-command-overrides.ts"; import type { ApiCommandBinding, ApiCommandEntry, @@ -54,10 +55,34 @@ export class ApiCommandGenerationError extends Schema.TaggedError = Schema.Struct({ + group: Schema.String, + method: Schema.String, + poll: Schema.optionalKey(Schema.Struct(StatusMapping)), +}); + +const decodeXOperation = Schema.decodeUnknownExit(XOperationSchema, { + onExcessProperty: "error", +}); + interface DeriveInput { /** The parsed OpenAPI document. */ readonly spec: JsonObject; - readonly names: Readonly>; + /** Per-operation CLI metadata; its fields win over the spec's `x-operation`. */ + readonly overrides: Readonly>; readonly nouns: Readonly>; /** Kebab-case operation id to the camelCase key of the typed client's `operationDefinitions`. */ readonly operationIdMap: Readonly>; @@ -79,6 +104,15 @@ interface Operation { readonly pathItem: JsonObject; } +interface OperationMetadata { + readonly group?: string; + readonly method?: string; + readonly flags: Readonly>; + readonly sensitive: ReadonlyArray; + readonly poll?: ApiCommandPoll; + readonly wait?: ApiCommandWait; +} + interface FlagShape { readonly type: ApiCommandFlag["type"]; readonly choices?: ReadonlyArray; @@ -292,6 +326,13 @@ const kebabCase = (field: string): string => .replaceAll("_", "-") .toLowerCase(); +/** `tables` to `table`, `entries` to `entry`; names ending in `ss`, `us` or `is` stay as they are. */ +const singular = (kebab: string): string => { + if (kebab.endsWith("ies")) return `${kebab.slice(0, -3)}y`; + if (/(?:ss|us|is)$/u.test(kebab) || !kebab.endsWith("s")) return kebab; + return kebab.slice(0, -1); +}; + const credentialLike = (field: string): boolean => kebabCase(field) .split("-") @@ -326,6 +367,13 @@ const describeFlagSchema = (spec: JsonObject, raw: unknown): FlagShape | undefin return scalar === undefined ? undefined : { ...scalar, repeatable: false }; }; +const isSecretField = (spec: JsonObject, raw: unknown): boolean => { + const schema = asRecord(resolve(spec, raw)); + return ( + schema?.writeOnly === true || schema?.format === "password" || schema?.["x-sensitive"] === true + ); +}; + const schemaDescription = (spec: JsonObject, raw: unknown): string | undefined => asString(asRecord(resolve(spec, raw))?.description); @@ -384,22 +432,148 @@ const operationParameters = (spec: JsonObject, operation: Operation): ReadonlyAr .map((raw) => asRecord(resolve(spec, raw))) .filter(Predicate.isNotUndefined); -/** Derives the generated commands for every name-table entry and collects every lint failure. */ +/** Merges each operation's `x-operation` with its override entry; the override wins field by field. */ +const mergeMetadata = ( + operations: ReadonlyMap, + overrides: Readonly>, + problems: Array, +): ReadonlyMap => { + const merged = new Map(); + for (const operationId of Object.keys(overrides)) { + if (!operations.has(operationId)) { + problems.push(`${operationId}: override entry has no operation in the spec`); + } + } + for (const [operationId, operation] of operations) { + const override = overrides[operationId]; + const block = operation.node["x-operation"]; + let fromSpec: XOperation | undefined; + if (block !== undefined) { + const decoded = decodeXOperation(block); + if (Exit.isFailure(decoded)) { + problems.push(`${operationId}: invalid x-operation: ${Cause.pretty(decoded.cause)}`); + continue; + } + fromSpec = decoded.value; + } + if (override === undefined && fromSpec === undefined) continue; + const group = override?.group ?? fromSpec?.group; + const method = override?.method ?? fromSpec?.method; + if (override !== undefined && (group === undefined || method === undefined)) { + problems.push(`${operationId}: override entry gives no command name; set group and method`); + } + const poll = override?.poll ?? fromSpec?.poll; + merged.set(operationId, { + ...(group === undefined ? {} : { group }), + ...(method === undefined ? {} : { method }), + flags: { ...override?.flags }, + sensitive: [...(override?.sensitive ?? [])], + ...(poll === undefined ? {} : { poll }), + ...(override?.wait === undefined ? {} : { wait: override.wait }), + }); + if (poll !== undefined && operation.method !== "GET") { + problems.push(`${operationId}: poll belongs on a read operation, not ${operation.method}`); + } + } + return merged; +}; + +const RESPONSE_POINTER = /^\$response\.body#(\/.*)$/u; +const REQUEST_PATH = /^\$request\.path\.(.+)$/u; + +/** + * The wait a command's 2xx response `links` declare: the one link whose target operation has + * `poll`. Links to operations without `poll` are ignored. + */ +const linkedWait = ( + spec: JsonObject, + operations: ReadonlyMap, + metadata: ReadonlyMap, + operation: Operation, + fail: (reason: string) => void, +): ApiCommandWait | undefined => { + const responses = asRecord(operation.node.responses) ?? {}; + const waits: Array = []; + for (const code of Object.keys(responses).sort()) { + if (!code.startsWith("2")) continue; + const links = asRecord(asRecord(resolve(spec, responses[code]))?.links) ?? {}; + for (const [linkName, rawLink] of Object.entries(links)) { + const link = asRecord(resolve(spec, rawLink)); + const targetId = asString(link?.operationId); + if (link === undefined || targetId === undefined) { + fail(`link "${linkName}" must name its target with operationId`); + continue; + } + const target = operations.get(targetId); + if (target === undefined) { + fail(`link "${linkName}" targets unknown operation "${targetId}"`); + continue; + } + const poll = metadata.get(targetId)?.poll; + if (poll === undefined) continue; + + const params: Record = {}; + for (const [parameter, expression] of Object.entries(asRecord(link.parameters) ?? {})) { + const pointer = typeof expression === "string" ? RESPONSE_POINTER.exec(expression) : null; + const pathName = typeof expression === "string" ? REQUEST_PATH.exec(expression)?.[1] : null; + if (pointer?.[1] !== undefined) { + params[parameter] = pointer[1]; + } else if (pathName !== null && pathName !== undefined) { + const hasPath = (candidate: Operation) => + operationParameters(spec, candidate).some( + (item) => item.in === "path" && item.name === pathName, + ); + if (parameter !== pathName || !hasPath(target) || !hasPath(operation)) { + fail( + `link "${linkName}" parameter "${parameter}": "${String(expression)}" needs a path parameter of that name on both operations`, + ); + } + } else { + fail( + `link "${linkName}" parameter "${parameter}": unsupported expression ${JSON.stringify(expression)}`, + ); + } + } + waits.push({ + read: targetId, + params, + status: poll.status, + succeeded: poll.succeeded, + failed: poll.failed, + ...(poll.error === undefined ? {} : { error: poll.error }), + }); + } + } + if (waits.length > 1) { + fail( + `more than one response link targets a polled operation (${waits.map((w) => w.read).join(", ")})`, + ); + return undefined; + } + return waits[0]; +}; + +/** Derives the generated commands from the merged `x-operation` and override metadata and collects every lint failure. */ export function deriveApiCommands(input: DeriveInput): DeriveResult { - const { spec, names, nouns, operationIdMap, handWrittenTopLevel } = input; + const { spec, overrides, nouns, operationIdMap, handWrittenTopLevel } = input; const operations = collectOperations(spec); const problems: Array = []; + const metadata = mergeMetadata(operations, overrides, problems); + const commandNamed = new Set( + [...metadata].flatMap(([id, item]) => + item.group !== undefined && item.method !== undefined ? [id] : [], + ), + ); const entries: Array = []; const schemas: Record = {}; const commandOwners = new Map(); - for (const [operationId, name] of Object.entries(names)) { + for (const [operationId, name] of metadata) { + const { group, method } = name; + if (group === undefined || method === undefined) continue; const fail = (reason: string) => problems.push(`${operationId}: ${reason}`); const operation = operations.get(operationId); - if (operation === undefined) { - fail("name table entry has no operation in the spec"); - continue; - } + if (operation === undefined) continue; const definition = operationIdMap[operationId]; if (definition === undefined) { fail("operation is missing from the typed client; regenerate @supabase/api"); @@ -407,16 +581,15 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { } const failuresBefore = problems.length; - const command = [...name.group.split("."), name.method]; - const segments = [...name.group.split("."), name.method]; - if (!segments.every((segment) => KEBAB.test(segment))) { + const command = [...group.split("."), method]; + if (!command.every((segment) => KEBAB.test(segment))) { fail(`command "${command.join(" ")}" must be lowercase kebab-case words`); } if (command.length > MAX_COMMAND_WORDS) { fail(`command "${command.join(" ")}" exceeds ${MAX_COMMAND_WORDS} words`); } - if (name.customVerb !== true && !VERBS.has(name.method)) { - fail(`verb "${name.method}" is outside the vocabulary; use a listed verb or set customVerb`); + if (!VERBS.has(method)) { + fail(`verb "${method}" is outside the vocabulary; use a listed verb`); } const noun = nouns[command[0] ?? ""]; if (noun === undefined) { @@ -439,8 +612,8 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const summary = asString(operation.node.summary); if (summary === undefined) fail("operation has no summary"); - const renames = name.flags ?? {}; - const sensitive = name.sensitive ?? []; + const renames = name.flags; + const sensitive = name.sensitive; const fields: Array<{ readonly location: "query" | "body"; readonly key: string; @@ -448,6 +621,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { readonly shape: FlagShape; readonly required: boolean; readonly description: string | undefined; + readonly writeOnly: boolean; }> = []; const pathBindings: Array = []; @@ -475,6 +649,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { required: parameter.required === true, description: asString(parameter.description) ?? schemaDescription(spec, parameter.schema), + writeOnly: false, }); } break; @@ -537,6 +712,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { shape, required: required.includes(field), description: schemaDescription(spec, schema), + writeOnly: isSecretField(spec, schema), }); } } @@ -559,7 +735,11 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const seenNames = new Set(); const seenKeys = new Set(); for (const field of fields) { - const flagName = renames[field.key] ?? kebabCase(field.key); + const conventional = + field.location === "body" && field.shape.repeatable + ? singular(kebabCase(field.key)) + : kebabCase(field.key); + const flagName = renames[field.key] ?? conventional; if (!KEBAB.test(flagName)) fail(`flag "${flagName}" must be lowercase kebab-case`); if (RESERVED_FLAGS.has(flagName)) { fail( @@ -574,7 +754,8 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { } seenNames.add(flagName); seenKeys.add(field.key); - const isSensitive = sensitive.includes(field.key); + const isSensitive = + field.location === "body" && (field.writeOnly || sensitive.includes(field.key)); if (field.location === "body" && credentialLike(field.key) && !isSensitive) { fail( `body field "${field.key}" looks like a credential; review it and list it under sensitive`, @@ -602,8 +783,9 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { }); } - if (name.wait !== undefined) { - lintWait({ spec, operations, names, operationId, operation, wait: name.wait, fail }); + const wait = name.wait ?? linkedWait(spec, operations, metadata, operation, fail); + if (wait !== undefined) { + lintWait({ spec, operations, commandNamed, operation, wait, fail }); } const response = classifySuccess(spec, operation, fail); @@ -647,7 +829,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { response: { status: response.status, kind: response.kind }, flags, bindings, - ...(name.wait === undefined ? {} : { wait: name.wait }), + ...(wait === undefined ? {} : { wait }), }); } @@ -660,20 +842,19 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { function lintWait(input: { readonly spec: JsonObject; readonly operations: ReadonlyMap; - readonly names: Readonly>; - readonly operationId: string; + readonly commandNamed: ReadonlySet; readonly operation: Operation; readonly wait: ApiCommandWait; readonly fail: (reason: string) => void; }): void { - const { spec, operations, names, operation, wait, fail } = input; + const { spec, operations, commandNamed, operation, wait, fail } = input; const readOperation = operations.get(wait.read); if (readOperation === undefined) { fail(`wait.read "${wait.read}" has no operation in the spec`); return; } - if (names[wait.read] === undefined) { - fail(`wait.read "${wait.read}" is not in the name table, so it has no command`); + if (!commandNamed.has(wait.read)) { + fail(`wait.read "${wait.read}" has no command name`); } const readParameters = operationParameters(spec, readOperation); diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 2d3ef6fbe5..7aa609c02d 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "@effect/vitest"; -import type { ApiCommandName } from "../src/commands/api/api-command-names.ts"; +import type { ApiCommandOverride } from "../src/commands/api/api-command-overrides.ts"; import { deriveApiCommands } from "./api-command-derive.ts"; const DIALECT = "https://json-schema.org/draft/2020-12/schema"; @@ -39,18 +39,21 @@ const envelope = (attributes: Record) => ({ }, }); -const derive = (operations: Record, names: Record) => +const derive = ( + operations: Record, + overrides: Record, +) => deriveApiCommands({ spec: { paths: Object.fromEntries( Object.entries(operations).map(([id, node]) => [ `/v1/projects/{ref}/${id}`, - { post: { operationId: id, ...(node as object) } }, + { [id.startsWith("get-") ? "get" : "post"]: { operationId: id, ...(node as object) } }, ]), ), components: { schemas: { Tags: { type: "array", items: { type: "string" } } } }, }, - names, + overrides, nouns: { thing: { description: "Manage things", feature: "things" } }, operationIdMap: Object.fromEntries( Object.keys(operations).map((id) => [id, "v2EnableWarehouse" as const]), @@ -58,7 +61,7 @@ const derive = (operations: Record, names: Record { it("binds envelope body fields by JSON pointer and the project ref to the target", () => { @@ -68,7 +71,7 @@ describe("deriveApiCommands", () => { requestBody: envelope({ tags: { type: "array", items: { type: "string" } } }), }), }, - { "create-thing": { ...create, flags: { tags: "tag" } } }, + { "create-thing": create }, ); expect(result.problems).toEqual([]); @@ -259,4 +262,300 @@ describe("deriveApiCommands", () => { expect(result.problems.join("\n")).toContain('keyword "contentMediaType"'); }); + + it("names a command from the operation's x-operation alone", () => { + const result = derive( + { "create-thing": operation({ "x-operation": { group: "thing", method: "create" } }) }, + {}, + ); + + expect(result.problems).toEqual([]); + expect(result.entries.map((entry) => entry.command)).toEqual([["thing", "create"]]); + }); + + it("lets an override entry replace the name and rename a single flag", () => { + const result = derive( + { + "create-thing": operation({ + "x-operation": { group: "thing", method: "create" }, + requestBody: envelope({ tags: { type: "array", items: { type: "string" } } }), + }), + }, + { "create-thing": { method: "update", flags: { name: "title", tags: "tg" } } }, + ); + + expect(result.problems).toEqual([]); + const [entry] = result.entries; + expect(entry?.command).toEqual(["thing", "update"]); + expect(entry?.flags.map((flag) => flag.name)).toEqual(["title", "tg"]); + }); + + it("names array body flags in the singular and keeps other fields as they are", () => { + const list = { type: "array", items: { type: "string" } }; + const result = derive( + { + "create-thing": operation({ + requestBody: envelope({ + categories: list, + tables: list, + access: list, + status: list, + analysis: list, + sizes: { type: "string" }, + }), + }), + }, + { "create-thing": create }, + ); + + expect(result.problems).toEqual([]); + expect(result.entries[0]?.flags.map((flag) => flag.name)).toEqual([ + "name", + "category", + "table", + "access", + "status", + "analysis", + "sizes", + ]); + }); + + it("rejects a singularised flag that collides with another flag", () => { + const result = derive( + { + "create-thing": operation({ + requestBody: envelope({ + table: { type: "string" }, + tables: { type: "array", items: { type: "string" } }, + }), + }), + }, + { "create-thing": create }, + ); + + expect(result.problems.join("\n")).toContain('"--table"'); + }); + + it("marks writeOnly and password-format body fields sensitive", () => { + const result = derive( + { + "create-thing": operation({ + requestBody: envelope({ + api_secret: { type: "string", writeOnly: true }, + pin: { type: "string", format: "password" }, + }), + }), + }, + { "create-thing": create }, + ); + + expect(result.problems).toEqual([]); + expect(result.entries[0]?.flags.map((flag) => [flag.name, flag.sensitive === true])).toEqual([ + ["name", false], + ["api-secret", true], + ["pin", true], + ]); + }); + + it("accepts a credential-like field that is marked x-sensitive or listed by the table and rejects it otherwise", () => { + const body = (api_key: Record) => envelope({ api_key }); + const flagOf = (result: ReturnType) => + result.entries[0]?.flags.find((flag) => flag.name === "api-key"); + + const marked = derive( + { "create-thing": operation({ requestBody: body({ type: "string", "x-sensitive": true }) }) }, + { "create-thing": create }, + ); + const listed = derive( + { "create-thing": operation({ requestBody: body({ type: "string" }) }) }, + { "create-thing": { ...create, sensitive: ["api_key"] } }, + ); + const unreviewed = derive( + { "create-thing": operation({ requestBody: body({ type: "string" }) }) }, + { "create-thing": create }, + ); + + expect(marked.problems).toEqual([]); + expect(flagOf(marked)?.sensitive).toBe(true); + expect(listed.problems).toEqual([]); + expect(flagOf(listed)?.sensitive).toBe(true); + expect(unreviewed.problems.join("\n")).toContain('"api_key" looks like a credential'); + }); + + describe("wait from response links", () => { + const changeResponse = (links: unknown) => ({ + "202": { + description: "accepted", + content: { + "application/json": { + schema: { + type: "object", + properties: { data: { type: "object", properties: { id: { type: "string" } } } }, + }, + }, + }, + links, + }, + }); + const poll = { + status: "/data/attributes/status", + succeeded: ["done"], + failed: ["broken"], + error: "/data/attributes/reason", + }; + const readThing = operation({ + "x-operation": { group: "thing", method: "get", poll }, + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "thing_id", in: "query", schema: { type: "string" } }, + ], + responses: jsonResponse({ + type: "object", + properties: { + data: { + type: "object", + properties: { + attributes: { + type: "object", + properties: { + status: { type: "string", enum: ["done", "broken", "pending"] }, + reason: { type: "string" }, + }, + }, + }, + }, + }, + }), + }); + const link = (parameters: Record, operationId = "get-thing") => ({ + setup: { operationId, parameters }, + }); + const changeThing = (links: unknown) => + operation({ + "x-operation": { group: "thing", method: "create" }, + responses: changeResponse(links), + }); + + it("builds the wait from the polled target and leaves the shared path parameter to the runtime", () => { + const result = derive( + { + "create-thing": changeThing( + link({ ref: "$request.path.ref", thing_id: "$response.body#/data/id" }), + ), + "get-thing": readThing, + }, + {}, + ); + + expect(result.problems).toEqual([]); + expect(result.entries.find((entry) => entry.operationId === "create-thing")?.wait).toEqual({ + read: "get-thing", + params: { thing_id: "/data/id" }, + ...poll, + }); + expect( + result.entries.find((entry) => entry.operationId === "get-thing")?.wait, + ).toBeUndefined(); + }); + + it("prefers an explicit wait over a link", () => { + const explicit = { + read: "get-thing", + params: {}, + status: "/data/attributes/reason", + succeeded: ["x"], + failed: [], + }; + const result = derive( + { + "create-thing": changeThing(link({ thing_id: "$response.body#/data/id" })), + "get-thing": readThing, + }, + { "create-thing": { wait: explicit } }, + ); + + expect(result.problems).toEqual([]); + expect(result.entries.find((entry) => entry.operationId === "create-thing")?.wait).toEqual( + explicit, + ); + }); + + it("ignores a link whose target has no poll", () => { + const result = derive( + { + "create-thing": changeThing(link({})), + "get-thing": operation({ "x-operation": { group: "thing", method: "get" } }), + }, + {}, + ); + + expect(result.problems).toEqual([]); + expect(result.entries.find((entry) => entry.operationId === "create-thing")?.wait).toBe( + undefined, + ); + }); + + it.each([ + [ + "an unsupported expression", + link({ thing_id: "$request.query.id" }), + "unsupported expression", + ], + ["an unknown target", link({}, "get-missing"), 'unknown operation "get-missing"'], + [ + "a path parameter the command lacks", + link({ ref: "$request.path.other" }), + "needs a path parameter of that name", + ], + ])("rejects %s", (_label, links, message) => { + const result = derive({ "create-thing": changeThing(links), "get-thing": readThing }, {}); + + expect(result.problems.join("\n")).toContain(message); + }); + }); + + it.each([ + [ + "a verb outside the vocabulary", + { "create-thing": operation({}) }, + { "create-thing": { group: "thing", method: "frobnicate" } }, + 'verb "frobnicate" is outside the vocabulary', + ], + [ + "an unknown key in x-operation", + { + "create-thing": operation({ + "x-operation": { group: "thing", method: "create", bogus: 1 }, + }), + }, + {}, + "create-thing: invalid x-operation", + ], + [ + "a CLI-only key in x-operation", + { + "create-thing": operation({ + "x-operation": { group: "thing", method: "create", flags: { name: "label" } }, + }), + }, + {}, + "create-thing: invalid x-operation", + ], + [ + "an override entry that leaves the operation unnamed", + { "create-thing": operation({}) }, + { "create-thing": { flags: { name: "label" } } }, + "gives no command name", + ], + [ + "an override entry for an operation missing from the spec", + { "create-thing": operation({ "x-operation": { group: "thing", method: "create" } }) }, + { "missing-thing": create }, + "missing-thing: override entry has no operation in the spec", + ], + ])("rejects %s", (_label, operations, overrides, message) => { + const result = derive(operations, overrides); + + expect(result.problems.join("\n")).toContain(message); + }); }); diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index 4e24eb7bb1..67a15c2846 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -1,7 +1,7 @@ import { BunRuntime, BunServices } from "@effect/platform-bun"; import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; -import { commandNames, nouns } from "../src/commands/api/api-command-names.ts"; +import { commandOverrides, nouns } from "../src/commands/api/api-command-overrides.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { ApiCommandGenerationError, deriveApiCommands } from "./api-command-derive.ts"; @@ -87,7 +87,7 @@ const main = Effect.gen(function* () { const { entries, schemas, problems } = deriveApiCommands({ spec, - names: commandNames, + overrides: commandOverrides, nouns, operationIdMap: openApiOperationIdMap, handWrittenTopLevel: yield* handWrittenTopLevel(cliRoot), diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index fbc4df3791..02153a3da4 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -23,8 +23,7 @@ import { mockTelemetryRuntime, mockTty, } from "../../../tests/helpers/mocks.ts"; -import { commandNames } from "./api-command-names.ts"; -import type { ApiCommandName } from "./api-command-names.ts"; +import type { ApiCommandEntry } from "./api-command.model.ts"; import { apiCommands } from "./generated.ts"; import { apiCommandSchemas } from "./generated.schemas.ts"; import { apiCommandGroups } from "./runtime.ts"; @@ -148,12 +147,18 @@ interface Input { readonly sample: unknown; } -const names: Readonly> = commandNames; - -/** Every non-path input of the operation, read from openapi.json and the command name table. */ -const inputsOf = (operationId: string, operation: SpecOperation): ReadonlyArray => { - const flagFor = (field: string) => - names[operationId]?.flags?.[field] ?? field.replaceAll("_", "-"); +/** + * Every non-path input of the operation, read from openapi.json; the flag spelling comes from the + * command's declared binding, since naming is the derivation's contract. + */ +const inputsOf = ( + operation: SpecOperation, + bindings: ApiCommandEntry["bindings"], +): ReadonlyArray => { + const flagFor = (location: Input["location"], field: string) => { + const binding = bindings.find((item) => item.location === location && item.name === field); + return binding?.source === "flag" ? binding.flag : ``; + }; const queries = operation.parameters .filter((parameter) => parameter["in"] === "query") .map((parameter): Input => { @@ -161,7 +166,7 @@ const inputsOf = (operationId: string, operation: SpecOperation): ReadonlyArray< return { location: "query", field, - flag: flagFor(field), + flag: flagFor("query", field), pointer: undefined, required: parameter["required"] === true, sample: sampleOf(parameter["schema"]), @@ -177,16 +182,17 @@ const inputsOf = (operationId: string, operation: SpecOperation): ReadonlyArray< const envelope = Object.keys(attributes).length > 0; const container = envelope ? attributes : operation.requestSchema; const required = asList(container["required"]); - const fields = Object.entries(asRecord(container["properties"])).map( - ([field, schema]): Input => ({ + const fields = Object.entries(asRecord(container["properties"])).map(([field, schema]): Input => { + const sample = sampleOf(schema); + return { location: "body", field, - flag: flagFor(field), + flag: flagFor("body", field), pointer: `${envelope ? "/data/attributes" : ""}/${field}`, required: required.includes(field), - sample: sampleOf(schema), - }), - ); + sample, + }; + }); return [...queries, ...fields]; }; @@ -298,6 +304,8 @@ const send = (path: ReadonlyArray, argv: ReadonlyArray, status: ); }; +const generated: readonly ApiCommandEntry[] = apiCommands; + const surface = await Effect.runPromise(commandSurface()); const rows = [...Object.values(surface.commands), ...Object.values(surface.variants.warehouse)] .flatMap((entry) => (entry.api === undefined ? [] : [{ ...entry, api: entry.api }])) @@ -316,7 +324,7 @@ describe("generated command bindings", () => { for (const row of rows) { const { operationId } = row.api; const operation = operationOf(operationId); - const inputs = inputsOf(operationId, operation); + const inputs = inputsOf(operation, row.api.bindings); const expectedPath = operation.template.replace("{ref}", VALID_REF); describe(row.path.join(" "), () => { @@ -374,7 +382,7 @@ describe("generated command bindings", () => { expect(shapeOf(branches.find((branch) => branch["title"] === "response"))).toEqual( shapeOf(operation.responseSchema), ); - const waitRead = names[operationId]?.wait?.read; + const waitRead = generated.find((entry) => entry.operationId === operationId)?.wait?.read; const waited = branches.find((branch) => branch["title"] === "waited"); if (waitRead === undefined) { expect(waited).toBeUndefined(); diff --git a/apps/cli/src/commands/api/api-command-names.ts b/apps/cli/src/commands/api/api-command-overrides.ts similarity index 50% rename from apps/cli/src/commands/api/api-command-names.ts rename to apps/cli/src/commands/api/api-command-overrides.ts index 9838f4dd88..01099c4a1c 100644 --- a/apps/cli/src/commands/api/api-command-names.ts +++ b/apps/cli/src/commands/api/api-command-overrides.ts @@ -1,7 +1,7 @@ import type { OpenApiOperationId } from "@supabase/api/effect"; import type { ApiCommandWait } from "./api-command.model.ts"; -/** Verbs every generated command may use; anything else needs `customVerb`. */ +/** Verbs every generated command may use. */ export const verbVocabulary = [ "list", "get", @@ -10,6 +10,7 @@ export const verbVocabulary = [ "delete", "enable", "disable", + "status", ] as const; export interface ApiNoun { @@ -18,16 +19,25 @@ export interface ApiNoun { readonly feature?: string; } -export interface ApiCommandName { +/** How to tell that the resource a read operation returns has settled. */ +export type ApiCommandPoll = Pick; + +/** + * CLI-only metadata of one operation; its `group`, `method` and `poll` win over the spec's + * `x-operation`. + */ +export interface ApiCommandOverride { /** Dot-separated noun path, e.g. `warehouse`. Its first segment must be a key of `nouns`. */ - readonly group: string; - readonly method: string; - /** Allows a `method` outside `verbVocabulary`. */ - readonly customVerb?: true; - /** API field name to flag name. */ + readonly group?: string; + /** A member of `verbVocabulary`. */ + readonly method?: string; + /** API field name to flag name; wins over the naming convention. */ readonly flags?: Readonly>; /** Credential-like body fields that were reviewed and are secrets. */ readonly sensitive?: readonly string[]; + /** Set on a read operation; response `links` that target it derive a `--wait`. */ + readonly poll?: ApiCommandPoll; + /** Replaces any wait derived from response `links`. */ readonly wait?: ApiCommandWait; } @@ -35,19 +45,6 @@ export const nouns = { warehouse: { description: "Manage the data warehouse for a project", feature: "warehouse" }, } as const satisfies Readonly>; -export const commandNames = { - "v2-enable-warehouse": { - group: "warehouse", - method: "enable", - flags: { tables: "table" }, - wait: { - read: "v2-get-warehouse-setup", - params: { selection_id: "/data/attributes/selection_id" }, - status: "/data/attributes/status", - succeeded: ["succeeded"], - failed: ["failed"], - error: "/data/attributes/status_error", - }, - }, - "v2-get-warehouse-setup": { group: "warehouse", method: "status", customVerb: true }, -} as const satisfies Partial>; +export const commandOverrides = {} as const satisfies Partial< + Record +>; diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index 146ba90f31..1c51dc4141 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -35,7 +35,7 @@ export interface ApiCommandFlag { readonly choices?: readonly string[]; readonly repeatable: boolean; readonly required: boolean; - /** A body field the name table reviewed as a secret; its value is never echoed or recorded. */ + /** A body field reviewed as a secret; its value is never echoed or recorded. */ readonly sensitive?: true; readonly description?: string; } diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 187dd79cc2..01e8a94919 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -37,7 +37,7 @@ import { ApiCommandUsageError } from "./api-command.errors.ts"; import type { ApiCommandEntry } from "./api-command.model.ts"; import { apiCommands } from "./generated.ts"; import { withStandardErrors } from "../../command-internal/command-errors/command-errors.annotation.ts"; -import { nouns } from "./api-command-names.ts"; +import { nouns } from "./api-command-overrides.ts"; const DEFAULT_WAIT_TIMEOUT = "10m"; const NANOSECONDS_PER_MILLISECOND = 1_000_000; diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 5dde7a771d..3f9d38d521 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -194,6 +194,15 @@ "$ref": "#/components/schemas/V2WarehouseEnableAcceptedResponse_Output" } } + }, + "links": { + "setup": { + "operationId": "v2-get-warehouse-setup", + "parameters": { + "ref": "$request.path.ref", + "selection_id": "$response.body#/data/attributes/selection_id" + } + } } }, "400": { @@ -289,23 +298,9 @@ "position": "before" } ], - "x-cli": { + "x-operation": { "group": "warehouse", - "method": "enable", - "flags": { - "tables": "table" - }, - "wait": { - "read": "v2-get-warehouse-setup", - "params": { - "ref": "/data/id", - "selection_id": "/data/attributes/selection_id" - }, - "status": "/data/attributes/status", - "succeeded": ["succeeded"], - "failed": ["failed"], - "error": "/data/attributes/status_error" - } + "method": "enable" }, "x-endpoint-owners": ["pipelines"], "x-fga-permissions": [["database_write"]], @@ -436,10 +431,10 @@ "position": "before" } ], - "x-cli": { - "group": "warehouse.setups", - "method": "get", - "wait": { + "x-operation": { + "group": "warehouse", + "method": "status", + "poll": { "status": "/data/attributes/status", "succeeded": ["succeeded"], "failed": ["failed"], diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index ef899008a8..598de4b9be 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -31994,6 +31994,15 @@ "$ref": "#/components/schemas/V2WarehouseEnableAcceptedResponse_Output" } } + }, + "links": { + "setup": { + "operationId": "v2-get-warehouse-setup", + "parameters": { + "ref": "$request.path.ref", + "selection_id": "$response.body#/data/attributes/selection_id" + } + } } }, "400": { @@ -32089,23 +32098,9 @@ "position": "before" } ], - "x-cli": { + "x-operation": { "group": "warehouse", - "method": "enable", - "flags": { - "tables": "table" - }, - "wait": { - "read": "v2-get-warehouse-setup", - "params": { - "ref": "/data/id", - "selection_id": "/data/attributes/selection_id" - }, - "status": "/data/attributes/status", - "succeeded": ["succeeded"], - "failed": ["failed"], - "error": "/data/attributes/status_error" - } + "method": "enable" }, "x-endpoint-owners": ["pipelines"], "x-fga-permissions": [["database_write"]], @@ -32231,10 +32226,10 @@ "position": "before" } ], - "x-cli": { - "group": "warehouse.setups", - "method": "get", - "wait": { + "x-operation": { + "group": "warehouse", + "method": "status", + "poll": { "status": "/data/attributes/status", "succeeded": ["succeeded"], "failed": ["failed"], From b76418388a55dc900ca5e12363f390eb40551766 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 16 Nov 2026 14:42:42 +0100 Subject: [PATCH 03/45] refactor(cli): allowlist generated API operations Only operations listed in generatedOperations generate commands. x-operation on any other operation is ignored until the spec metadata design settles. --- apps/cli/scripts/api-command-derive.ts | 38 ++++++++---- .../scripts/api-command-derive.unit.test.ts | 62 ++++++++++++++++--- apps/cli/scripts/generate-api-commands.ts | 7 ++- .../src/commands/api/api-command-overrides.ts | 6 ++ 4 files changed, 92 insertions(+), 21 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index a80fb6a0f2..886585fb64 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -81,6 +81,8 @@ const decodeXOperation = Schema.decodeUnknownExit(XOperationSchema, { interface DeriveInput { /** The parsed OpenAPI document. */ readonly spec: JsonObject; + /** Operation ids that generate commands; `x-operation` on any other operation is ignored. */ + readonly generated: ReadonlyArray; /** Per-operation CLI metadata; its fields win over the spec's `x-operation`. */ readonly overrides: Readonly>; readonly nouns: Readonly>; @@ -432,19 +434,25 @@ const operationParameters = (spec: JsonObject, operation: Operation): ReadonlyAr .map((raw) => asRecord(resolve(spec, raw))) .filter(Predicate.isNotUndefined); -/** Merges each operation's `x-operation` with its override entry; the override wins field by field. */ +/** Merges each generated operation's `x-operation` with its override entry; the override wins field by field. */ const mergeMetadata = ( operations: ReadonlyMap, + generated: ReadonlyArray, overrides: Readonly>, problems: Array, ): ReadonlyMap => { const merged = new Map(); for (const operationId of Object.keys(overrides)) { - if (!operations.has(operationId)) { - problems.push(`${operationId}: override entry has no operation in the spec`); + if (!generated.includes(operationId)) { + problems.push(`${operationId}: override entry is for an operation that is not generated`); } } - for (const [operationId, operation] of operations) { + for (const operationId of generated) { + const operation = operations.get(operationId); + if (operation === undefined) { + problems.push(`${operationId}: generated operation has no operation in the spec`); + continue; + } const override = overrides[operationId]; const block = operation.node["x-operation"]; let fromSpec: XOperation | undefined; @@ -456,11 +464,10 @@ const mergeMetadata = ( } fromSpec = decoded.value; } - if (override === undefined && fromSpec === undefined) continue; const group = override?.group ?? fromSpec?.group; const method = override?.method ?? fromSpec?.method; - if (override !== undefined && (group === undefined || method === undefined)) { - problems.push(`${operationId}: override entry gives no command name; set group and method`); + if (group === undefined || method === undefined) { + problems.push(`${operationId}: no command name; set group and method`); } const poll = override?.poll ?? fromSpec?.poll; merged.set(operationId, { @@ -483,7 +490,7 @@ const REQUEST_PATH = /^\$request\.path\.(.+)$/u; /** * The wait a command's 2xx response `links` declare: the one link whose target operation has - * `poll`. Links to operations without `poll` are ignored. + * `poll`. Links to operations without `poll` are ignored; a polled target that is not generated fails. */ const linkedWait = ( spec: JsonObject, @@ -510,7 +517,14 @@ const linkedWait = ( continue; } const poll = metadata.get(targetId)?.poll; - if (poll === undefined) continue; + if (poll === undefined) { + if (!metadata.has(targetId) && asRecord(target.node["x-operation"])?.poll !== undefined) { + fail( + `link "${linkName}" targets "${targetId}", which declares poll but is not generated`, + ); + } + continue; + } const params: Record = {}; for (const [parameter, expression] of Object.entries(asRecord(link.parameters) ?? {})) { @@ -555,10 +569,10 @@ const linkedWait = ( /** Derives the generated commands from the merged `x-operation` and override metadata and collects every lint failure. */ export function deriveApiCommands(input: DeriveInput): DeriveResult { - const { spec, overrides, nouns, operationIdMap, handWrittenTopLevel } = input; + const { spec, generated, overrides, nouns, operationIdMap, handWrittenTopLevel } = input; const operations = collectOperations(spec); const problems: Array = []; - const metadata = mergeMetadata(operations, overrides, problems); + const metadata = mergeMetadata(operations, generated, overrides, problems); const commandNamed = new Set( [...metadata].flatMap(([id, item]) => item.group !== undefined && item.method !== undefined ? [id] : [], @@ -854,7 +868,7 @@ function lintWait(input: { return; } if (!commandNamed.has(wait.read)) { - fail(`wait.read "${wait.read}" has no command name`); + fail(`wait.read "${wait.read}" is not a generated command`); } const readParameters = operationParameters(spec, readOperation); diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 7aa609c02d..c738307370 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -42,6 +42,7 @@ const envelope = (attributes: Record) => ({ const derive = ( operations: Record, overrides: Record, + generated: ReadonlyArray = Object.keys(operations), ) => deriveApiCommands({ spec: { @@ -53,6 +54,7 @@ const derive = ( ), components: { schemas: { Tags: { type: "array", items: { type: "string" } } } }, }, + generated, overrides, nouns: { thing: { description: "Manage things", feature: "things" } }, operationIdMap: Object.fromEntries( @@ -495,6 +497,16 @@ describe("deriveApiCommands", () => { ); }); + it("rejects a link to a polled target that is not generated", () => { + const result = derive({ "create-thing": changeThing(link({})), "get-thing": readThing }, {}, [ + "create-thing", + ]); + + expect(result.problems).toEqual([ + 'create-thing: link "setup" targets "get-thing", which declares poll but is not generated', + ]); + }); + it.each([ [ "an unsupported expression", @@ -542,20 +554,54 @@ describe("deriveApiCommands", () => { "create-thing: invalid x-operation", ], [ - "an override entry that leaves the operation unnamed", + "a generated operation that has no name", { "create-thing": operation({}) }, { "create-thing": { flags: { name: "label" } } }, - "gives no command name", - ], - [ - "an override entry for an operation missing from the spec", - { "create-thing": operation({ "x-operation": { group: "thing", method: "create" } }) }, - { "missing-thing": create }, - "missing-thing: override entry has no operation in the spec", + "create-thing: no command name", ], ])("rejects %s", (_label, operations, overrides, message) => { const result = derive(operations, overrides); expect(result.problems.join("\n")).toContain(message); }); + + describe("generated operations", () => { + const named = operation({ "x-operation": { group: "thing", method: "create" } }); + + it("ignores x-operation on an operation that is not generated, even when it is invalid", () => { + const result = derive( + { + "create-thing": named, + "create-other": operation({ + "x-operation": { group: "other", method: "frobnicate", bogus: 1 }, + }), + }, + {}, + ["create-thing"], + ); + + expect(result.problems).toEqual([]); + expect(result.entries.map((entry) => entry.operationId)).toEqual(["create-thing"]); + }); + + it("rejects a generated operation that is missing from the spec", () => { + const result = derive({ "create-thing": named }, {}, ["create-thing", "missing-thing"]); + + expect(result.problems).toEqual([ + "missing-thing: generated operation has no operation in the spec", + ]); + }); + + it("rejects an override entry for an operation that is not generated", () => { + const result = derive( + { "create-thing": named, "create-other": named }, + { "create-other": create }, + ["create-thing"], + ); + + expect(result.problems).toEqual([ + "create-other: override entry is for an operation that is not generated", + ]); + }); + }); }); diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index 67a15c2846..5d6a7d6801 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -1,7 +1,11 @@ import { BunRuntime, BunServices } from "@effect/platform-bun"; import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; -import { commandOverrides, nouns } from "../src/commands/api/api-command-overrides.ts"; +import { + commandOverrides, + generatedOperations, + nouns, +} from "../src/commands/api/api-command-overrides.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { ApiCommandGenerationError, deriveApiCommands } from "./api-command-derive.ts"; @@ -87,6 +91,7 @@ const main = Effect.gen(function* () { const { entries, schemas, problems } = deriveApiCommands({ spec, + generated: generatedOperations, overrides: commandOverrides, nouns, operationIdMap: openApiOperationIdMap, diff --git a/apps/cli/src/commands/api/api-command-overrides.ts b/apps/cli/src/commands/api/api-command-overrides.ts index 01099c4a1c..10a618ae52 100644 --- a/apps/cli/src/commands/api/api-command-overrides.ts +++ b/apps/cli/src/commands/api/api-command-overrides.ts @@ -41,6 +41,12 @@ export interface ApiCommandOverride { readonly wait?: ApiCommandWait; } +/** Only these operations generate commands; `x-operation` on any other operation is ignored. */ +export const generatedOperations: ReadonlyArray = [ + "v2-enable-warehouse", + "v2-get-warehouse-setup", +]; + export const nouns = { warehouse: { description: "Manage the data warehouse for a project", feature: "warehouse" }, } as const satisfies Readonly>; From a6e6b63556951e910a7a464f7c3646144331bd5d Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 16 Nov 2026 15:25:24 +0100 Subject: [PATCH 04/45] fix(cli): address review findings for generated API commands - Agent runs on a terminal report failures as the standard JSON document. - Unlinked-project and branch-resolution failures map to usage, network and API error codes instead of internal_error. - Operation-failed and wait-timeout errors classify as API status. - --dry-run masks sensitive fields supplied through --body or --file. - Result schemas combine branches with anyOf. - Generation rejects nested groups and operations without a ref path parameter, and reads +json success schemas for wait pointers. - SIDE_EFFECTS telemetry wording matches what is recorded. --- apps/cli/scripts/api-command-derive.ts | 21 ++++-- .../scripts/api-command-derive.unit.test.ts | 53 +++++++++++++++ .../command-surface.integration.test.ts | 4 +- .../command-surface/command-surface.ts | 4 +- .../api-command-bindings.integration.test.ts | 2 +- .../src/commands/api/api-command-overrides.ts | 2 +- .../src/commands/api/api-command-request.ts | 11 +--- .../src/commands/api/api-command.errors.ts | 4 +- .../src/commands/api/api-commands.e2e.test.ts | 8 +-- .../api/api-commands.integration.test.ts | 24 +++++++ apps/cli/src/commands/api/runtime.ts | 2 +- .../api/warehouse/enable/SIDE_EFFECTS.md | 5 +- .../api/warehouse/status/SIDE_EFFECTS.md | 5 +- apps/cli/src/shared/cli/agent-output.ts | 2 +- apps/cli/src/shared/cli/run.ts | 5 +- .../cli/standard-errors.integration.test.ts | 14 ++++ apps/cli/src/shared/cli/standard-errors.ts | 45 +++++++++---- .../shared/cli/standard-errors.unit.test.ts | 64 +++++++++++++++++++ .../cli/tests/fixtures/standard-errors-cli.ts | 2 +- apps/cli/tests/helpers/cli.ts | 6 +- 20 files changed, 230 insertions(+), 53 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 886585fb64..15ad9b528e 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -43,7 +43,6 @@ const CREDENTIAL_TOKENS: ReadonlySet = new Set([ const VERBS: ReadonlySet = new Set(verbVocabulary); const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const; -const MAX_COMMAND_WORDS = 4; const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u; export class ApiCommandGenerationError extends Schema.TaggedError()( @@ -303,7 +302,7 @@ const classifySuccess = ( } const content = asRecord(asRecord(resolve(spec, responses[code]))?.content) ?? {}; const types = Object.keys(content); - const json = types.find((type) => type === "application/json" || type.endsWith("+json")); + const json = jsonMediaType(content); if (types.length === 0) { classified.push({ status, kind: "empty" }); } else if (json !== undefined) { @@ -397,12 +396,18 @@ const resolvePointer = (spec: JsonObject, root: unknown, pointer: string): unkno return current; }; +/** The JSON media type a response offers: `application/json` or a `+json` suffix type. */ +const jsonMediaType = (content: JsonObject): string | undefined => + Object.keys(content).find((type) => type === "application/json" || type.endsWith("+json")); + const successSchema = (spec: JsonObject, operation: Operation): unknown => { const responses = asRecord(operation.node.responses) ?? {}; for (const code of Object.keys(responses).sort()) { if (!code.startsWith("2")) continue; const response = asRecord(resolve(spec, responses[code])); - const media = asRecord(asRecord(response?.content)?.["application/json"]); + const content = asRecord(response?.content) ?? {}; + const mediaType = jsonMediaType(content); + const media = mediaType === undefined ? undefined : asRecord(content[mediaType]); if (media?.schema !== undefined) return media.schema; } return undefined; @@ -595,13 +600,11 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { } const failuresBefore = problems.length; - const command = [...group.split("."), method]; + const command = [group, method]; + if (group.includes(".")) fail(`group "${group}" must be a single noun`); if (!command.every((segment) => KEBAB.test(segment))) { fail(`command "${command.join(" ")}" must be lowercase kebab-case words`); } - if (command.length > MAX_COMMAND_WORDS) { - fail(`command "${command.join(" ")}" exceeds ${MAX_COMMAND_WORDS} words`); - } if (!VERBS.has(method)) { fail(`verb "${method}" is outside the vocabulary; use a listed verb`); } @@ -744,6 +747,10 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { } } + if (pathBindings.length === 0) { + fail('unsupported in this runtime: operation has no "ref" path parameter'); + } + const flags: Array = []; const bindings: Array = [...pathBindings]; const seenNames = new Set(); diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index c738307370..c890a9ce52 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -384,6 +384,47 @@ describe("deriveApiCommands", () => { expect(unreviewed.problems.join("\n")).toContain('"api_key" looks like a credential'); }); + it("resolves wait pointers from a +json response", () => { + const jsonApi = (schema: unknown) => ({ + "200": { description: "ok", content: { "application/vnd.api+json": { schema } } }, + }); + const result = derive( + { + "create-thing": operation({ + "x-operation": { group: "thing", method: "create" }, + responses: jsonApi({ type: "object", properties: { id: { type: "string" } } }), + }), + "get-thing": operation({ + "x-operation": { group: "thing", method: "get" }, + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "thing_id", in: "query", schema: { type: "string" } }, + ], + responses: jsonApi({ + type: "object", + properties: { status: { type: "string", enum: ["done", "pending"] } }, + }), + }), + }, + { + "create-thing": { + wait: { + read: "get-thing", + params: { thing_id: "/id" }, + status: "/status", + succeeded: ["done"], + failed: [], + }, + }, + }, + ); + + expect(result.problems).toEqual([]); + expect(result.entries.find((entry) => entry.operationId === "create-thing")?.wait?.read).toBe( + "get-thing", + ); + }); + describe("wait from response links", () => { const changeResponse = (links: unknown) => ({ "202": { @@ -527,6 +568,18 @@ describe("deriveApiCommands", () => { }); it.each([ + [ + "a nested group", + { "create-thing": operation({}) }, + { "create-thing": { group: "thing.sub", method: "create" } }, + 'group "thing.sub" must be a single noun', + ], + [ + "an operation without a ref path parameter", + { "create-thing": operation({ parameters: [] }) }, + { "create-thing": create }, + 'operation has no "ref" path parameter', + ], [ "a verb outside the vocabulary", { "create-thing": operation({}) }, diff --git a/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts b/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts index 8f9edee1ed..195fb65b36 100644 --- a/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts @@ -10,8 +10,8 @@ const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown const surface = Effect.runPromise(commandSurface()); const titlesOf = (result: unknown): ReadonlyArray => - typeof result === "object" && result !== null && "oneOf" in result && Array.isArray(result.oneOf) - ? result.oneOf.map((branch) => + typeof result === "object" && result !== null && "anyOf" in result && Array.isArray(result.anyOf) + ? result.anyOf.map((branch) => typeof branch === "object" && branch !== null && "title" in branch ? branch.title : null, ) : []; diff --git a/apps/cli/src/command-internal/command-surface/command-surface.ts b/apps/cli/src/command-internal/command-surface/command-surface.ts index 0bf44fe211..9f0401da7a 100644 --- a/apps/cli/src/command-internal/command-surface/command-surface.ts +++ b/apps/cli/src/command-internal/command-surface/command-surface.ts @@ -63,7 +63,7 @@ interface CommandSurfaceEntry { readonly permissions?: CommandPermissions; readonly arguments: readonly SurfaceArgument[]; readonly flags: Readonly>; - /** `"undeclared"` for a hand-written command, else a JSON Schema `oneOf` of titled branches. */ + /** `"undeclared"` for a hand-written command, else a JSON Schema `anyOf` of titled branches. */ readonly result: "undeclared" | JsonSchema; readonly errors: "standard" | "legacy"; readonly api?: SurfaceApi; @@ -210,7 +210,7 @@ const apiSurface = Effect.fn("CommandSurface.api")(function* (command: CommandRo : { contentType: schemas.request.contentType, schema: schemas.request.schema }, bindings, } satisfies SurfaceApi, - result: { oneOf: branches } satisfies JsonSchema, + result: { anyOf: branches } satisfies JsonSchema, sensitiveFlags: new Set( generated.flags.filter((flag) => flag.sensitive).map((flag) => flag.name), ), diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 02153a3da4..4dca644e77 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -378,7 +378,7 @@ describe("generated command bindings", () => { it("declares the operation's success response as the response result", () => { expect(Object.keys(apiCommandSchemas)).toContain(operationId); - const branches = asList(asRecord(row.result)["oneOf"]).map(asRecord); + const branches = asList(asRecord(row.result)["anyOf"]).map(asRecord); expect(shapeOf(branches.find((branch) => branch["title"] === "response"))).toEqual( shapeOf(operation.responseSchema), ); diff --git a/apps/cli/src/commands/api/api-command-overrides.ts b/apps/cli/src/commands/api/api-command-overrides.ts index 10a618ae52..6b5b7772cf 100644 --- a/apps/cli/src/commands/api/api-command-overrides.ts +++ b/apps/cli/src/commands/api/api-command-overrides.ts @@ -27,7 +27,7 @@ export type ApiCommandPoll = Pick): Record { +export const previewRequest = (entry: ApiCommandEntry, decoded: object): ApiRequestPreview => { const definition = definitionOf(entry); const path = definition.pathParams.reduce( (current, name) => @@ -225,8 +221,7 @@ export const previewRequest = ( body = pick(decoded, definition.requestBody.fields); for (const binding of entry.bindings) { if (binding.location !== "body" || !sensitive.has(binding.flag)) continue; - const value = flagValues[binding.flag]; - if (value !== undefined && Option.isSome(value)) { + if (readPointer(body, binding.pointer) !== undefined) { body = writePointer(body, binding.pointer, REDACTED_PREVIEW_VALUE); } } diff --git a/apps/cli/src/commands/api/api-command.errors.ts b/apps/cli/src/commands/api/api-command.errors.ts index 68572d7417..83daf29295 100644 --- a/apps/cli/src/commands/api/api-command.errors.ts +++ b/apps/cli/src/commands/api/api-command.errors.ts @@ -38,7 +38,7 @@ export class ApiCommandOperationFailedError extends Data.TaggedError( readonly hint: string; }> { get [ErrorActionabilityId](): CliErrorActionabilityDeclaration { - return actionability.invalidInput; + return actionability.apiStatus; } } @@ -49,6 +49,6 @@ export class ApiCommandWaitTimeoutError extends Data.TaggedError("ApiCommandWait readonly hint: string; }> { get [ErrorActionabilityId](): CliErrorActionabilityDeclaration { - return { ...actionability.invalidInput, fingerprint_suffix: "operation_timeout" }; + return { ...actionability.apiStatus, fingerprint_suffix: "operation_timeout" }; } } diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index 7c03f9d121..ae5655be5d 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -159,21 +159,17 @@ it.live("warehouse enable without --yes refuses to run when stdin is piped", () it.live("warehouse enable --wait prints the final status read", () => Effect.gen(function* () { - const reads = [statusBody("running"), statusBody("succeeded")]; - let read = 0; const { result, requests } = yield* runWarehouse( ["enable", "--schema", "public", "--yes", "--wait", "--timeout", "30s", "-o", "json"], ({ method }) => { if (method === "POST") return json(202, { data: { attributes: { selection_id: SEL } } }); - const next = reads[Math.min(read, reads.length - 1)] ?? statusBody("succeeded"); - read += 1; - return next; + return statusBody("succeeded"); }, ); requireCliSuccess(result, "warehouse enable --wait"); expect(result.stdout, result.stderr).toBe(statusBody("succeeded").body); - expect(requests).toEqual([`POST ${ENABLE_PATH}`, `GET ${STATUS_PATH}`, `GET ${STATUS_PATH}`]); + expect(requests).toEqual([`POST ${ENABLE_PATH}`, `GET ${STATUS_PATH}`]); }).pipe(Effect.provide(BunServices.layer)), ); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index ae854a10c4..6c2d0d91ee 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -37,6 +37,7 @@ import { ApiCommandWaitTimeoutError, } from "./api-command.errors.ts"; import type { ApiCommandEntry } from "./api-command.model.ts"; +import { assembleInput, decodeInput, previewRequest } from "./api-command-request.ts"; import { apiCommands } from "./generated.ts"; import { readApiCommand } from "./api-command.annotation.ts"; import { readCommandStage } from "./api-command-stage.ts"; @@ -399,6 +400,29 @@ describe("generated warehouse commands", () => { }); }); + it.effect("masks a sensitive field supplied through --body in the preview", () => + Effect.gen(function* () { + const sensitiveEntry: ApiCommandEntry = { + ...enable, + flags: enable.flags.map((flag) => + flag.name === "schema" ? { ...flag, sensitive: true } : flag, + ), + }; + const body = Option.some({ + data: { type: "warehouse_setup", attributes: { schema: "top-secret" } }, + }); + const input = yield* assembleInput(sensitiveEntry, VALID_REF, {}, body); + const decoded = yield* decodeInput(sensitiveEntry, input); + + const preview = previewRequest(sensitiveEntry, decoded); + + expect(encodeJson(preview)).not.toContain("top-secret"); + expect(preview.body).toEqual({ + data: { type: "warehouse_setup", attributes: { schema: "[redacted]" } }, + }); + }), + ); + it.effect("previews a read with a null body", () => { const { out, run } = setup(["warehouse", "status", "--inspect-fdw", "false", "--dry-run"], { route: ok({}), diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 01e8a94919..ad2b32f624 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -148,7 +148,7 @@ const handle = Effect.fn("api-command.run")(function* ( if (flags.dryRun) { yield* Effect.annotateCurrentSpan("run.outcome", "dry_run"); - return yield* writeDocument(previewRequest(entry, decoded, flags.api), format); + return yield* writeDocument(previewRequest(entry, decoded), format); } if (!entry.readOnly) { yield* requireHostedMutationConsent({ action: consentAction(entry) }); diff --git a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md index 3473fe7b27..521401fe54 100644 --- a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md @@ -67,8 +67,9 @@ nothing, before consent. | ---------------------- | ------------------------------------------ | ----------------------------------- | | `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | -Generated flag values are never recorded; only the target flags and the `--dry-run`, `--wait` -and `--timeout` runtime flags appear in `flags`. +Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` +and `--wait` record `true`. Generated field flags, `--body`, `--file` and `--timeout` are recorded as +``. ## Output diff --git a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md index 07781913ed..67fa87e803 100644 --- a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md @@ -61,8 +61,9 @@ Query: `inspect_fdw=true|false` and `selection_id=`, each only when its flag | ---------------------- | ------------------------------------------ | ----------------------------------- | | `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | -Generated flag values are never recorded; only the target flags and the `--dry-run`, `--wait` -and `--timeout` runtime flags appear in `flags`. +Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` +records `true`. Generated field flags (`--inspect-fdw`, `--selection-id`), `--body` and `--file` are +recorded as ``. ## Output diff --git a/apps/cli/src/shared/cli/agent-output.ts b/apps/cli/src/shared/cli/agent-output.ts index 428ae6f6b0..0807730cbf 100644 --- a/apps/cli/src/shared/cli/agent-output.ts +++ b/apps/cli/src/shared/cli/agent-output.ts @@ -17,7 +17,7 @@ interface AgentOutputOptions { readonly isBuiltInTextRequest?: boolean; } -export function readLongFlag(args: ReadonlyArray, name: string): string | undefined { +function readLongFlag(args: ReadonlyArray, name: string): string | undefined { const prefix = `${name}=`; for (let i = 0; i < args.length; i++) { const arg = args[i]; diff --git a/apps/cli/src/shared/cli/run.ts b/apps/cli/src/shared/cli/run.ts index d9af96f4b3..d97c5bec70 100644 --- a/apps/cli/src/shared/cli/run.ts +++ b/apps/cli/src/shared/cli/run.ts @@ -858,7 +858,10 @@ export const runCli = Effect.fnUntraced(function* < const mapped = standardFailureFor(cause, suggestionContext); return { exitCode: mapped.exitCode, - pending: { ...mapped, machine: isMachineFailureMode(args, tty.stdoutIsTty) }, + pending: { + ...mapped, + machine: isMachineFailureMode(args, tty.stdoutIsTty, outputFormat), + }, } satisfies RunOutcome; } // See `shouldReportFailure` and `exitCodeForFailure` for the exit-code/reporting rules; a diff --git a/apps/cli/src/shared/cli/standard-errors.integration.test.ts b/apps/cli/src/shared/cli/standard-errors.integration.test.ts index e78c351330..a4b4fadc94 100644 --- a/apps/cli/src/shared/cli/standard-errors.integration.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.integration.test.ts @@ -4,6 +4,8 @@ import { Effect, FileSystem, Schema, Stream } from "effect"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; import { fileURLToPath } from "node:url"; +import { AGENT_DETECTION_ENV_KEYS } from "../../../tests/helpers/cli.ts"; + const FIXTURE = fileURLToPath( new URL("../../../tests/fixtures/standard-errors-cli.ts", import.meta.url), ); @@ -23,6 +25,7 @@ const runFixture = Effect.fn("StandardErrorsTest.run")(function* ( const child = yield* spawner.spawn( ChildProcess.make(bun, [FIXTURE, ...args], { env: { + ...Object.fromEntries(AGENT_DETECTION_ENV_KEYS.map((key) => [key, ""])), SUPABASE_HOME: home, SUPABASE_NO_KEYRING: "1", SUPABASE_TELEMETRY_DISABLED: "1", @@ -125,6 +128,17 @@ describe("errors.standard failure contract", () => { }).pipe(Effect.provide(BunServices.layer)), ); + it.live("an agent run on a terminal still reports the JSON document", () => + Effect.gen(function* () { + const { exitCode, stdout, stderr } = yield* runFixture(["conflict", "--agent=yes"], { + STANDARD_ERRORS_FIXTURE_TTY: "1", + }); + expect(stdout).toBe(""); + expect(exitCode).toBe(1); + expect(yield* decodeJson(lastLine(stderr))).toMatchObject({ code: "conflict", status: 409 }); + }).pipe(Effect.provide(BunServices.layer)), + ); + it.live("a terminal run prints the message and hint as text with the same exit code", () => Effect.gen(function* () { const { exitCode, stdout, stderr } = yield* runFixture(["conflict"], { diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index faeed3e7cc..34bc4ba30f 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -18,6 +18,7 @@ import { ApiCommandUsageError, ApiCommandWaitTimeoutError, } from "../../commands/api/api-command.errors.ts"; +import { LinkBranchListStatusError } from "../../command-internal/target/branch-resolution.errors.ts"; import { normalizeCause } from "../output/normalize-error.ts"; import { writeStdio } from "../output/output.layer.ts"; import { @@ -26,7 +27,8 @@ import { CliErrorKind, } from "../telemetry/error-actionability.ts"; import { isMachineResourceFormat } from "../output/resource-format.ts"; -import { readLongFlag, readOutputFlag } from "./agent-output.ts"; +import type { OutputFormat } from "../output/types.ts"; +import { readOutputFlag } from "./agent-output.ts"; import { findCommand, resolvedCommandPathForArgv, @@ -113,6 +115,14 @@ const failure = ( document: { code, status: null, message, hint, ...extras }, }); +/** Declared categories meaning the invocation or the project config must change before a retry can work. */ +const USAGE_CATEGORIES: ReadonlySet = new Set([ + CliErrorCategory.InvalidInput, + CliErrorCategory.ProjectNotLinked, + CliErrorCategory.MissingProjectRef, + CliErrorCategory.InvalidConfig, +]); + const messageOf = (error: unknown, fallback: string): string => error instanceof Error && error.message.trim().length > 0 ? error.message : fallback; @@ -130,6 +140,12 @@ const failureForError = ( document: documentForStatus(error.status, error.message, error), }; } + if (error instanceof LinkBranchListStatusError) { + return { + exitCode: EXIT_FAILURE, + document: documentForStatus(error.status, error.message, {}), + }; + } if (error instanceof ApiCommandUsageError) { return failure(EXIT_USAGE, "usage_error", error.message, error.hint ?? null); } @@ -174,11 +190,20 @@ const failureForError = ( const declared = classifyCliErrorActionability(error); if ( declared.error_kind === CliErrorKind.UserActionable && - declared.error_category === CliErrorCategory.InvalidInput + USAGE_CATEGORIES.has(declared.error_category) ) { const normalized = normalizeCause(cause, context); return failure(EXIT_USAGE, "usage_error", normalized.message, normalized.suggestion ?? null); } + if (declared.error_kind === CliErrorKind.ExternalService) { + const normalized = normalizeCause(cause, context); + return failure( + EXIT_FAILURE, + declared.error_category === CliErrorCategory.Network ? "network_error" : "api_error", + normalized.message, + normalized.suggestion ?? null, + ); + } return failure(EXIT_FAILURE, "internal_error", normalizeCause(cause).message); }; @@ -210,19 +235,15 @@ export const errorsContractForRun = ( return node === undefined ? "legacy" : readCommandErrorsContract(node); }; -/** Whether failures render as the JSON document: a machine `-o` or `--output-format`, or stdout that is not a TTY. */ +/** Whether failures render as the JSON document: a machine `-o`, a resolved non-text output format, or stdout that is not a TTY. */ export const isMachineFailureMode = ( args: ReadonlyArray, stdoutIsTty: boolean, -): boolean => { - const outputFormat = readLongFlag(args, "--output-format"); - return ( - !stdoutIsTty || - outputFormat === "json" || - outputFormat === "stream-json" || - isMachineResourceFormat(Option.fromNullishOr(readOutputFlag(args))) - ); -}; + outputFormat: OutputFormat, +): boolean => + !stdoutIsTty || + outputFormat !== "text" || + isMachineResourceFormat(Option.fromNullishOr(readOutputFlag(args))); /** Renders the failure as the stderr text: a leading blank line plus JSON, or a human message and hint. */ const renderStandardFailure = (pending: PendingStandardFailure): string => { diff --git a/apps/cli/src/shared/cli/standard-errors.unit.test.ts b/apps/cli/src/shared/cli/standard-errors.unit.test.ts index a0ae14fd57..4bf0b59cb1 100644 --- a/apps/cli/src/shared/cli/standard-errors.unit.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.unit.test.ts @@ -16,6 +16,15 @@ import { ApiCommandUsageError, ApiCommandWaitTimeoutError, } from "../../commands/api/api-command.errors.ts"; +import { + LinkBranchListNetworkError, + LinkBranchListStatusError, + LinkBranchNotFoundError, + LinkBranchNotLinkedError, + LinkBranchNotReadyError, + LinkParentRefInvalidError, +} from "../../command-internal/target/branch-resolution.errors.ts"; +import { ProjectRefNotLinkedError } from "../../config/project-ref.errors.ts"; import { standardFailureFor } from "./standard-errors.ts"; const request = HttpClientRequest.get("https://api.example.test/v1/projects"); @@ -153,6 +162,61 @@ describe("standardFailureFor", () => { hint: "Pass only one target flag.", }, }, + { + name: "unlinked project", + cause: Cause.fail(new ProjectRefNotLinkedError({ message: "Cannot find project ref." })), + expected: { exitCode: 2, code: "usage_error", status: null, hint: null }, + }, + { + name: "branch without a linked parent", + cause: Cause.fail( + new LinkBranchNotLinkedError({ message: "No parent.", suggestion: "Run supabase link." }), + ), + expected: { exitCode: 2, code: "usage_error", status: null, hint: "Run supabase link." }, + }, + { + name: "invalid linked parent ref", + cause: Cause.fail( + new LinkParentRefInvalidError({ message: "Bad ref.", suggestion: "Re-run supabase link." }), + ), + expected: { exitCode: 2, code: "usage_error", status: null, hint: "Re-run supabase link." }, + }, + { + name: "unknown branch", + cause: Cause.fail( + new LinkBranchNotFoundError({ message: "No such branch.", suggestion: "List branches." }), + ), + expected: { exitCode: 2, code: "usage_error", status: null, hint: "List branches." }, + }, + { + name: "branch not ready", + cause: Cause.fail( + new LinkBranchNotReadyError({ branch: "b", status: "CREATING_PROJECT", message: "Wait." }), + ), + expected: { exitCode: 1, code: "api_error", status: null, hint: null }, + }, + { + name: "branch list transport failure", + cause: Cause.fail(new LinkBranchListNetworkError({ message: "offline" })), + expected: { exitCode: 1, code: "network_error", status: null, hint: null }, + }, + { + name: "branch list decode failure", + cause: Cause.fail(new LinkBranchListNetworkError({ message: "bad body", decode: true })), + expected: { exitCode: 1, code: "api_error", status: null, hint: null }, + }, + ...[ + [401, "unauthenticated"], + [403, "forbidden"], + [404, "not_found"], + [500, "api_error"], + ].map(([status, code]) => ({ + name: `branch list status ${status}`, + cause: Cause.fail( + new LinkBranchListStatusError({ status: Number(status), body: "", message: "failed" }), + ), + expected: { exitCode: 1, code: String(code), status: Number(status), hint: null }, + })), { name: "defect", cause: Cause.die(new Error("boom")), diff --git a/apps/cli/tests/fixtures/standard-errors-cli.ts b/apps/cli/tests/fixtures/standard-errors-cli.ts index 80619e72b0..ee0d15c1e6 100644 --- a/apps/cli/tests/fixtures/standard-errors-cli.ts +++ b/apps/cli/tests/fixtures/standard-errors-cli.ts @@ -65,5 +65,5 @@ if (simulateTty) { } await Effect.runPromise( - runCli(root, { agentDefaultOutputFormat: "text", analyticsLayer: mockAnalytics().layer }), + runCli(root, { agentDefaultOutputFormat: "json", analyticsLayer: mockAnalytics().layer }), ); diff --git a/apps/cli/tests/helpers/cli.ts b/apps/cli/tests/helpers/cli.ts index 8e9e638951..e3a3607dd4 100644 --- a/apps/cli/tests/helpers/cli.ts +++ b/apps/cli/tests/helpers/cli.ts @@ -33,10 +33,8 @@ const BINARY_EXT = process.platform === "win32" ? ".exe" : ""; const SHIM_PATH = fileURLToPath(new URL("../../dist/supabase.js", import.meta.url)); const BINARY_PATH = fileURLToPath(new URL(`../../dist/supabase${BINARY_EXT}`, import.meta.url)); -// E2E subprocesses should only enter agent output mode when a test explicitly -// opts in via `options.env`. Keep this list aligned with @vercel/detect-agent -// env probes so a developer's shell cannot accidentally change CLI rendering. -const AGENT_DETECTION_ENV_KEYS: readonly string[] = [ +/** Env probes from `@vercel/detect-agent`; subprocess tests clear them so the developer's shell cannot switch the CLI into agent output mode. */ +export const AGENT_DETECTION_ENV_KEYS: readonly string[] = [ "AI_AGENT", "CURSOR_TRACE_ID", "CURSOR_AGENT", From 4468e672463250fef6170fc18b4fc83e8b7da593 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 16 Nov 2026 17:41:13 +0100 Subject: [PATCH 05/45] feat(cli): support more generated command shapes and harden the generator Generated commands gain nested groups, one positional argument, header flags, action verbs, file-only body fields and reads that poll themselves, so `warehouse status --wait` waits for a final status. The generator rejects what the runtime cannot send safely: a secret held at any depth of a body field without a masked flag, secret header or query parameters, non-string positionals, nullable wait pointers and link expressions other than the project ref and response pointers. The runtime rejects an empty or dot-segment positional before any request. The command surface moves under `src/cli`, and the shared API command errors and stage annotation move under `src/command-internal`. The command policy replaces the override table, and the dry-run preview lists headers. --- apps/cli/scripts/api-command-derive.ts | 366 +++-- .../scripts/api-command-derive.unit.test.ts | 1251 ++++++++++++----- apps/cli/scripts/generate-api-commands.ts | 7 +- .../command-surface.integration.test.ts | 19 +- .../command-surface/command-surface.ts | 49 +- .../command-errors}/api-command.errors.ts | 0 .../command-stage.annotation.ts} | 19 +- .../api-command-bindings.integration.test.ts | 4 +- .../src/commands/api/api-command-execute.ts | 79 +- .../cli/src/commands/api/api-command-flags.ts | 20 +- ...and-overrides.ts => api-command-policy.ts} | 30 +- .../src/commands/api/api-command-request.ts | 61 +- .../api-command-shapes.integration.test.ts | 366 +++++ .../cli/src/commands/api/api-command.model.ts | 30 +- .../src/commands/api/api-commands.e2e.test.ts | 47 +- .../api/api-commands.integration.test.ts | 183 ++- apps/cli/src/commands/api/generated.ts | 16 +- apps/cli/src/commands/api/runtime.ts | 173 ++- .../api/warehouse/enable/SIDE_EFFECTS.md | 12 +- .../api/warehouse/status/SIDE_EFFECTS.md | 44 +- apps/cli/src/shared/cli/standard-errors.ts | 2 +- .../shared/cli/standard-errors.unit.test.ts | 2 +- .../cli/tests/fixtures/standard-errors-cli.ts | 2 +- 23 files changed, 2072 insertions(+), 710 deletions(-) rename apps/cli/src/{command-internal => cli}/command-surface/command-surface.integration.test.ts (89%) rename apps/cli/src/{command-internal => cli}/command-surface/command-surface.ts (85%) rename apps/cli/src/{commands/api => command-internal/command-errors}/api-command.errors.ts (100%) rename apps/cli/src/{commands/api/api-command-stage.ts => command-internal/command-stage/command-stage.annotation.ts} (53%) rename apps/cli/src/commands/api/{api-command-overrides.ts => api-command-policy.ts} (52%) create mode 100644 apps/cli/src/commands/api/api-command-shapes.integration.test.ts diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 15ad9b528e..95170f0ef2 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -2,10 +2,9 @@ import type { OperationId } from "@supabase/api/effect"; import { Cause, Exit, Predicate, Schema } from "effect"; import { verbVocabulary, - type ApiCommandOverride, type ApiCommandPoll, type ApiNoun, -} from "../src/commands/api/api-command-overrides.ts"; +} from "../src/commands/api/api-command-policy.ts"; import type { ApiCommandBinding, ApiCommandEntry, @@ -44,6 +43,10 @@ const VERBS: ReadonlySet = new Set(verbVocabulary); const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const; const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u; +const MAX_COMMAND_WORDS = 4; +/** Headers the request builder owns; a spec that declares them gets no flag. */ +const UNMAPPED_HEADERS: ReadonlySet = new Set(["authorization", "content-type", "accept"]); +const NON_SECRET_HEADERS: ReadonlySet = new Set(["idempotency-key"]); export class ApiCommandGenerationError extends Schema.TaggedError()( "ApiCommandGenerationError", @@ -82,8 +85,6 @@ interface DeriveInput { readonly spec: JsonObject; /** Operation ids that generate commands; `x-operation` on any other operation is ignored. */ readonly generated: ReadonlyArray; - /** Per-operation CLI metadata; its fields win over the spec's `x-operation`. */ - readonly overrides: Readonly>; readonly nouns: Readonly>; /** Kebab-case operation id to the camelCase key of the typed client's `operationDefinitions`. */ readonly operationIdMap: Readonly>; @@ -106,12 +107,9 @@ interface Operation { } interface OperationMetadata { - readonly group?: string; - readonly method?: string; - readonly flags: Readonly>; - readonly sensitive: ReadonlyArray; + readonly group: string; + readonly method: string; readonly poll?: ApiCommandPoll; - readonly wait?: ApiCommandWait; } interface FlagShape { @@ -321,6 +319,14 @@ const classifySuccess = ( return classified[0]; }; +const STABILITY_NOTICE = /\s*This endpoint is currently in its \*\*[^*]+\*\* stage\.\s*$/u; + +/** The description without the stage paragraph the spec appends to it; `undefined` when nothing is left. */ +const stripStabilityNotice = (description: string | undefined): string | undefined => { + const stripped = description?.replace(STABILITY_NOTICE, "").trim(); + return stripped === undefined || stripped === "" ? undefined : stripped; +}; + const kebabCase = (field: string): string => field .replace(/([a-z0-9])([A-Z])/gu, "$1-$2") @@ -375,6 +381,41 @@ const isSecretField = (spec: JsonObject, raw: unknown): boolean => { ); }; +/** + * The dotted path of the first secret a schema holds at any depth: a schema marked secret or a + * property with a credential-like name. `visited` ends the walk on a recursive schema. + */ +const findSecret = ( + spec: JsonObject, + raw: unknown, + path: string, + visited: Set = new Set(), +): string | undefined => { + const schema = asRecord(resolve(spec, raw)); + if (schema === undefined || visited.has(schema)) return undefined; + visited.add(schema); + if (isSecretField(spec, schema)) return path; + const properties = Object.entries(asRecord(schema.properties) ?? {}); + const credential = properties.find(([name]) => credentialLike(name)); + if (credential !== undefined) return `${path}.${credential[0]}`; + const children: ReadonlyArray = [ + ...properties.map(([name, child]) => [`${path}.${name}`, child] as const), + [`${path}[]`, schema.items], + [path, schema.additionalProperties], + ...Object.values(asRecord(schema.patternProperties) ?? {}).map( + (child) => [path, child] as const, + ), + ...SCHEMA_LIST_KEYWORDS.flatMap((keyword) => + asArray(schema[keyword]).map((child) => [path, child] as const), + ), + ]; + for (const [childPath, child] of children) { + const found = findSecret(spec, child, childPath, visited); + if (found !== undefined) return found; + } + return undefined; +}; + const schemaDescription = (spec: JsonObject, raw: unknown): string | undefined => asString(asRecord(resolve(spec, raw))?.description); @@ -396,6 +437,20 @@ const resolvePointer = (spec: JsonObject, root: unknown, pointer: string): unkno return current; }; +/** Whether `pointer` names a property that is required at every object level it passes through. */ +const pointerAlwaysPresent = (spec: JsonObject, root: unknown, pointer: string): boolean => { + if (!pointer.startsWith("/")) return false; + let current = resolve(spec, root); + for (const segment of pointer.slice(1).split("/")) { + const node = asRecord(current); + const property = asRecord(node?.properties)?.[segment]; + if (property === undefined || !asArray(node?.required).includes(segment)) return false; + current = resolve(spec, property); + if (asRecord(current)?.nullable === true) return false; + } + return true; +}; + /** The JSON media type a response offers: `application/json` or a `+json` suffix type. */ const jsonMediaType = (content: JsonObject): string | undefined => Object.keys(content).find((type) => type === "application/json" || type.endsWith("+json")); @@ -439,57 +494,51 @@ const operationParameters = (spec: JsonObject, operation: Operation): ReadonlyAr .map((raw) => asRecord(resolve(spec, raw))) .filter(Predicate.isNotUndefined); -/** Merges each generated operation's `x-operation` with its override entry; the override wins field by field. */ -const mergeMetadata = ( +/** Reads each generated operation's `x-operation`. */ +const readMetadata = ( operations: ReadonlyMap, generated: ReadonlyArray, - overrides: Readonly>, problems: Array, ): ReadonlyMap => { - const merged = new Map(); - for (const operationId of Object.keys(overrides)) { - if (!generated.includes(operationId)) { - problems.push(`${operationId}: override entry is for an operation that is not generated`); - } - } + const metadata = new Map(); for (const operationId of generated) { const operation = operations.get(operationId); if (operation === undefined) { problems.push(`${operationId}: generated operation has no operation in the spec`); continue; } - const override = overrides[operationId]; const block = operation.node["x-operation"]; - let fromSpec: XOperation | undefined; - if (block !== undefined) { - const decoded = decodeXOperation(block); - if (Exit.isFailure(decoded)) { - problems.push(`${operationId}: invalid x-operation: ${Cause.pretty(decoded.cause)}`); - continue; - } - fromSpec = decoded.value; - } - const group = override?.group ?? fromSpec?.group; - const method = override?.method ?? fromSpec?.method; - if (group === undefined || method === undefined) { - problems.push(`${operationId}: no command name; set group and method`); - } - const poll = override?.poll ?? fromSpec?.poll; - merged.set(operationId, { - ...(group === undefined ? {} : { group }), - ...(method === undefined ? {} : { method }), - flags: { ...override?.flags }, - sensitive: [...(override?.sensitive ?? [])], - ...(poll === undefined ? {} : { poll }), - ...(override?.wait === undefined ? {} : { wait: override.wait }), - }); + if (block === undefined) { + problems.push(`${operationId}: no command name; set x-operation group and method`); + continue; + } + const decoded = decodeXOperation(block); + if (Exit.isFailure(decoded)) { + problems.push(`${operationId}: invalid x-operation: ${Cause.pretty(decoded.cause)}`); + continue; + } + const { group, method, poll } = decoded.value; + metadata.set(operationId, { group, method, ...(poll === undefined ? {} : { poll }) }); if (poll !== undefined && operation.method !== "GET") { problems.push(`${operationId}: poll belongs on a read operation, not ${operation.method}`); } } - return merged; + return metadata; }; +const pollWait = ( + read: string, + params: Readonly>, + poll: ApiCommandPoll, +): ApiCommandWait => ({ + read, + params, + status: poll.status, + succeeded: poll.succeeded, + failed: poll.failed, + ...(poll.error === undefined ? {} : { error: poll.error }), +}); + const RESPONSE_POINTER = /^\$response\.body#(\/.*)$/u; const REQUEST_PATH = /^\$request\.path\.(.+)$/u; @@ -542,7 +591,11 @@ const linkedWait = ( operationParameters(spec, candidate).some( (item) => item.in === "path" && item.name === pathName, ); - if (parameter !== pathName || !hasPath(target) || !hasPath(operation)) { + if (pathName !== "ref") { + fail( + `link "${linkName}" parameter "${parameter}": only "$request.path.ref" is supported in this runtime`, + ); + } else if (parameter !== pathName || !hasPath(target) || !hasPath(operation)) { fail( `link "${linkName}" parameter "${parameter}": "${String(expression)}" needs a path parameter of that name on both operations`, ); @@ -553,14 +606,7 @@ const linkedWait = ( ); } } - waits.push({ - read: targetId, - params, - status: poll.status, - succeeded: poll.succeeded, - failed: poll.failed, - ...(poll.error === undefined ? {} : { error: poll.error }), - }); + waits.push(pollWait(targetId, params, poll)); } } if (waits.length > 1) { @@ -572,24 +618,20 @@ const linkedWait = ( return waits[0]; }; -/** Derives the generated commands from the merged `x-operation` and override metadata and collects every lint failure. */ +/** Derives the generated commands from each operation's `x-operation` and collects every lint failure. */ export function deriveApiCommands(input: DeriveInput): DeriveResult { - const { spec, generated, overrides, nouns, operationIdMap, handWrittenTopLevel } = input; + const { spec, generated, nouns, operationIdMap, handWrittenTopLevel } = input; const operations = collectOperations(spec); const problems: Array = []; - const metadata = mergeMetadata(operations, generated, overrides, problems); - const commandNamed = new Set( - [...metadata].flatMap(([id, item]) => - item.group !== undefined && item.method !== undefined ? [id] : [], - ), - ); + const metadata = readMetadata(operations, generated, problems); + const commandNamed = new Set(metadata.keys()); const entries: Array = []; const schemas: Record = {}; const commandOwners = new Map(); + const groupPaths = new Set(); for (const [operationId, name] of metadata) { const { group, method } = name; - if (group === undefined || method === undefined) continue; const fail = (reason: string) => problems.push(`${operationId}: ${reason}`); const operation = operations.get(operationId); if (operation === undefined) continue; @@ -600,8 +642,10 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { } const failuresBefore = problems.length; - const command = [group, method]; - if (group.includes(".")) fail(`group "${group}" must be a single noun`); + const command = [...group.split("."), method]; + if (command.length > MAX_COMMAND_WORDS) { + fail(`command "${command.join(" ")}" has more than four words`); + } if (!command.every((segment) => KEBAB.test(segment))) { fail(`command "${command.join(" ")}" must be lowercase kebab-case words`); } @@ -611,28 +655,35 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const noun = nouns[command[0] ?? ""]; if (noun === undefined) { fail(`noun "${command[0]}" is missing from the nouns table`); + continue; } const commandKey = command.join(" "); const owner = commandOwners.get(commandKey); if (owner !== undefined) fail(`command "${commandKey}" is already generated by ${owner}`); commandOwners.set(commandKey, operationId); + if (groupPaths.has(commandKey)) fail(`command "${commandKey}" is both a command and a group`); + for (let depth = 2; depth < command.length; depth += 1) { + const groupKey = command.slice(0, depth).join(" "); + if (commandOwners.has(groupKey)) fail(`command "${groupKey}" is both a command and a group`); + groupPaths.add(groupKey); + const subGroup = command.slice(1, depth).join("."); + if (noun.groups?.[subGroup] === undefined) { + fail(`group "${subGroup}" has no description in the nouns table`); + } + } if (handWrittenTopLevel.has(command[0] ?? "")) { fail(`command "${commandKey}" collides with the hand-written "${command[0]}" command`); } const stability = asString(operation.node["x-scalar-stability"]); if (stability !== "experimental") { - fail( - "stable generated commands need the R8 baseline check, not implemented yet (x-scalar-stability must be experimental)", - ); + fail("only operations marked experimental can be generated (x-scalar-stability)"); } const summary = asString(operation.node.summary); if (summary === undefined) fail("operation has no summary"); - const renames = name.flags; - const sensitive = name.sensitive; const fields: Array<{ - readonly location: "query" | "body"; + readonly location: "query" | "header" | "body"; readonly key: string; readonly pointer?: string; readonly shape: FlagShape; @@ -641,21 +692,74 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { readonly writeOnly: boolean; }> = []; + const fileOnlyFields: Array = []; const pathBindings: Array = []; + const pathNames: Array = []; + const positionals: Array<{ + readonly name: string; + readonly parameter: string; + readonly description: string | undefined; + }> = []; for (const parameter of operationParameters(spec, operation)) { const parameterName = asString(parameter.name) ?? ""; switch (parameter.in) { - case "path": + case "path": { + pathNames.push(parameterName); if (parameterName === "ref") { pathBindings.push({ location: "path", name: "ref", source: "target" }); + break; + } + const shape = describeFlagSchema(spec, parameter.schema); + if (shape === undefined || shape.repeatable) { + fail(`unsupported in this runtime: path parameter "${parameterName}" is not a scalar`); + } else if (shape.type !== "string") { + fail(`unsupported in this runtime: path parameter "${parameterName}" is not a string`); } else { - fail(`unsupported in this runtime: path parameter "${parameterName}"`); + positionals.push({ + name: kebabCase(parameterName), + parameter: parameterName, + description: + asString(parameter.description) ?? schemaDescription(spec, parameter.schema), + }); } break; + } + case "header": { + const lowerName = parameterName.toLowerCase(); + if (UNMAPPED_HEADERS.has(lowerName)) break; + const shape = describeFlagSchema(spec, parameter.schema); + if ( + isSecretField(spec, parameter.schema) || + (credentialLike(parameterName) && !NON_SECRET_HEADERS.has(lowerName)) + ) { + fail( + `unsupported in this runtime: header parameter "${parameterName}" carries a credential, and the dry-run preview masks only body fields`, + ); + } else if (shape === undefined || shape.repeatable) { + fail( + `unsupported in this runtime: header parameter "${parameterName}" is not a scalar`, + ); + } else { + fields.push({ + location: "header", + key: parameterName, + shape, + required: parameter.required === true, + description: + asString(parameter.description) ?? schemaDescription(spec, parameter.schema), + writeOnly: false, + }); + } + break; + } case "query": { const shape = describeFlagSchema(spec, parameter.schema); if (parameterName === "dry_run") { fail('unsupported in this runtime: server-side "dry_run" parameter'); + } else if (isSecretField(spec, parameter.schema)) { + fail( + `unsupported in this runtime: query parameter "${parameterName}" is a secret, and the dry-run preview masks only body fields`, + ); } else if (shape === undefined || shape.repeatable) { fail(`unsupported in this runtime: query parameter "${parameterName}" is not a scalar`); } else { @@ -716,9 +820,17 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { if (field === "dry_run") { fail('unsupported in this runtime: server-side "dry_run" body field'); } else if (shape === undefined) { - fail( - `unsupported in this runtime: body field "${field}" is not a scalar, string enum or array of scalars`, - ); + const secret = findSecret(spec, schema, field); + if (secret !== undefined) { + fail( + `unsupported in this runtime: body field "${field}" ${secret === field ? "is a secret" : `holds the secret "${secret}"`} without a flag, and the dry-run preview masks only flag-bound fields`, + ); + } else if (credentialLike(field)) { + fail( + `body field "${field}" looks like a credential; mark its schema writeOnly, format: password or x-sensitive`, + ); + } + fileOnlyFields.push(field); } else { fields.push({ location: "body", @@ -729,57 +841,67 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { shape, required: required.includes(field), description: schemaDescription(spec, schema), - writeOnly: isSecretField(spec, schema), + writeOnly: findSecret(spec, schema, field) !== undefined, }); } } } } - for (const key of Object.keys(renames)) { - if (!fields.some((field) => field.key === key)) { - fail(`flags rename "${key}" matches no query parameter or body field`); - } - } - for (const key of sensitive) { - if (!fields.some((field) => field.location === "body" && field.key === key)) { - fail(`sensitive "${key}" matches no body field`); - } - } - if (pathBindings.length === 0) { fail('unsupported in this runtime: operation has no "ref" path parameter'); } + const [positional, ...extraPositionals] = positionals; + if (extraPositionals.length > 0) { + fail('unsupported in this runtime: more than one path parameter besides "ref"'); + } + if (positional !== undefined) { + if (!KEBAB.test(positional.name)) { + fail(`argument "${positional.name}" must be lowercase kebab-case`); + } + pathBindings.push({ + location: "path", + name: positional.parameter, + source: "argument", + argument: positional.name, + }); + } const flags: Array = []; const bindings: Array = [...pathBindings]; const seenNames = new Set(); - const seenKeys = new Set(); + const seenKeys = new Set(pathNames); + for (const key of fileOnlyFields) { + if (seenKeys.has(key)) { + fail( + `"${key}" is used by more than one of: path parameter, header parameter, query parameter, body field`, + ); + } + seenKeys.add(key); + } for (const field of fields) { - const conventional = + const flagName = field.location === "body" && field.shape.repeatable ? singular(kebabCase(field.key)) : kebabCase(field.key); - const flagName = renames[field.key] ?? conventional; if (!KEBAB.test(flagName)) fail(`flag "${flagName}" must be lowercase kebab-case`); if (RESERVED_FLAGS.has(flagName)) { - fail( - `flag "--${flagName}" (from "${field.key}") collides with a reserved runtime flag; rename it`, - ); + fail(`flag "--${flagName}" (from "${field.key}") collides with a reserved runtime flag`); } if (seenNames.has(flagName)) { - fail(`flag "--${flagName}" (from "${field.key}") is produced twice; rename one`); + fail(`flag "--${flagName}" (from "${field.key}") is produced twice`); } if (seenKeys.has(field.key)) { - fail(`"${field.key}" is both a query parameter and a body field`); + fail( + `"${field.key}" is used by more than one of: path parameter, header parameter, query parameter, body field`, + ); } seenNames.add(flagName); seenKeys.add(field.key); - const isSensitive = - field.location === "body" && (field.writeOnly || sensitive.includes(field.key)); + const isSensitive = field.location === "body" && field.writeOnly; if (field.location === "body" && credentialLike(field.key) && !isSensitive) { fail( - `body field "${field.key}" looks like a credential; review it and list it under sensitive`, + `body field "${field.key}" looks like a credential; mark its schema writeOnly, format: password or x-sensitive`, ); } bindings.push( @@ -791,7 +913,12 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { source: "flag", flag: flagName, } - : { location: "query", name: field.key, source: "flag", flag: flagName }, + : { + location: field.location === "header" ? "header" : "query", + name: field.key, + source: "flag", + flag: flagName, + }, ); flags.push({ name: flagName, @@ -804,7 +931,12 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { }); } - const wait = name.wait ?? linkedWait(spec, operations, metadata, operation, fail); + const linked = linkedWait(spec, operations, metadata, operation, fail); + const ownPoll = name.poll; + if (ownPoll !== undefined && linked !== undefined) { + fail(`declares poll and also links to the polled operation "${linked.read}"; use one`); + } + const wait = linked ?? (ownPoll === undefined ? undefined : pollWait(operationId, {}, ownPoll)); if (wait !== undefined) { lintWait({ spec, operations, commandNamed, operation, wait, fail }); } @@ -833,7 +965,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { if (problems.length > failuresBefore || summary === undefined) continue; if (response === undefined || schemaSet === undefined) continue; schemas[operationId] = schemaSet; - const description = asString(operation.node.description)?.trim(); + const description = stripStabilityNotice(asString(operation.node.description)); entries.push({ command, operationId, @@ -841,13 +973,21 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { method: operation.method, apiPath: operation.path, summary, - ...(description === undefined || description === "" ? {} : { description }), - scope: "project", + ...(description === undefined ? {} : { description }), readOnly: operation.method === "GET", - stability: "experimental", - ...(noun?.feature === undefined ? {} : { feature: noun.feature }), + feature: noun.feature, ...(body === undefined ? {} : { body }), response: { status: response.status, kind: response.kind }, + ...(positional === undefined + ? {} + : { + argument: { + name: positional.name, + ...(positional.description === undefined + ? {} + : { description: positional.description }), + }, + }), flags, bindings, ...(wait === undefined ? {} : { wait }), @@ -879,21 +1019,31 @@ function lintWait(input: { } const readParameters = operationParameters(spec, readOperation); - const queryNames = new Set( - readParameters.filter((parameter) => parameter.in === "query").map((p) => asString(p.name)), + const suppliable = new Set( + readParameters + .filter( + (parameter) => + parameter.in === "query" || (parameter.in === "path" && parameter.name !== "ref"), + ) + .map((p) => asString(p.name)), ); const changeResponse = successSchema(spec, operation); for (const [parameter, pointer] of Object.entries(wait.params)) { - if (!queryNames.has(parameter)) { - fail(`wait.params "${parameter}" is not a query parameter of ${wait.read}`); + if (!suppliable.has(parameter)) { + fail(`wait.params "${parameter}" is not a query or path parameter of ${wait.read}`); } if (resolvePointer(spec, changeResponse, pointer) === undefined) { fail(`wait.params "${parameter}" pointer "${pointer}" does not resolve in the response`); + } else if (!pointerAlwaysPresent(spec, changeResponse, pointer)) { + fail( + `wait.params "${parameter}" pointer "${pointer}" is not required at every level of the response, so --wait could have nothing to poll with`, + ); } } for (const parameter of readParameters) { const parameterName = asString(parameter.name); if ( + wait.read !== operation.id && parameter.required === true && parameterName !== undefined && parameterName !== "ref" && diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index c890a9ce52..c49152e662 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "@effect/vitest"; -import type { ApiCommandOverride } from "../src/commands/api/api-command-overrides.ts"; +import type { ApiNoun } from "../src/commands/api/api-command-policy.ts"; import { deriveApiCommands } from "./api-command-derive.ts"; const DIALECT = "https://json-schema.org/draft/2020-12/schema"; @@ -39,42 +39,63 @@ const envelope = (attributes: Record) => ({ }, }); +const thingNoun: ApiNoun = { + description: "Manage things", + feature: "things", + groups: { sub: "Manage sub things", "sub.deep": "Manage deep things", status: "Status" }, +}; + +/** The spec path of an operation: the project ref, then one segment per other path parameter. */ +const pathOf = (id: string, node: unknown): string => { + const parameters: unknown = Reflect.get(Object(node), "parameters"); + const extra = Array.isArray(parameters) + ? parameters + .filter((parameter) => parameter.in === "path" && parameter.name !== "ref") + .map((parameter) => `/{${parameter.name}}`) + : []; + return `/v1/projects/{ref}/${id}${extra.join("")}`; +}; + const derive = ( operations: Record, - overrides: Record, generated: ReadonlyArray = Object.keys(operations), + options: { + readonly schemas?: Record; + readonly overrides?: Partial[0]>; + } = {}, ) => deriveApiCommands({ spec: { paths: Object.fromEntries( Object.entries(operations).map(([id, node]) => [ - `/v1/projects/{ref}/${id}`, + pathOf(id, node), { [id.startsWith("get-") ? "get" : "post"]: { operationId: id, ...(node as object) } }, ]), ), - components: { schemas: { Tags: { type: "array", items: { type: "string" } } } }, + components: { + schemas: { Tags: { type: "array", items: { type: "string" } }, ...options.schemas }, + }, }, generated, - overrides, - nouns: { thing: { description: "Manage things", feature: "things" } }, + nouns: { thing: thingNoun }, operationIdMap: Object.fromEntries( Object.keys(operations).map((id) => [id, "v2EnableWarehouse" as const]), ), handWrittenTopLevel: new Set(["db"]), + ...options.overrides, }); -const create: ApiCommandOverride = { group: "thing", method: "create" }; +const named = (method: string) => ({ "x-operation": { group: "thing", method } }); +const create = named("create"); describe("deriveApiCommands", () => { it("binds envelope body fields by JSON pointer and the project ref to the target", () => { - const result = derive( - { - "create-thing": operation({ - requestBody: envelope({ tags: { type: "array", items: { type: "string" } } }), - }), - }, - { "create-thing": create }, - ); + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: envelope({ tags: { type: "array", items: { type: "string" } } }), + }), + }); expect(result.problems).toEqual([]); const [entry] = result.entries; @@ -108,24 +129,22 @@ describe("deriveApiCommands", () => { }); it("binds plain body fields at the body root and inlines referenced schemas", () => { - const result = derive( - { - "create-thing": operation({ - requestBody: { - content: { - "application/json": { - schema: { - type: "object", - properties: { display_name: { type: "string" } }, - }, + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: { + content: { + "application/json": { + schema: { + type: "object", + properties: { display_name: { type: "string" } }, }, }, }, - responses: jsonResponse({ $ref: "#/components/schemas/Tags" }), - }), - }, - { "create-thing": create }, - ); + }, + responses: jsonResponse({ $ref: "#/components/schemas/Tags" }), + }), + }); expect(result.problems).toEqual([]); expect(result.entries[0]?.body?.kind).toBe("json-object"); @@ -144,18 +163,16 @@ describe("deriveApiCommands", () => { }); it("turns a string enum query parameter into flag choices and an empty response into null", () => { - const result = derive( - { - "list-things": operation({ - parameters: [ - { name: "ref", in: "path", required: true, schema: { type: "string" } }, - { name: "sort", in: "query", schema: { type: "string", enum: ["asc", "desc"] } }, - ], - responses: { "204": { description: "none" } }, - }), - }, - { "list-things": { group: "thing", method: "list" } }, - ); + const result = derive({ + "list-things": operation({ + ...named("list"), + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "sort", in: "query", schema: { type: "string", enum: ["asc", "desc"] } }, + ], + responses: { "204": { description: "none" } }, + }), + }); expect(result.problems).toEqual([]); expect(result.entries[0]?.flags[0]).toMatchObject({ name: "sort", choices: ["asc", "desc"] }); @@ -163,82 +180,179 @@ describe("deriveApiCommands", () => { expect(result.schemas["list-things"]?.result).toEqual({ $schema: DIALECT, type: "null" }); }); - it.each([ - [ - "a nested object body field", - operation({ requestBody: envelope({ nested: { type: "object", properties: {} } }) }), - 'body field "nested"', - ], - [ - "a binary success response", - operation({ + it("derives a plain token-named query parameter as a flag", () => { + const result = derive({ + "list-things": operation({ + ...named("list"), + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "page_token", in: "query", schema: { type: "string" } }, + ], + }), + }); + + expect(result.problems).toEqual([]); + expect(result.entries[0]?.flags[0]).toMatchObject({ name: "page-token" }); + }); + + it("rejects a binary success response", () => { + const result = derive({ + "create-thing": operation({ + ...create, responses: { "200": { description: "file", content: { "application/octet-stream": {} } } }, }), - "binary or streaming", - ], - ])("rejects %s", (_label, node, message) => { - const result = derive({ "create-thing": node }, { "create-thing": create }); + }); expect(result.entries).toEqual([]); - expect(result.problems.join("\n")).toContain(message); + expect(result.problems.join("\n")).toContain("binary or streaming"); }); - it("rejects a body field that collides with a reserved runtime flag", () => { - const result = derive( - { "create-thing": operation({ requestBody: envelope({ wait: { type: "boolean" } }) }) }, - { "create-thing": create }, - ); + describe("body fields without a flag", () => { + const writeOnlyString = { type: "string", writeOnly: true }; + const nestedBody = (nested: Record) => + derive({ + "create-thing": operation({ ...create, requestBody: envelope({ nested }) }), + }); - expect(result.problems.join("\n")).toContain('"--wait"'); - }); + it("keeps the operation and describes the field in the request schema without a flag or binding", () => { + const result = nestedBody({ type: "object", properties: { size: { type: "string" } } }); - it("rejects a wait pointer that does not resolve in the response", () => { - const result = derive( - { - "create-thing": operation({}), - "get-thing": operation({}), - }, - { - "create-thing": { + expect(result.problems).toEqual([]); + const [entry] = result.entries; + expect(entry?.flags.map((flag) => flag.name)).toEqual(["name"]); + expect(entry?.bindings.filter((binding) => binding.location === "body")).toHaveLength(1); + expect(JSON.stringify(result.schemas["create-thing"]?.request)).toContain('"nested"'); + }); + + it("rejects a sensitive field that has no flag", () => { + const result = nestedBody({ + type: "object", + writeOnly: true, + properties: { size: { type: "string" } }, + }); + + expect(result.entries).toEqual([]); + expect(result.problems.join("\n")).toContain( + 'unsupported in this runtime: body field "nested" is a secret without a flag', + ); + }); + + it("rejects an unmarked credential-like field that has no flag", () => { + const result = derive({ + "create-thing": operation({ ...create, - wait: { - read: "get-thing", - params: {}, - status: "/data/attributes/missing", - succeeded: ["done"], - failed: [], - }, + requestBody: envelope({ api_key: { type: "object", properties: {} } }), + }), + }); + + expect(result.problems.join("\n")).toContain('"api_key" looks like a credential'); + }); + + it.each([ + [ + "a writeOnly property", + { type: "object", properties: { size: { type: "string" }, pin: writeOnlyString } }, + "nested.pin", + ], + [ + "a credential-like property name", + { type: "object", properties: { db_password: { type: "string" } } }, + "nested.db_password", + ], + [ + "a secret inside array items", + { type: "array", items: { type: "object", properties: { pin: writeOnlyString } } }, + "nested[].pin", + ], + [ + "a secret two levels down", + { + type: "object", + properties: { inner: { type: "object", properties: { pin: writeOnlyString } } }, }, - "get-thing": { group: "thing", method: "get" }, - }, - ); + "nested.inner.pin", + ], + [ + "a secret in an anyOf member", + { anyOf: [{ type: "object", properties: { pin: writeOnlyString } }, { type: "null" }] }, + "nested.pin", + ], + ])("rejects a file-only field that holds %s", (_label, nested, secretPath) => { + const result = nestedBody(nested); + + expect(result.entries).toEqual([]); + expect(result.problems).toEqual([ + `create-thing: unsupported in this runtime: body field "nested" holds the secret "${secretPath}" without a flag, and the dry-run preview masks only flag-bound fields`, + ]); + }); + + it("rejects a file-only field whose patternProperties value is a secret", () => { + const result = nestedBody({ + type: "object", + patternProperties: { ".*": { type: "string", format: "password" } }, + }); - expect(result.problems.join("\n")).toContain('wait.status pointer "/data/attributes/missing"'); + expect(result.entries).toEqual([]); + expect(result.problems).toEqual([ + 'create-thing: unsupported in this runtime: body field "nested" is a secret without a flag, and the dry-run preview masks only flag-bound fields', + ]); + }); + + it("accepts a file-only field whose schema refers back to itself when it holds no secret", () => { + const node = { + type: "object", + properties: { label: { type: "string" }, child: { $ref: "#/components/schemas/Node" } }, + }; + const result = derive( + { + "create-thing": operation({ + ...create, + requestBody: envelope({ tree: { $ref: "#/components/schemas/Node" } }), + }), + }, + ["create-thing"], + { schemas: { Node: node } }, + ); + + expect(result.problems.join("\n")).not.toContain("secret"); + expect(result.problems).toEqual([ + "create-thing: unsupported in this runtime: recursive schema reference #/components/schemas/Node", + ]); + }); + }); + + it("rejects a body field that collides with a reserved runtime flag", () => { + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: envelope({ wait: { type: "boolean" } }), + }), + }); + + expect(result.problems.join("\n")).toContain('"--wait"'); }); it("converts OpenAPI 3.0 schema keywords to JSON Schema 2020-12", () => { - const result = derive( - { - "get-thing": operation({ - responses: jsonResponse({ - type: "object", - properties: { - name: { type: "string", nullable: true, example: "a" }, - count: { - type: "integer", - minimum: 0, - exclusiveMinimum: true, - maximum: 9, - exclusiveMaximum: false, - }, - any: { nullable: true, description: "free" }, + const result = derive({ + "get-thing": operation({ + ...named("get"), + responses: jsonResponse({ + type: "object", + properties: { + name: { type: "string", nullable: true, example: "a" }, + count: { + type: "integer", + minimum: 0, + exclusiveMinimum: true, + maximum: 9, + exclusiveMaximum: false, }, - discriminator: { propertyName: "name" }, - }), + any: { nullable: true, description: "free" }, + }, + discriminator: { propertyName: "name" }, }), - }, - { "get-thing": { group: "thing", method: "get" } }, - ); + }), + }); expect(result.problems).toEqual([]); expect(result.schemas["get-thing"]?.result).toEqual({ @@ -253,62 +367,60 @@ describe("deriveApiCommands", () => { }); it("rejects a schema keyword it cannot convert", () => { - const result = derive( - { - "get-thing": operation({ - responses: jsonResponse({ type: "string", contentMediaType: "x" }), - }), - }, - { "get-thing": { group: "thing", method: "get" } }, - ); + const result = derive({ + "get-thing": operation({ + ...named("get"), + responses: jsonResponse({ type: "string", contentMediaType: "x" }), + }), + }); expect(result.problems.join("\n")).toContain('keyword "contentMediaType"'); }); - it("names a command from the operation's x-operation alone", () => { - const result = derive( - { "create-thing": operation({ "x-operation": { group: "thing", method: "create" } }) }, - {}, - ); + it("names a command from the operation's x-operation", () => { + const result = derive({ "create-thing": operation(create) }); expect(result.problems).toEqual([]); expect(result.entries.map((entry) => entry.command)).toEqual([["thing", "create"]]); }); - it("lets an override entry replace the name and rename a single flag", () => { - const result = derive( - { - "create-thing": operation({ - "x-operation": { group: "thing", method: "create" }, - requestBody: envelope({ tags: { type: "array", items: { type: "string" } } }), - }), - }, - { "create-thing": { method: "update", flags: { name: "title", tags: "tg" } } }, + it("strips the stage paragraph from the description whatever the stage word", () => { + const describe = (description: string) => + derive({ "create-thing": operation({ ...create, description }) }).entries[0]?.description; + + expect(describe("Does the thing.\n\nThis endpoint is currently in its **Alpha** stage.")).toBe( + "Does the thing.", ); + expect(describe("Does the thing.\n\nThis endpoint is currently in its **Beta** stage.\n")).toBe( + "Does the thing.", + ); + expect(describe("This endpoint is currently in its **Alpha** stage.")).toBeUndefined(); + }); - expect(result.problems).toEqual([]); - const [entry] = result.entries; - expect(entry?.command).toEqual(["thing", "update"]); - expect(entry?.flags.map((flag) => flag.name)).toEqual(["title", "tg"]); + it("generates only operations marked experimental", () => { + const result = derive({ + "create-thing": operation({ ...create, "x-scalar-stability": "beta" }), + }); + + expect(result.entries).toEqual([]); + expect(result.problems.join("\n")).toContain("only operations marked experimental"); }); it("names array body flags in the singular and keeps other fields as they are", () => { const list = { type: "array", items: { type: "string" } }; - const result = derive( - { - "create-thing": operation({ - requestBody: envelope({ - categories: list, - tables: list, - access: list, - status: list, - analysis: list, - sizes: { type: "string" }, - }), + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: envelope({ + categories: list, + tables: list, + access: list, + status: list, + analysis: list, + sizes: { type: "string" }, }), - }, - { "create-thing": create }, - ); + }), + }); expect(result.problems).toEqual([]); expect(result.entries[0]?.flags.map((flag) => flag.name)).toEqual([ @@ -323,120 +435,76 @@ describe("deriveApiCommands", () => { }); it("rejects a singularised flag that collides with another flag", () => { - const result = derive( - { - "create-thing": operation({ - requestBody: envelope({ - table: { type: "string" }, - tables: { type: "array", items: { type: "string" } }, - }), + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: envelope({ + table: { type: "string" }, + tables: { type: "array", items: { type: "string" } }, }), - }, - { "create-thing": create }, - ); + }), + }); expect(result.problems.join("\n")).toContain('"--table"'); }); it("marks writeOnly and password-format body fields sensitive", () => { - const result = derive( - { - "create-thing": operation({ - requestBody: envelope({ - api_secret: { type: "string", writeOnly: true }, - pin: { type: "string", format: "password" }, - }), + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: envelope({ + api_secret: { type: "string", writeOnly: true }, + pin: { type: "string", format: "password" }, + recovery_codes: { type: "array", items: { type: "string", writeOnly: true } }, }), - }, - { "create-thing": create }, - ); + }), + }); expect(result.problems).toEqual([]); expect(result.entries[0]?.flags.map((flag) => [flag.name, flag.sensitive === true])).toEqual([ ["name", false], ["api-secret", true], ["pin", true], + ["recovery-code", true], ]); }); - it("accepts a credential-like field that is marked x-sensitive or listed by the table and rejects it otherwise", () => { + it("accepts a credential-like field that is marked x-sensitive and rejects it otherwise", () => { const body = (api_key: Record) => envelope({ api_key }); const flagOf = (result: ReturnType) => result.entries[0]?.flags.find((flag) => flag.name === "api-key"); - const marked = derive( - { "create-thing": operation({ requestBody: body({ type: "string", "x-sensitive": true }) }) }, - { "create-thing": create }, - ); - const listed = derive( - { "create-thing": operation({ requestBody: body({ type: "string" }) }) }, - { "create-thing": { ...create, sensitive: ["api_key"] } }, - ); - const unreviewed = derive( - { "create-thing": operation({ requestBody: body({ type: "string" }) }) }, - { "create-thing": create }, - ); + const marked = derive({ + "create-thing": operation({ + ...create, + requestBody: body({ type: "string", "x-sensitive": true }), + }), + }); + const unmarked = derive({ + "create-thing": operation({ ...create, requestBody: body({ type: "string" }) }), + }); expect(marked.problems).toEqual([]); expect(flagOf(marked)?.sensitive).toBe(true); - expect(listed.problems).toEqual([]); - expect(flagOf(listed)?.sensitive).toBe(true); - expect(unreviewed.problems.join("\n")).toContain('"api_key" looks like a credential'); - }); - - it("resolves wait pointers from a +json response", () => { - const jsonApi = (schema: unknown) => ({ - "200": { description: "ok", content: { "application/vnd.api+json": { schema } } }, - }); - const result = derive( - { - "create-thing": operation({ - "x-operation": { group: "thing", method: "create" }, - responses: jsonApi({ type: "object", properties: { id: { type: "string" } } }), - }), - "get-thing": operation({ - "x-operation": { group: "thing", method: "get" }, - parameters: [ - { name: "ref", in: "path", required: true, schema: { type: "string" } }, - { name: "thing_id", in: "query", schema: { type: "string" } }, - ], - responses: jsonApi({ - type: "object", - properties: { status: { type: "string", enum: ["done", "pending"] } }, - }), - }), - }, - { - "create-thing": { - wait: { - read: "get-thing", - params: { thing_id: "/id" }, - status: "/status", - succeeded: ["done"], - failed: [], - }, - }, - }, - ); - - expect(result.problems).toEqual([]); - expect(result.entries.find((entry) => entry.operationId === "create-thing")?.wait?.read).toBe( - "get-thing", - ); + expect(unmarked.problems.join("\n")).toContain('"api_key" looks like a credential'); }); describe("wait from response links", () => { - const changeResponse = (links: unknown) => ({ + const requiredChain = { + type: "object", + required: ["data"], + properties: { + data: { type: "object", required: ["id"], properties: { id: { type: "string" } } }, + }, + }; + const changeResponse = ( + links: unknown, + schema: unknown = requiredChain, + mediaType = "json", + ) => ({ "202": { description: "accepted", - content: { - "application/json": { - schema: { - type: "object", - properties: { data: { type: "object", properties: { id: { type: "string" } } } }, - }, - }, - }, + content: { [mediaType === "json" ? "application/json" : mediaType]: { schema } }, links, }, }); @@ -446,100 +514,89 @@ describe("deriveApiCommands", () => { failed: ["broken"], error: "/data/attributes/reason", }; - const readThing = operation({ - "x-operation": { group: "thing", method: "get", poll }, - parameters: [ - { name: "ref", in: "path", required: true, schema: { type: "string" } }, - { name: "thing_id", in: "query", schema: { type: "string" } }, - ], - responses: jsonResponse({ - type: "object", - properties: { - data: { - type: "object", - properties: { - attributes: { - type: "object", - properties: { - status: { type: "string", enum: ["done", "broken", "pending"] }, - reason: { type: "string" }, - }, + const readSchema = { + type: "object", + properties: { + data: { + type: "object", + properties: { + attributes: { + type: "object", + properties: { + status: { type: "string", enum: ["done", "broken", "pending"] }, + reason: { type: "string" }, }, }, }, }, - }), - }); + }, + }; + const readWith = (readPoll: unknown, responses: unknown = jsonResponse(readSchema)) => + operation({ + "x-operation": { group: "thing", method: "get", poll: readPoll }, + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "thing_id", in: "query", schema: { type: "string" } }, + ], + responses, + }); + const readThing = readWith(poll); const link = (parameters: Record, operationId = "get-thing") => ({ setup: { operationId, parameters }, }); - const changeThing = (links: unknown) => - operation({ - "x-operation": { group: "thing", method: "create" }, - responses: changeResponse(links), - }); + const changeThing = (links: unknown, schema?: unknown) => + operation({ ...create, responses: changeResponse(links, schema) }); + const waitOf = (result: ReturnType) => + result.entries.find((entry) => entry.operationId === "create-thing")?.wait; it("builds the wait from the polled target and leaves the shared path parameter to the runtime", () => { - const result = derive( - { - "create-thing": changeThing( - link({ ref: "$request.path.ref", thing_id: "$response.body#/data/id" }), - ), - "get-thing": readThing, - }, - {}, - ); + const result = derive({ + "create-thing": changeThing( + link({ ref: "$request.path.ref", thing_id: "$response.body#/data/id" }), + ), + "get-thing": readThing, + }); expect(result.problems).toEqual([]); - expect(result.entries.find((entry) => entry.operationId === "create-thing")?.wait).toEqual({ + expect(waitOf(result)).toEqual({ read: "get-thing", params: { thing_id: "/data/id" }, ...poll, }); - expect( - result.entries.find((entry) => entry.operationId === "get-thing")?.wait, - ).toBeUndefined(); }); - it("prefers an explicit wait over a link", () => { - const explicit = { - read: "get-thing", - params: {}, - status: "/data/attributes/reason", - succeeded: ["x"], - failed: [], - }; - const result = derive( - { - "create-thing": changeThing(link({ thing_id: "$response.body#/data/id" })), - "get-thing": readThing, - }, - { "create-thing": { wait: explicit } }, - ); + it("resolves wait pointers from +json responses", () => { + const jsonApi = (schema: unknown) => ({ + "200": { description: "ok", content: { "application/vnd.api+json": { schema } } }, + }); + const result = derive({ + "create-thing": operation({ + ...create, + responses: changeResponse( + link({ thing_id: "$response.body#/data/id" }), + requiredChain, + "application/vnd.api+json", + ), + }), + "get-thing": readWith(poll, jsonApi(readSchema)), + }); expect(result.problems).toEqual([]); - expect(result.entries.find((entry) => entry.operationId === "create-thing")?.wait).toEqual( - explicit, - ); + expect(waitOf(result)?.read).toBe("get-thing"); }); it("ignores a link whose target has no poll", () => { - const result = derive( - { - "create-thing": changeThing(link({})), - "get-thing": operation({ "x-operation": { group: "thing", method: "get" } }), - }, - {}, - ); + const result = derive({ + "create-thing": changeThing(link({})), + "get-thing": operation(named("get")), + }); expect(result.problems).toEqual([]); - expect(result.entries.find((entry) => entry.operationId === "create-thing")?.wait).toBe( - undefined, - ); + expect(waitOf(result)).toBeUndefined(); }); it("rejects a link to a polled target that is not generated", () => { - const result = derive({ "create-thing": changeThing(link({})), "get-thing": readThing }, {}, [ + const result = derive({ "create-thing": changeThing(link({})), "get-thing": readThing }, [ "create-thing", ]); @@ -548,6 +605,77 @@ describe("deriveApiCommands", () => { ]); }); + it("derives a self wait on a read that declares its own poll", () => { + const result = derive({ "get-thing": readThing }); + + expect(result.problems).toEqual([]); + expect(result.entries[0]?.wait).toEqual({ read: "get-thing", params: {}, ...poll }); + }); + + it("rejects a read that declares poll and also links to a polled operation", () => { + const result = derive({ + "get-thing": readThing, + "get-other": operation({ + ...readThing, + responses: { + "200": { + description: "ok", + content: { "application/json": { schema: requiredChain } }, + links: link({ thing_id: "$response.body#/data/id" }), + }, + }, + }), + }); + + expect(result.problems.join("\n")).toContain( + 'declares poll and also links to the polled operation "get-thing"; use one', + ); + }); + + it("rejects a poll status pointer that does not resolve in the read response", () => { + const result = derive({ + "create-thing": changeThing(link({ thing_id: "$response.body#/data/id" })), + "get-thing": readWith({ ...poll, status: "/data/attributes/missing" }), + }); + + expect(result.problems.join("\n")).toContain( + 'wait.status pointer "/data/attributes/missing"', + ); + }); + + it.each([ + [ + "an error pointer the read response does not have", + readWith({ ...poll, error: "/data/attributes/nope" }), + 'wait.error pointer "/data/attributes/nope" does not resolve in the get-thing response', + ], + [ + "an empty succeeded list", + readWith({ ...poll, succeeded: [] }), + "wait.succeeded must list at least one status", + ], + [ + "a status outside the status enum", + readWith({ ...poll, failed: ["bogus"] }), + 'wait status "bogus" is not in the status enum of get-thing', + ], + [ + "a required read parameter the link does not supply", + operation({ + ...readThing, + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "thing_id", in: "query", required: true, schema: { type: "string" } }, + ], + }), + 'wait.params does not supply required parameter "thing_id" of get-thing', + ], + ])("rejects a poll with %s", (_label, read, message) => { + const result = derive({ "create-thing": changeThing(link({})), "get-thing": read }); + + expect(result.problems.map((problem) => problem.replace(/^[^:]+: /u, ""))).toContain(message); + }); + it.each([ [ "an unsupported expression", @@ -556,12 +684,273 @@ describe("deriveApiCommands", () => { ], ["an unknown target", link({}, "get-missing"), 'unknown operation "get-missing"'], [ - "a path parameter the command lacks", + "a request path expression other than ref", link({ ref: "$request.path.other" }), - "needs a path parameter of that name", + 'link "setup" parameter "ref": only "$request.path.ref" is supported in this runtime', + ], + [ + "a link without a target operationId", + { setup: { parameters: {} } }, + 'link "setup" must name its target with operationId', + ], + [ + "a ref expression bound to a parameter of another name", + link({ other: "$request.path.ref" }), + 'link "setup" parameter "other": "$request.path.ref" needs a path parameter of that name on both operations', + ], + [ + "a parameter the polled read does not take", + link({ bogus: "$response.body#/data/id" }), + 'wait.params "bogus" is not a query or path parameter of get-thing', + ], + [ + "a pointer the change response does not have", + link({ thing_id: "$response.body#/data/missing" }), + 'wait.params "thing_id" pointer "/data/missing" does not resolve in the response', + ], + [ + "two links to a polled operation", + { first: link({}).setup, second: link({}).setup }, + "more than one response link targets a polled operation (get-thing, get-thing)", ], ])("rejects %s", (_label, links, message) => { - const result = derive({ "create-thing": changeThing(links), "get-thing": readThing }, {}); + const result = derive({ "create-thing": changeThing(links), "get-thing": readThing }); + + expect(result.problems.join("\n")).toContain(message); + }); + + it.each([ + [ + "a property that is not required in the enclosing object", + { + type: "object", + required: ["data"], + properties: { data: { type: "object", properties: { id: { type: "string" } } } }, + }, + ], + [ + "an enclosing object that is not required", + { + type: "object", + properties: { + data: { type: "object", required: ["id"], properties: { id: { type: "string" } } }, + }, + }, + ], + [ + "a required property that is nullable", + { + type: "object", + required: ["data"], + properties: { + data: { + type: "object", + required: ["id"], + properties: { id: { type: "string", nullable: true } }, + }, + }, + }, + ], + ])("rejects a wait value taken from %s", (_label, schema) => { + const result = derive({ + "create-thing": changeThing(link({ thing_id: "$response.body#/data/id" }), schema), + "get-thing": readThing, + }); + + expect(waitOf(result)).toBeUndefined(); + expect(result.problems.join("\n")).toContain("is not required at every level"); + }); + }); + + describe("nested groups", () => { + it("derives a command path from a dotted group, three levels deep", () => { + const result = derive({ + "create-thing": operation({ "x-operation": { group: "thing.sub", method: "create" } }), + "create-deep": operation({ "x-operation": { group: "thing.sub.deep", method: "create" } }), + }); + + expect(result.problems).toEqual([]); + expect(result.entries.map((entry) => entry.command)).toEqual([ + ["thing", "sub", "create"], + ["thing", "sub", "deep", "create"], + ]); + }); + }); + + describe("path parameters", () => { + const withParameters = (...parameters: ReadonlyArray) => + operation({ + "x-operation": { group: "thing", method: "get" }, + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + ...parameters, + ], + }); + const pathParameter = (name: string, extra: Record = {}) => ({ + name, + in: "path", + required: true, + schema: { type: "string" }, + ...extra, + }); + + it("binds the one other path parameter to a positional argument named after it", () => { + const result = derive({ + "get-thing": withParameters( + pathParameter("function_slug", { description: "Slug of the function." }), + ), + }); + + expect(result.problems).toEqual([]); + const [entry] = result.entries; + expect(entry?.argument).toEqual({ + name: "function-slug", + description: "Slug of the function.", + }); + expect(entry?.bindings).toEqual([ + { location: "path", name: "ref", source: "target" }, + { location: "path", name: "function_slug", source: "argument", argument: "function-slug" }, + ]); + expect(entry?.flags).toEqual([]); + }); + + it.each([ + [ + "a second path parameter", + withParameters(pathParameter("version"), pathParameter("id")), + 'unsupported in this runtime: more than one path parameter besides "ref"', + ], + [ + "a path parameter that is not a scalar", + withParameters( + pathParameter("version", { schema: { type: "array", items: { type: "string" } } }), + ), + 'path parameter "version" is not a scalar', + ], + [ + "a path parameter that is not a string", + withParameters(pathParameter("version", { schema: { type: "integer" } })), + 'unsupported in this runtime: path parameter "version" is not a string', + ], + [ + "a path parameter named like a query parameter", + withParameters(pathParameter("version"), { + name: "version", + in: "query", + schema: { type: "string" }, + }), + '"version" is used by more than one of', + ], + [ + "a path parameter that stands in for no ref", + operation({ + "x-operation": { group: "thing", method: "get" }, + parameters: [pathParameter("version")], + }), + 'operation has no "ref" path parameter', + ], + ])("rejects %s", (_label, node, message) => { + const result = derive({ "get-thing": node }); + + expect(result.problems.join("\n")).toContain(message); + }); + }); + + describe("header parameters", () => { + const withHeaders = (...headers: ReadonlyArray) => + operation({ + ...create, + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + ...headers, + ], + }); + const header = (name: string, extra: Record = {}) => ({ + name, + in: "header", + schema: { type: "string" }, + ...extra, + }); + + it("turns a header parameter into a flag that is required only when the header is", () => { + const result = derive({ + "create-thing": withHeaders( + header("Idempotency-Key", { description: "Deduplicates retries." }), + header("X-Trace-Id", { required: true }), + ), + }); + + expect(result.problems).toEqual([]); + const [entry] = result.entries; + expect(entry?.flags).toEqual([ + { + name: "idempotency-key", + type: "string", + repeatable: false, + required: false, + description: "Deduplicates retries.", + }, + { name: "x-trace-id", type: "string", repeatable: false, required: true }, + ]); + expect(entry?.bindings).toContainEqual({ + location: "header", + name: "Idempotency-Key", + source: "flag", + flag: "idempotency-key", + }); + }); + + it.each([ + ["a credential-named header", header("X-Api-Key")], + [ + "a password-format header", + header("X-Pin", { schema: { type: "string", format: "password" } }), + ], + ])("rejects %s because the dry-run preview masks only body fields", (_label, parameter) => { + const result = derive({ "create-thing": withHeaders(parameter) }); + + expect(result.entries).toEqual([]); + expect(result.problems).toEqual([ + `create-thing: unsupported in this runtime: header parameter "${parameter.name}" carries a credential, and the dry-run preview masks only body fields`, + ]); + }); + + it("gives no flag to Authorization, Content-Type or Accept in any case", () => { + const result = derive({ + "create-thing": withHeaders( + header("Authorization"), + header("content-type"), + header("ACCEPT"), + ), + }); + + expect(result.problems).toEqual([]); + expect(result.entries[0]?.flags).toEqual([]); + }); + + it.each([ + [ + "a cookie parameter", + { name: "session", in: "cookie", schema: { type: "string" } }, + 'unsupported in this runtime: cookie parameter "session"', + ], + [ + "a header that is not a scalar", + header("X-Tags", { schema: { type: "array", items: { type: "string" } } }), + 'header parameter "X-Tags" is not a scalar', + ], + ["a header named like a body field", header("name"), '"name" is used by more than one of'], + ])("rejects %s", (_label, parameter, message) => { + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: envelope({}), + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + parameter, + ], + }), + }); expect(result.problems.join("\n")).toContain(message); }); @@ -569,21 +958,35 @@ describe("deriveApiCommands", () => { it.each([ [ - "a nested group", - { "create-thing": operation({}) }, - { "create-thing": { group: "thing.sub", method: "create" } }, - 'group "thing.sub" must be a single noun', + "a command of more than four words", + { + "create-thing": operation({ + "x-operation": { group: "thing.sub.deep.deeper", method: "create" }, + }), + }, + 'command "thing sub deep deeper create" has more than four words', + ], + [ + "a sub-group without a description", + { "create-thing": operation({ "x-operation": { group: "thing.other", method: "create" } }) }, + 'group "other" has no description in the nouns table', + ], + [ + "a leaf command that is also a group", + { + "get-status": operation({ "x-operation": { group: "thing", method: "status" } }), + "get-detail": operation({ "x-operation": { group: "thing.status", method: "get" } }), + }, + 'command "thing status" is both a command and a group', ], [ "an operation without a ref path parameter", - { "create-thing": operation({ parameters: [] }) }, - { "create-thing": create }, + { "create-thing": operation({ ...create, parameters: [] }) }, 'operation has no "ref" path parameter', ], [ "a verb outside the vocabulary", - { "create-thing": operation({}) }, - { "create-thing": { group: "thing", method: "frobnicate" } }, + { "create-thing": operation({ "x-operation": { group: "thing", method: "frobnicate" } }) }, 'verb "frobnicate" is outside the vocabulary', ], [ @@ -593,31 +996,222 @@ describe("deriveApiCommands", () => { "x-operation": { group: "thing", method: "create", bogus: 1 }, }), }, - {}, - "create-thing: invalid x-operation", - ], - [ - "a CLI-only key in x-operation", - { - "create-thing": operation({ - "x-operation": { group: "thing", method: "create", flags: { name: "label" } }, - }), - }, - {}, "create-thing: invalid x-operation", ], [ - "a generated operation that has no name", + "a generated operation that has no x-operation", { "create-thing": operation({}) }, - { "create-thing": { flags: { name: "label" } } }, "create-thing: no command name", ], - ])("rejects %s", (_label, operations, overrides, message) => { - const result = derive(operations, overrides); + ])("rejects %s", (_label, operations, message) => { + const result = derive(operations); expect(result.problems.join("\n")).toContain(message); }); + describe("operation rejections", () => { + const ref = { name: "ref", in: "path", required: true, schema: { type: "string" } }; + const withParameters = (...parameters: ReadonlyArray) => + operation({ ...create, parameters: [ref, ...parameters] }); + const respondWith = (schema: unknown) => + operation({ ...named("get"), responses: jsonResponse(schema) }); + + it.each([ + [ + "a response schema that is not an object", + { "get-thing": respondWith({ type: "object", properties: { a: 5 } }) }, + "get-thing: schema is not an object", + ], + [ + "a response schema reference that does not resolve", + { "get-thing": respondWith({ $ref: "#/components/schemas/Missing" }) }, + "get-thing: schema reference #/components/schemas/Missing does not resolve", + ], + [ + "an exclusive bound without its bound", + { "get-thing": respondWith({ type: "integer", exclusiveMinimum: true }) }, + "get-thing: schema sets exclusiveMinimum: true without minimum", + ], + [ + "an exclusive bound with an unsupported value", + { "get-thing": respondWith({ type: "integer", exclusiveMaximum: "yes" }) }, + 'get-thing: schema keyword "exclusiveMaximum" has an unsupported value', + ], + [ + "a nullable keyword with an unsupported value", + { "get-thing": respondWith({ type: "string", nullable: "yes" }) }, + 'get-thing: schema keyword "nullable" has an unsupported value', + ], + [ + "a response status that is not a number", + { "create-thing": operation({ ...create, responses: { "2XX": { description: "ok" } } }) }, + 'create-thing: unsupported in this runtime: response status "2XX"', + ], + [ + "an operation with no 2xx response", + { + "create-thing": operation({ ...create, responses: { "400": { description: "bad" } } }), + }, + "create-thing: operation has no 2xx response", + ], + [ + "a noun missing from the nouns table", + { "create-thing": operation({ "x-operation": { group: "other", method: "create" } }) }, + 'create-thing: noun "other" is missing from the nouns table', + ], + [ + "a command that is not lowercase kebab-case", + { "create-thing": operation({ "x-operation": { group: "thing", method: "Create" } }) }, + 'create-thing: command "thing Create" must be lowercase kebab-case words', + ], + [ + "a command generated twice", + { "create-thing": operation(create), "create-other": operation(create) }, + 'create-other: command "thing create" is already generated by create-thing', + ], + [ + "a command declared after the group that contains it", + { + "get-detail": operation({ "x-operation": { group: "thing.status", method: "get" } }), + "get-status": operation({ "x-operation": { group: "thing", method: "status" } }), + }, + 'get-status: command "thing status" is both a command and a group', + ], + [ + "a poll on an operation that is not a read", + { + "create-thing": operation({ + "x-operation": { + group: "thing", + method: "create", + poll: { status: "/ok", succeeded: ["done"], failed: [] }, + }, + }), + }, + "create-thing: poll belongs on a read operation, not POST", + ], + [ + "an operation with no summary", + { "create-thing": operation({ ...create, summary: undefined }) }, + "create-thing: operation has no summary", + ], + [ + "a server-side dry_run query parameter", + { + "create-thing": withParameters({ + name: "dry_run", + in: "query", + schema: { type: "boolean" }, + }), + }, + 'create-thing: unsupported in this runtime: server-side "dry_run" parameter', + ], + [ + "a query parameter that is not a scalar", + { + "create-thing": withParameters({ + name: "filter", + in: "query", + schema: { type: "object" }, + }), + }, + 'create-thing: unsupported in this runtime: query parameter "filter" is not a scalar', + ], + [ + "a secret query parameter", + { + "create-thing": withParameters({ + name: "pin", + in: "query", + schema: { type: "string", writeOnly: true }, + }), + }, + 'create-thing: unsupported in this runtime: query parameter "pin" is a secret, and the dry-run preview masks only body fields', + ], + [ + "a query parameter whose flag is not kebab-case", + { + "create-thing": withParameters({ + name: "page.size", + in: "query", + schema: { type: "string" }, + }), + }, + 'create-thing: flag "page.size" must be lowercase kebab-case', + ], + [ + "a path parameter whose argument is not kebab-case", + { + "create-thing": withParameters({ + name: "slug.name", + in: "path", + required: true, + schema: { type: "string" }, + }), + }, + 'create-thing: argument "slug.name" must be lowercase kebab-case', + ], + [ + "a request body that is not JSON", + { + "create-thing": operation({ + ...create, + requestBody: { content: { "text/plain": { schema: { type: "string" } } } }, + }), + }, + "create-thing: unsupported in this runtime: request body (text/plain) is not a JSON object", + ], + [ + "a server-side dry_run body field", + { + "create-thing": operation({ + ...create, + requestBody: envelope({ dry_run: { type: "boolean" } }), + }), + }, + 'create-thing: unsupported in this runtime: server-side "dry_run" body field', + ], + [ + "a file-only body field named like a path parameter", + { + "create-thing": operation({ + ...create, + parameters: [ + ref, + { name: "version", in: "path", required: true, schema: { type: "string" } }, + ], + requestBody: envelope({ version: { type: "object", properties: {} } }), + }), + }, + 'create-thing: "version" is used by more than one of: path parameter, header parameter, query parameter, body field', + ], + ])("rejects %s", (_label, operations, problem) => { + const result = derive(operations); + + expect(result.problems).toContain(problem); + }); + + it("rejects an operation that the typed client does not have", () => { + const result = derive({ "create-thing": operation(create) }, undefined, { + overrides: { operationIdMap: {} }, + }); + + expect(result.problems).toEqual([ + "create-thing: operation is missing from the typed client; regenerate @supabase/api", + ]); + }); + + it("rejects a command whose first word belongs to a hand-written command", () => { + const result = derive({ "create-thing": operation(create) }, undefined, { + overrides: { handWrittenTopLevel: new Set(["thing"]) }, + }); + + expect(result.problems).toEqual([ + 'create-thing: command "thing create" collides with the hand-written "thing" command', + ]); + }); + }); + describe("generated operations", () => { const named = operation({ "x-operation": { group: "thing", method: "create" } }); @@ -629,7 +1223,6 @@ describe("deriveApiCommands", () => { "x-operation": { group: "other", method: "frobnicate", bogus: 1 }, }), }, - {}, ["create-thing"], ); @@ -638,23 +1231,11 @@ describe("deriveApiCommands", () => { }); it("rejects a generated operation that is missing from the spec", () => { - const result = derive({ "create-thing": named }, {}, ["create-thing", "missing-thing"]); + const result = derive({ "create-thing": named }, ["create-thing", "missing-thing"]); expect(result.problems).toEqual([ "missing-thing: generated operation has no operation in the spec", ]); }); - - it("rejects an override entry for an operation that is not generated", () => { - const result = derive( - { "create-thing": named, "create-other": named }, - { "create-other": create }, - ["create-thing"], - ); - - expect(result.problems).toEqual([ - "create-other: override entry is for an operation that is not generated", - ]); - }); }); }); diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index 5d6a7d6801..d771dabc19 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -1,11 +1,7 @@ import { BunRuntime, BunServices } from "@effect/platform-bun"; import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; -import { - commandOverrides, - generatedOperations, - nouns, -} from "../src/commands/api/api-command-overrides.ts"; +import { generatedOperations, nouns } from "../src/commands/api/api-command-policy.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { ApiCommandGenerationError, deriveApiCommands } from "./api-command-derive.ts"; @@ -92,7 +88,6 @@ const main = Effect.gen(function* () { const { entries, schemas, problems } = deriveApiCommands({ spec, generated: generatedOperations, - overrides: commandOverrides, nouns, operationIdMap: openApiOperationIdMap, handWrittenTopLevel: yield* handWrittenTopLevel(cliRoot), diff --git a/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts similarity index 89% rename from apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts rename to apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 195fb65b36..7230e9bc1b 100644 --- a/apps/cli/src/command-internal/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -2,7 +2,7 @@ import { describe, expect, it } from "@effect/vitest"; import { Effect, Schema } from "effect"; import { commandSurface, commandSurfaceEntry, walkCommandSurface } from "./command-surface.ts"; -import { rootCommandForFeatures } from "../../cli/root.ts"; +import { rootCommandForFeatures } from "../root.ts"; const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); @@ -70,11 +70,16 @@ describe("command surface", () => { path: ["warehouse", "enable"], target: { group: "hosted", consent: "no" }, errors: "standard", - stage: { status: "experimental", gate: { kind: "feature", feature: "warehouse" } }, + stage: { status: "experimental", feature: "warehouse" }, api: { operationId: "v2-enable-warehouse", request: { contentType: "application/json" } }, }); expect(titlesOf(enable?.result)).toEqual(["response", "waited", "dryRun"]); - expect(enable?.flags["table"]).toMatchObject({ type: "string", variadic: true }); + expect(enable?.flags["schema"]).toMatchObject({ required: true }); + expect(enable?.flags["table"]).toMatchObject({ + type: "string", + variadic: true, + required: false, + }); expect(enable?.flags["dry-run"]).toMatchObject({ type: "boolean", default: false }); expect(Object.keys(enable?.flags ?? {})).not.toContain("output"); }), @@ -90,7 +95,7 @@ describe("command surface", () => { }), ); - it.effect("declares a waited result only for a command with a wait read", () => + it.effect("declares a waited result only for a command that waits on another read", () => Effect.gen(function* () { const { variants } = yield* Effect.promise(() => surface); expect(titlesOf(variants.warehouse["warehouse status"]?.result)).toEqual([ @@ -121,13 +126,11 @@ describe("command surface", () => { it.effect("loads the generated schemas only through the surface extraction", () => Effect.gen(function* () { - const extraction = yield* bundledInputs( - "src/command-internal/command-surface/command-surface.ts", - ); + const extraction = yield* bundledInputs("src/cli/command-surface/command-surface.ts"); const runtime = yield* bundledInputs("src/main.ts"); expect(extraction).toContain("src/commands/api/generated.schemas.ts"); expect(runtime).not.toContain("src/commands/api/generated.schemas.ts"); - expect(runtime).not.toContain("src/command-internal/command-surface/command-surface.ts"); + expect(runtime).not.toContain("src/cli/command-surface/command-surface.ts"); }), ); }); diff --git a/apps/cli/src/command-internal/command-surface/command-surface.ts b/apps/cli/src/cli/command-surface/command-surface.ts similarity index 85% rename from apps/cli/src/command-internal/command-surface/command-surface.ts rename to apps/cli/src/cli/command-surface/command-surface.ts index 9f0401da7a..f34930eaf8 100644 --- a/apps/cli/src/command-internal/command-surface/command-surface.ts +++ b/apps/cli/src/cli/command-surface/command-surface.ts @@ -5,18 +5,19 @@ import { readApiCommand } from "../../commands/api/api-command.annotation.ts"; import type { ApiCommandBinding, ApiCommandEntry, + ApiCommandFlag, ApiCommandSchemas, } from "../../commands/api/api-command.model.ts"; -import { readCommandStage } from "../../commands/api/api-command-stage.ts"; -import type { CommandStage } from "../../commands/api/api-command-stage.ts"; +import { readCommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; +import type { CommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; import { apiCommands } from "../../commands/api/generated.ts"; -import { rootCommandForFeatures } from "../../cli/root.ts"; +import { rootCommandForFeatures } from "../root.ts"; import { flattenSubcommands } from "../../docs/docs-introspection.ts"; -import { readCommandErrorsContract } from "../command-errors/command-errors.annotation.ts"; -import { readPermissions } from "../command-permissions/command-permissions.annotation.ts"; -import type { CommandPermissions } from "../command-permissions/model.ts"; -import { readTargetPolicy } from "../target/target-policy.ts"; -import type { TargetGroup } from "../target/target-policy.ts"; +import { readCommandErrorsContract } from "../../command-internal/command-errors/command-errors.annotation.ts"; +import { readPermissions } from "../../command-internal/command-permissions/command-permissions.annotation.ts"; +import type { CommandPermissions } from "../../command-internal/command-permissions/model.ts"; +import { readTargetPolicy } from "../../command-internal/target/target-policy.ts"; +import type { TargetGroup } from "../../command-internal/target/target-policy.ts"; type JsonSchema = Readonly>; @@ -29,7 +30,10 @@ interface SurfaceArgument { readonly variadic: boolean; } -/** A flag as the parser accepts it; `env` is `null` because the parser carries no env name. */ +/** + * A flag as the parser accepts it, except that a generated API flag is `required` and `sensitive` + * as its operation declares; `env` is `null` because the parser carries no env name. + */ interface SurfaceFlag { readonly name: string; readonly aliases: readonly string[]; @@ -91,9 +95,10 @@ const dryRunSchema: JsonSchema = { method: { type: "string" }, path: { type: "string" }, query: { type: "object" }, + headers: { type: "object" }, body: {}, }, - required: ["method", "path", "query", "body"], + required: ["method", "path", "query", "headers", "body"], additionalProperties: false, }; @@ -146,9 +151,11 @@ const sortedRecord = ( ): Readonly> => Object.fromEntries([...entries].toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))); +const noApiFlags: ReadonlyMap = new Map(); + const surfaceFlag = ( flag: CommandSpec.Flag, - sensitiveFlags: ReadonlySet, + apiFlags: ReadonlyMap, ): readonly [string, SurfaceFlag] => [ flag.name, { @@ -156,13 +163,13 @@ const surfaceFlag = ( aliases: flag.aliases, type: flag.typeName, choices: choicesOf(flag.type), - required: flag.required, + required: flag.required || apiFlags.get(flag.name)?.required === true, default: defaultOf(flag.fallbacks), env: null, negatable: flag.negation !== undefined, variadic: flag.variadic !== undefined, hidden: flag.hidden, - sensitive: flag.type._tag === "Redacted" || sensitiveFlags.has(flag.name), + sensitive: flag.type._tag === "Redacted" || apiFlags.get(flag.name)?.sensitive === true, }, ]; @@ -174,7 +181,7 @@ const walkGlobalFlags = (root: CommandRoot) => { ? [] : spec.value.flags .filter((flag) => flag.scope._tag === "Global") - .map((flag) => surfaceFlag(flag, new Set())), + .map((flag) => surfaceFlag(flag, noApiFlags)), ); }; @@ -191,7 +198,7 @@ const apiSurface = Effect.fn("CommandSurface.api")(function* (command: CommandRo if (schemas === undefined) { return yield* Effect.die(`no generated schemas for operation "${operationId}"`); } - const waitRead = generated.wait?.read; + const waitRead = generated.wait?.read === operationId ? undefined : generated.wait?.read; const waitSchemas = waitRead === undefined ? undefined : table[waitRead]; if (waitRead !== undefined && waitSchemas === undefined) { return yield* Effect.die(`no generated schemas for operation "${waitRead}"`); @@ -211,9 +218,7 @@ const apiSurface = Effect.fn("CommandSurface.api")(function* (command: CommandRo bindings, } satisfies SurfaceApi, result: { anyOf: branches } satisfies JsonSchema, - sensitiveFlags: new Set( - generated.flags.filter((flag) => flag.sensitive).map((flag) => flag.name), - ), + apiFlags: new Map(generated.flags.map((flag) => [flag.name, flag])), }); }); @@ -228,16 +233,16 @@ export const commandSurfaceEntry = Effect.fn("CommandSurface.entry")(function* ( return yield* Effect.die(`unknown command path "${path.join(" ")}"`); } const api = yield* apiSurface(command.value); - const sensitiveFlags = Option.match(api, { - onNone: () => new Set(), - onSome: (found) => found.sensitiveFlags, + const apiFlags = Option.match(api, { + onNone: () => noApiFlags, + onSome: (found) => found.apiFlags, }); const stage = readCommandStage(command.value); const target = readTargetPolicy(command.value); const permissions = readPermissions(command.value); const flags = spec.value.flags .filter((flag) => flag.scope._tag !== "Global") - .map((flag) => surfaceFlag(flag, sensitiveFlags)); + .map((flag) => surfaceFlag(flag, apiFlags)); const entry: CommandSurfaceEntry = { path, aliases: spec.value.alias === undefined ? [] : [spec.value.alias], diff --git a/apps/cli/src/commands/api/api-command.errors.ts b/apps/cli/src/command-internal/command-errors/api-command.errors.ts similarity index 100% rename from apps/cli/src/commands/api/api-command.errors.ts rename to apps/cli/src/command-internal/command-errors/api-command.errors.ts diff --git a/apps/cli/src/commands/api/api-command-stage.ts b/apps/cli/src/command-internal/command-stage/command-stage.annotation.ts similarity index 53% rename from apps/cli/src/commands/api/api-command-stage.ts rename to apps/cli/src/command-internal/command-stage/command-stage.annotation.ts index 9dc8030293..aacc431bb8 100644 --- a/apps/cli/src/commands/api/api-command-stage.ts +++ b/apps/cli/src/command-internal/command-stage/command-stage.annotation.ts @@ -1,15 +1,13 @@ -import { Context, Effect, Option } from "effect"; +import { Context, Option } from "effect"; import { Command } from "effect/cli"; -import { requireExperimental } from "../../command-internal/experimental-gate.ts"; - /** - * How far a command's contract has settled. An experimental command is reachable only through its - * `gate`: the `--experimental` flag, or an experimental feature whose family mounts the command. + * How far a command's contract has settled. An experimental command is reachable only while its + * `feature` is enabled: the root mounts the command's family only then. */ export interface CommandStage { readonly status: "experimental"; - readonly gate: { readonly kind: "flag" } | { readonly kind: "feature"; readonly feature: string }; + readonly feature: string; } /** Context key under which a command's stage is stored in `Command.annotations`. */ @@ -17,7 +15,7 @@ export class CommandStageAnnotation extends Context.Service ( @@ -28,10 +26,3 @@ export const withCommandStage = /** The stage a command declares, or `None` for a stable command. */ export const readCommandStage = (command: Command.Command.Any): Option.Option => Context.getOption(command.annotations, CommandStageAnnotation); - -/** - * Enforces a stage before any other effect. A feature gate is satisfied by the family being - * mounted: the root only mounts a feature's commands while the feature is enabled. - */ -export const enforceStage = (stage: CommandStage) => - stage.gate.kind === "flag" ? requireExperimental : Effect.void; diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 4dca644e77..43d3bf3d36 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -4,7 +4,7 @@ import openApiSpec from "@supabase/api/openapi.json"; import { Effect, Layer, Predicate, Schema, Stdio } from "effect"; import { CliOutput, Command } from "effect/cli"; -import { commandSurface } from "../../command-internal/command-surface/command-surface.ts"; +import { commandSurface } from "../../cli/command-surface/command-surface.ts"; import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; import { @@ -384,7 +384,7 @@ describe("generated command bindings", () => { ); const waitRead = generated.find((entry) => entry.operationId === operationId)?.wait?.read; const waited = branches.find((branch) => branch["title"] === "waited"); - if (waitRead === undefined) { + if (waitRead === undefined || waitRead === operationId) { expect(waited).toBeUndefined(); return; } diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index f0a105a848..47e9e32b69 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -15,9 +15,8 @@ import { ApiCommandOperationFailedError, ApiCommandStatusError, ApiCommandWaitTimeoutError, -} from "./api-command.errors.ts"; +} from "../../command-internal/command-errors/api-command.errors.ts"; import type { ApiCommandEntry, ApiCommandWait } from "./api-command.model.ts"; -import { apiCommands } from "./generated.ts"; const POLL_BASE_DELAY = "1 second"; const POLL_MAX_DELAY_MILLIS = 10_000; @@ -167,11 +166,11 @@ export const writeApiResponse = Effect.fnUntraced(function* ( interface WaitInput { readonly wait: ApiCommandWait; - /** The operation that produced `changed`. */ - readonly changedEntry: ApiCommandEntry; + /** The operation the wait polls; its decoded input is `readInput`. */ + readonly readEntry: ApiCommandEntry; + /** The flat input of the read operation, as assembled from flags or the change response. */ + readonly readInput: Readonly>; readonly ref: string; - /** The change response the read parameters are taken from. */ - readonly changed: ApiCommandResponse; readonly timeoutMillis: number; } @@ -210,14 +209,13 @@ const failureReason = (reason: unknown): string | undefined => { const classify = (wait: ApiCommandWait, response: ApiCommandResponse, statusHint: string) => { const body = parseResponse(response); const status = readPointer(body, wait.status); - const reason = - wait.error === undefined ? undefined : failureReason(readPointer(body, wait.error)); - const failedStatus = typeof status === "string" && wait.failed.includes(status); - if (reason !== undefined || failedStatus) { + if (typeof status === "string" && wait.failed.includes(status)) { + const reason = + wait.error === undefined ? undefined : failureReason(readPointer(body, wait.error)); return Effect.fail( new ApiCommandOperationFailedError({ - status: typeof status === "string" ? status : "unknown", - message: reason ?? `The operation failed with status "${String(status)}".`, + status, + message: reason ?? `The operation failed with status "${status}".`, hint: statusHint, }), ); @@ -232,36 +230,55 @@ const statusCommand = ( ref: string, readInput: Readonly>, ): string => { + const valueOf = (binding: { readonly name: string }) => readInput[binding.name]; + const positional = readEntry.bindings.flatMap((binding) => { + const value = valueOf(binding); + return binding.source === "argument" && value !== undefined ? [String(value)] : []; + }); const flags = readEntry.bindings.flatMap((binding) => { - if (binding.source !== "flag") return []; - const value = readInput[binding.name]; - return value === undefined ? [] : [`--${binding.flag} ${String(value)}`]; + const value = valueOf(binding); + return binding.source === "flag" && value !== undefined + ? [`--${binding.flag} ${String(value)}`] + : []; }); - return ["supabase", ...readEntry.command, ...flags, `--remote=${ref}`].join(" "); + return ["supabase", ...readEntry.command, ...positional, ...flags, `--remote=${ref}`].join(" "); }; /** - * Polls the read operation until it reports a terminal status and returns the final response with - * the operation that produced it. A failed status or failure reason, a timeout, or any non-2xx - * read (a 409 included) ends the wait with an error. A change response that lacks a value the - * read needs is returned as it is, without waiting. + * The input of a linked wait's read: the project ref plus each read parameter taken from the + * change response by pointer. Generation guarantees the response carries them, so a missing one + * is a defect. */ -export const waitForOperation = Effect.fn("api-command.wait")(function* (input: WaitInput) { - const { wait } = input; - const readEntry = apiCommands.find((candidate) => candidate.operationId === wait.read); - if (readEntry === undefined) { - return yield* Effect.die(new Error(`Unknown wait read operation ${wait.read}`)); - } +export const linkedReadInput = Effect.fnUntraced(function* (input: { + readonly wait: ApiCommandWait; + /** The operation that produced `changed`. */ + readonly changedOperationId: string; + readonly ref: string; + readonly changed: ApiCommandResponse; +}) { const changedBody = parseResponse(input.changed); const readInput: Record = { ref: input.ref }; - for (const [param, pointer] of Object.entries(wait.params)) { + for (const [param, pointer] of Object.entries(input.wait.params)) { const value = readPointer(changedBody, pointer); - if (value === undefined) { - yield* Effect.annotateCurrentSpan({ "wait.outcome": "skipped" }); - return { entry: input.changedEntry, response: input.changed }; + if (value === undefined || value === null) { + return yield* Effect.die( + new Error( + `${input.changedOperationId} did not return ${pointer}, which ${input.wait.read} needs to wait.`, + ), + ); } readInput[param] = value; } + return readInput; +}); + +/** + * Polls the read operation until it reports a terminal status and returns the final response. A + * failed status, a timeout, or any non-2xx read (a 409 included) ends the wait with an error; the + * failure reason only supplies its message. + */ +export const waitForOperation = Effect.fn("api-command.wait")(function* (input: WaitInput) { + const { wait, readEntry, readInput } = input; const decoded = yield* decodeInput(readEntry, readInput); const hint = `Check it with \`${statusCommand(readEntry, input.ref, readInput)}\`.`; const attempts = yield* Ref.make(0); @@ -297,5 +314,5 @@ export const waitForOperation = Effect.fn("api-command.wait")(function* (input: "wait.attempts": yield* Ref.get(attempts), "wait.outcome": "succeeded", }); - return { entry: readEntry, response: outcome.response }; + return outcome.response; }); diff --git a/apps/cli/src/commands/api/api-command-flags.ts b/apps/cli/src/commands/api/api-command-flags.ts index 08768de8a6..59ae878337 100644 --- a/apps/cli/src/commands/api/api-command-flags.ts +++ b/apps/cli/src/commands/api/api-command-flags.ts @@ -22,15 +22,27 @@ const scalarFlag = (flag: ApiCommandFlag): Flag.Flag } }; +/** Where a generated flag's value lands in the request. */ +export type ApiFlagLocation = "query" | "header" | "body"; + +const describedFlag = (flag: ApiCommandFlag, location: ApiFlagLocation): string => { + const description = flag.description ?? `Set ${flag.name}.`; + if (!flag.required) return description; + return location === "body" + ? `${description} Required unless the field is in --body or --file.` + : `${description} Required.`; +}; + /** * Builds a flag that keeps absence distinct from every value: `Flag.optional` is the outermost * wrapper, a repeatable flag needs at least one occurrence once present, and a boolean can be * given as `false`. */ -export const apiFlag = (flag: ApiCommandFlag): Flag.Flag> => { - const described = scalarFlag(flag).pipe( - Flag.withDescription(flag.description ?? `Set ${flag.name}.`), - ); +export const apiFlag = ( + flag: ApiCommandFlag, + location: ApiFlagLocation, +): Flag.Flag> => { + const described = scalarFlag(flag).pipe(Flag.withDescription(describedFlag(flag, location))); const shaped: Flag.Flag = flag.repeatable ? Flag.map(Flag.atLeast(described, 1), (values): ApiFlagValue => values) : Flag.map(described, (value): ApiFlagValue => value); diff --git a/apps/cli/src/commands/api/api-command-overrides.ts b/apps/cli/src/commands/api/api-command-policy.ts similarity index 52% rename from apps/cli/src/commands/api/api-command-overrides.ts rename to apps/cli/src/commands/api/api-command-policy.ts index 6b5b7772cf..08bb5477c1 100644 --- a/apps/cli/src/commands/api/api-command-overrides.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -11,36 +11,22 @@ export const verbVocabulary = [ "enable", "disable", "status", + "add", + "remove", + "resync", ] as const; export interface ApiNoun { readonly description: string; /** Feature that gates every command under the noun. */ - readonly feature?: string; + readonly feature: string; + /** Help text of each sub-group, keyed by its dotted path below the noun, e.g. `"tables.layout"`. */ + readonly groups?: Readonly>; } /** How to tell that the resource a read operation returns has settled. */ export type ApiCommandPoll = Pick; -/** - * CLI-only metadata of one operation; its `group`, `method` and `poll` win over the spec's - * `x-operation`. - */ -export interface ApiCommandOverride { - /** A single noun, e.g. `warehouse`; it must be a key of `nouns`. */ - readonly group?: string; - /** A member of `verbVocabulary`. */ - readonly method?: string; - /** API field name to flag name; wins over the naming convention. */ - readonly flags?: Readonly>; - /** Credential-like body fields that were reviewed and are secrets. */ - readonly sensitive?: readonly string[]; - /** Set on a read operation; response `links` that target it derive a `--wait`. */ - readonly poll?: ApiCommandPoll; - /** Replaces any wait derived from response `links`. */ - readonly wait?: ApiCommandWait; -} - /** Only these operations generate commands; `x-operation` on any other operation is ignored. */ export const generatedOperations: ReadonlyArray = [ "v2-enable-warehouse", @@ -50,7 +36,3 @@ export const generatedOperations: ReadonlyArray = [ export const nouns = { warehouse: { description: "Manage the data warehouse for a project", feature: "warehouse" }, } as const satisfies Readonly>; - -export const commandOverrides = {} as const satisfies Partial< - Record ->; diff --git a/apps/cli/src/commands/api/api-command-request.ts b/apps/cli/src/commands/api/api-command-request.ts index d5e2e19676..c88681f384 100644 --- a/apps/cli/src/commands/api/api-command-request.ts +++ b/apps/cli/src/commands/api/api-command-request.ts @@ -4,7 +4,7 @@ import { Effect, FileSystem, Option, Predicate, Schema, type SchemaIssue } from import { Stdin } from "../../shared/runtime/stdin.service.ts"; import type { ApiFlagValue } from "./api-command-flags.ts"; import { readPointer, writePointer } from "./api-command-pointer.ts"; -import { ApiCommandUsageError } from "./api-command.errors.ts"; +import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; import type { ApiCommandEntry } from "./api-command.model.ts"; /** Parsed flag values keyed by flag name; `None` means the flag was absent. */ @@ -88,16 +88,18 @@ const initialBody = (entry: ApiCommandEntry): Readonly> }; /** - * The flat operation input `{...bodyFields, ...query, ref}`. A body override is the starting point - * when given, else the synthesized envelope; only flags that were passed are written, each at its - * own pointer. An override may only carry top-level fields the request body declares, and the - * path and query values are applied last so body data cannot retarget the request. + * The flat operation input `{...bodyFields, ...query, ...headers, ref, }`. A body + * override is the starting point when given, else the synthesized envelope; only flags that were + * passed are written, each at its own pointer. An override may only carry top-level fields the + * request body declares, and the path values are applied last so body data cannot retarget the + * request. */ export const assembleInput = Effect.fnUntraced(function* ( entry: ApiCommandEntry, ref: string, flagValues: ApiFlagValues, bodyOverride: Option.Option>>, + argument?: string, ) { if (Option.isSome(bodyOverride)) { const { requestBody } = definitionOf(entry); @@ -115,14 +117,29 @@ export const assembleInput = Effect.fnUntraced(function* ( } let body: unknown = Option.getOrElse(bodyOverride, () => initialBody(entry)); const query: Record = {}; + const headers: Record = {}; + const positional: Record = {}; for (const binding of entry.bindings) { + if (binding.source === "argument") { + if (argument !== undefined) { + if (argument === "" || argument === "." || argument === "..") { + return yield* new ApiCommandUsageError({ + message: `<${binding.argument}> must not be empty, "." or "..".`, + hint: "Pass the identifier of the resource.", + }); + } + positional[binding.name] = argument; + } + continue; + } if (binding.source !== "flag") continue; const value = flagValues[binding.flag]; if (value === undefined || Option.isNone(value)) continue; if (binding.location === "query") query[binding.name] = value.value; + if (binding.location === "header") headers[binding.name] = value.value; if (binding.location === "body") body = writePointer(body, binding.pointer, value.value); } - return { ...(isRecord(body) ? body : {}), ...query, ref }; + return { ...(isRecord(body) ? body : {}), ...query, ...headers, ref, ...positional }; }); type Path = ReadonlyArray; @@ -152,14 +169,18 @@ const missingKeyPaths = (issue: SchemaIssue.Issue, path: Path): ReadonlyArray { +/** The flag binding that supplies the input field at `path`, if one covers it. */ +const flagAt = (entry: ApiCommandEntry, path: Path) => { const pointer = `/${path.map(String).join("/")}`; for (const binding of entry.bindings) { if (binding.source !== "flag") continue; - if (binding.location === "body" && binding.pointer === pointer) return binding.flag; - if (binding.location === "query" && path.length === 1 && path[0] === binding.name) { - return binding.flag; + if (binding.location === "body" && binding.pointer === pointer) return binding; + if ( + (binding.location === "query" || binding.location === "header") && + path.length === 1 && + path[0] === binding.name + ) { + return binding; } } return undefined; @@ -167,12 +188,16 @@ const flagAt = (entry: ApiCommandEntry, path: Path): string | undefined => { const invalidRequest = (entry: ApiCommandEntry, error: Schema.SchemaError) => { const paths = missingKeyPaths(error.issue, []); - const flags = paths?.map((path) => flagAt(entry, path)); - if (flags !== undefined && flags.every((flag) => flag !== undefined)) { - const names = flags.map((flag) => `--${flag}`).join(", "); + const missing = paths?.map((path) => flagAt(entry, path)); + if (missing !== undefined && missing.every((binding) => binding !== undefined)) { + const names = missing.map((binding) => `--${binding.flag}`).join(", "); + const plural = missing.length === 1 ? "" : "s"; + const allBody = missing.every((binding) => binding.location === "body"); return new ApiCommandUsageError({ - message: `Missing required ${flags.length === 1 ? "flag" : "flags"} ${names}`, - hint: "Pass the flag, or include the field in --body/--file.", + message: `Missing required flag${plural} ${names}`, + hint: allBody + ? `Pass the flag${plural}, or include the field${plural} in --body/--file.` + : `Pass the flag${plural}.`, }); } return new ApiCommandUsageError({ @@ -190,11 +215,12 @@ export const decodeInput = (entry: ApiCommandEntry, input: unknown) => input, ).pipe(Effect.mapError((error) => invalidRequest(entry, error))); -/** What a request would send: method, path, query and body, with sensitive flag values masked. */ +/** What a request would send: method, path, query, headers and body, with sensitive flag values masked. */ export interface ApiRequestPreview { readonly method: string; readonly path: string; readonly query: Readonly>; + readonly headers: Readonly>; readonly body: unknown; } @@ -230,6 +256,7 @@ export const previewRequest = (entry: ApiCommandEntry, decoded: object): ApiRequ method: definition.method, path, query: pick(decoded, definition.queryParams), + headers: pick(decoded, definition.headerParams), body, }; }; diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts new file mode 100644 index 0000000000..f4ab030df0 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts @@ -0,0 +1,366 @@ +import { BunServices } from "@effect/platform-bun"; +import { describe, expect, it } from "@effect/vitest"; +import { openApiOperationIdMap } from "@supabase/api/effect"; +import openApiSpec from "@supabase/api/openapi.json"; +import { Console, Effect, Exit, FileSystem, Layer, Path, Predicate, Schema, Stdio } from "effect"; +import { CliOutput, Command } from "effect/cli"; + +import { deriveApiCommands } from "../../../scripts/api-command-derive.ts"; +import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; +import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; +import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; +import { + VALID_REF, + VALID_TOKEN, + buildTestRuntime, + mockCommandPlatformApi, + mockCommandSettings, + useTempWorkdir, + withConfigEnv, +} from "../../../tests/helpers/command-mocks.ts"; +import { + fakeConsole, + mockOutput, + mockRuntimeInfo, + mockStdin, + mockTelemetryRuntime, + mockTty, +} from "../../../tests/helpers/mocks.ts"; +import type { ApiNoun } from "./api-command-policy.ts"; +import { apiCommandGroup } from "./runtime.ts"; + +const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); +const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); + +const isRecord = (value: unknown): value is Record => + Predicate.isObject(value) && !Array.isArray(value); + +const fixtureNoun: ApiNoun = { + description: "Fixture commands", + feature: "fixture", + groups: { + migrations: "Migration fixtures", + auth: "Auth fixtures", + "auth.signing-keys": "Signing key fixtures", + jit: "JIT access fixtures", + keys: "Legacy key fixtures", + }, +}; + +const FIXTURE_OPERATIONS = { + "v1-apply-a-migration": { group: "fixture.migrations", method: "create" }, + "v1-get-a-migration": { group: "fixture.migrations", method: "get" }, + "v1-get-project-signing-key": { group: "fixture.auth.signing-keys", method: "get" }, + "v1-update-jit-access": { group: "fixture.jit", method: "update" }, + "v1-update-project-legacy-api-keys": { group: "fixture.keys", method: "update" }, +}; + +/** The committed spec with an experimental `x-operation` on a few real operations. */ +const fixtureSpec = () => { + const spec: Record = structuredClone(openApiSpec); + for (const item of Object.values(isRecord(spec["paths"]) ? spec["paths"] : {})) { + for (const operation of Object.values(isRecord(item) ? item : {})) { + if (!isRecord(operation)) continue; + const operationId = String(operation["operationId"]); + if (!Object.hasOwn(FIXTURE_OPERATIONS, operationId)) continue; + operation["x-operation"] = Reflect.get(FIXTURE_OPERATIONS, operationId); + operation["x-scalar-stability"] = "experimental"; + } + } + return spec; +}; + +const derived = deriveApiCommands({ + spec: fixtureSpec(), + generated: Object.keys(FIXTURE_OPERATIONS), + nouns: { fixture: fixtureNoun }, + operationIdMap: openApiOperationIdMap, + handWrittenTopLevel: new Set(), +}); + +const fixtureRoot = Command.make("supabase").pipe( + Command.withSubcommands([apiCommandGroup("fixture", fixtureNoun, derived.entries)]), + Command.withGlobalFlags(GLOBAL_FLAGS), +); + +const MIGRATION_VERSION = "20250312000000"; +const SIGNING_KEY_ID = "33333333-3333-4333-8333-333333333333"; +const MIGRATIONS_PATH = `/v1/projects/${VALID_REF}/database/migrations`; +const TARGET_LOOKUP_PATH = `/v1/projects/${VALID_REF}`; + +interface Sent { + readonly method: string; + readonly path: string; + readonly headers: Headers; + readonly body: unknown; +} + +/** Replaces `globalThis.fetch` while the command runs; every API request is recorded and answered with `{}`. */ +const withApi = (sent: Array) => { + const answer = () => + new Response("{}", { status: 200, headers: { "content-type": "application/json" } }); + const stub = (input: string | URL | Request, init?: RequestInit): Promise => { + const request = input instanceof Request ? input : new Request(String(input), init); + const url = new URL(request.url); + if (url.pathname === TARGET_LOOKUP_PATH) return Promise.resolve(answer()); + return request.text().then((text) => { + sent.push({ + method: request.method, + path: url.pathname, + headers: request.headers, + body: text === "" ? undefined : decodeJson(text), + }); + return answer(); + }); + }; + return (body: Effect.Effect) => + Effect.acquireUseRelease( + Effect.sync(() => { + const previous = globalThis.fetch; + globalThis.fetch = Object.assign(stub, { preconnect: previous.preconnect }); + return previous; + }), + () => body, + (previous) => + Effect.sync(() => { + globalThis.fetch = previous; + }), + ); +}; + +const tempRoot = useTempWorkdir("supabase-api-shapes-int-"); + +const run = (argv: ReadonlyArray) => { + const args = [...argv, `--remote=${VALID_REF}`, "--yes"]; + const sent: Array = []; + const out = mockOutput({ format: "text" }); + const { console, calls } = fakeConsole(); + const layer = Layer.mergeAll( + buildTestRuntime({ + out, + api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), + cliSettings: mockCommandSettings({ workdir: tempRoot.current }), + tty: mockTty({ stdinIsTty: false, stdoutIsTty: false }), + stdin: mockStdin(false), + cliArgs: args, + }), + BunServices.layer, + CliOutput.layer(textCliOutputFormatter()), + Layer.succeed(ExperimentalFlag, false), + mockTelemetryRuntime({ configDir: tempRoot.current }), + mockRuntimeInfo({ cwd: tempRoot.current, homeDir: tempRoot.current }), + Stdio.layerTest({ args: Effect.succeed(args) }), + ); + const effect = withConfigEnv( + { SUPABASE_ACCESS_TOKEN: VALID_TOKEN, SUPABASE_NO_KEYRING: "1" }, + Command.runWith(fixtureRoot, { version: "0.0.0-test" })(args), + ).pipe(withApi(sent), Effect.provideService(Console.Console, console), Effect.provide(layer)); + return { sent, out, help: () => calls.join("\n"), effect }; +}; + +describe("generated command shapes", () => { + it("derives the fixture commands without problems", () => { + expect(derived.problems).toEqual([]); + expect(derived.entries.map((entry) => entry.command.join(" "))).toEqual([ + "fixture auth signing-keys get", + "fixture jit update", + "fixture keys update", + "fixture migrations create", + "fixture migrations get", + ]); + }); + + describe("a positional path parameter", () => { + it.effect("is path-encoded into the request of a three-word command", () => { + const { sent, effect } = run(["fixture", "migrations", "get", MIGRATION_VERSION]); + return Effect.gen(function* () { + yield* effect; + expect(sent.map(({ method, path }) => `${method} ${path}`)).toEqual([ + `GET ${MIGRATIONS_PATH}/${MIGRATION_VERSION}`, + ]); + }); + }); + + it.effect("reaches a four-word command through two nested groups", () => { + const { sent, effect } = run(["fixture", "auth", "signing-keys", "get", SIGNING_KEY_ID]); + return Effect.gen(function* () { + yield* effect; + expect(sent.map(({ path }) => path)).toEqual([ + `/v1/projects/${VALID_REF}/config/auth/signing-keys/${SIGNING_KEY_ID}`, + ]); + }); + }); + + it.effect("fails the parse and sends nothing when it is missing", () => { + const { sent, help, effect } = run(["fixture", "migrations", "get"]); + return Effect.gen(function* () { + const exit = yield* Effect.exit(effect); + expect(Exit.isFailure(exit)).toBe(true); + expect(help()).toContain(""); + expect(sent).toEqual([]); + }); + }); + + it.effect.each(["", ".."])( + "rejects the value %j as a usage error and sends nothing", + (value) => { + const { sent, effect } = run(["fixture", "migrations", "get", value]); + return Effect.gen(function* () { + const failure = yield* Effect.flip(effect); + expect(failure).toBeInstanceOf(ApiCommandUsageError); + expect(failure).toMatchObject({ + message: ' must not be empty, "." or "..".', + }); + expect(sent).toEqual([]); + }); + }, + ); + + it.effect("is interpolated into the dry-run path", () => { + const { sent, out, effect } = run([ + "fixture", + "migrations", + "get", + MIGRATION_VERSION, + "--dry-run", + ]); + return Effect.gen(function* () { + yield* effect; + expect(sent).toEqual([]); + expect(decodeJson(out.stdoutText)).toEqual({ + method: "GET", + path: `${MIGRATIONS_PATH}/${MIGRATION_VERSION}`, + query: {}, + headers: {}, + body: null, + }); + }); + }); + }); + + describe("a header flag", () => { + const create = ["fixture", "migrations", "create", "--query", "select 1"]; + + it.effect("is sent as the header when passed", () => { + const { sent, effect } = run([...create, "--idempotency-key", "retry-1"]); + return Effect.gen(function* () { + yield* effect; + expect(sent.map((request) => request.headers.get("idempotency-key"))).toEqual(["retry-1"]); + }); + }); + + it.effect("is left out of the request when absent", () => { + const { sent, effect } = run(create); + return Effect.gen(function* () { + yield* effect; + expect(sent.map((request) => request.headers.has("idempotency-key"))).toEqual([false]); + }); + }); + + it.effect("appears under headers in the dry-run document", () => { + const { out, effect } = run([...create, "--idempotency-key", "retry-1", "--dry-run"]); + return Effect.gen(function* () { + yield* effect; + expect(decodeJson(out.stdoutText)).toEqual({ + method: "POST", + path: MIGRATIONS_PATH, + query: {}, + headers: { "Idempotency-Key": "retry-1" }, + body: { query: "select 1" }, + }); + }); + }); + }); + + describe("a body field without a flag", () => { + const USER_ID = "55555555-5555-4555-8555-555555555555"; + const roles = [ + { role: "postgres", allowed_networks: { allowed_cidrs: [{ cidr: "10.0.0.0/8" }] } }, + ]; + const update = ["fixture", "jit", "update"]; + + it.effect("is sent from --body together with a flag-supplied scalar field", () => { + const { sent, effect } = run([ + ...update, + "--user-id", + USER_ID, + "--body", + encodeJson({ roles }), + ]); + return Effect.gen(function* () { + yield* effect; + expect(sent.map(({ method, path }) => `${method} ${path}`)).toEqual([ + `PUT /v1/projects/${VALID_REF}/database/jit`, + ]); + expect(sent.map((request) => request.body)).toEqual([{ user_id: USER_ID, roles }]); + }); + }); + + it.effect("is sent from --file together with a flag-supplied scalar field", () => { + const { sent, effect } = run([ + ...update, + "--user-id", + USER_ID, + "--file", + `${tempRoot.current}/jit.json`, + ]); + return Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + yield* fs.writeFileString(path.join(tempRoot.current, "jit.json"), encodeJson({ roles })); + yield* effect; + expect(sent.map((request) => request.body)).toEqual([{ user_id: USER_ID, roles }]); + }).pipe(Effect.provide(BunServices.layer)); + }); + + it.effect("has no flag in --help while its scalar sibling has one", () => { + const { help, effect } = run([...update, "--help"]); + return Effect.gen(function* () { + yield* effect; + expect(help()).toContain("--user-id"); + expect(help()).not.toContain("--roles"); + expect(help()).not.toContain("--role "); + }); + }); + }); + + describe("a required query flag", () => { + it.effect("reports a missing flag with the plain hint and sends nothing", () => { + const { sent, effect } = run(["fixture", "keys", "update"]); + return Effect.gen(function* () { + const failure = yield* effect.pipe(Effect.flip); + expect(failure).toMatchObject({ hint: "Pass the flag." }); + expect(sent).toEqual([]); + }); + }); + }); + + describe("help", () => { + it.effect("lists the nested group under its parent", () => { + const { help, effect } = run(["fixture", "auth", "--help"]); + return Effect.gen(function* () { + yield* effect; + expect(help()).toContain("signing-keys"); + expect(help()).toContain("Signing key fixtures (experimental)"); + }); + }); + + it.effect("shows the positional in the usage and the header as an optional flag", () => { + const read = run(["fixture", "migrations", "get", "--help"]); + const create = run(["fixture", "migrations", "create", "--help"]); + return Effect.gen(function* () { + yield* read.effect; + yield* create.effect; + expect(read.help()).toContain(""); + const flagLine = create + .help() + .split("\n") + .find((line) => line.includes("--idempotency-key ")); + expect(flagLine).toContain( + "A unique key to ensure the same migration is tracked only once.", + ); + expect(flagLine).not.toContain("Required"); + }); + }); + }); +}); diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index 1c51dc4141..7c7823ea88 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -9,6 +9,14 @@ export type ApiCommandBinding = /** The value comes from the command target (`--project-ref` or the linked project), not a flag. */ readonly source: "target"; } + | { + readonly location: "path"; + readonly name: string; + /** The value comes from the command's positional argument. */ + readonly source: "argument"; + /** Name of the positional argument that supplies the value. */ + readonly argument: string; + } | { readonly location: "query"; /** Query parameter name. */ @@ -17,6 +25,13 @@ export type ApiCommandBinding = /** Name of the flag that supplies the value. */ readonly flag: string; } + | { + readonly location: "header"; + /** Header name as declared in the spec. */ + readonly name: string; + readonly source: "flag"; + readonly flag: string; + } | { readonly location: "body"; /** Body field name. */ @@ -27,7 +42,7 @@ export type ApiCommandBinding = readonly flag: string; }; -/** One flag of a generated command, derived from a query parameter or a request body field. */ +/** One flag of a generated command, derived from a query parameter, a header parameter or a request body field. */ export interface ApiCommandFlag { /** Kebab-case flag name without the leading dashes. */ readonly name: string; @@ -42,7 +57,7 @@ export interface ApiCommandFlag { /** What `--wait` polls after a change and when it is done. */ export interface ApiCommandWait { - /** Operation id of the read operation to poll. */ + /** Operation id of the read operation to poll; the command's own when it polls itself. */ readonly read: string; /** Read parameter name to JSON pointer into the change response. */ readonly params: Readonly>; @@ -56,7 +71,7 @@ export interface ApiCommandWait { /** A generated command as plain data; the runtime turns each entry into a CLI command. */ export interface ApiCommandEntry { - /** Noun path followed by the verb, e.g. `["warehouse", "enable"]`. */ + /** Noun, optional sub-groups and the verb, e.g. `["warehouse", "enable"]`. */ readonly command: readonly string[]; /** Kebab-case operation id from the OpenAPI spec. */ readonly operationId: string; @@ -66,11 +81,9 @@ export interface ApiCommandEntry { readonly apiPath: string; readonly summary: string; readonly description?: string; - readonly scope: "project"; readonly readOnly: boolean; - readonly stability: "experimental"; /** Feature that gates the command's noun. */ - readonly feature?: string; + readonly feature: string; /** Request body shape; `json-envelope` bodies wrap fields in `data.attributes`. */ readonly body?: { readonly contentType: "application/json"; @@ -83,6 +96,11 @@ export interface ApiCommandEntry { readonly status: number; readonly kind: "json" | "text" | "empty"; }; + /** The positional argument that carries the operation's one non-`ref` path parameter. */ + readonly argument?: { + readonly name: string; + readonly description?: string; + }; readonly flags: readonly ApiCommandFlag[]; readonly bindings: readonly ApiCommandBinding[]; readonly wait?: ApiCommandWait; diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index ae5655be5d..6d344c6780 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -46,22 +46,28 @@ const runWarehouse = ( ) => Effect.gen(function* () { const requests: Array = []; + const bodies: Array = []; + const runPromise = Effect.runPromiseWith(yield* Effect.context()); const server = yield* Effect.acquireRelease( Effect.try({ try: () => Bun.serve({ hostname: "127.0.0.1", port: 0, - fetch(incoming) { - const { pathname } = new URL(incoming.url); - if (pathname === `/v1/projects/${REF}`) return Response.json({}); - requests.push(`${incoming.method} ${pathname}`); - const served = route({ method: incoming.method, pathname }); - return new Response(served.body, { - status: served.status, - headers: { "content-type": "application/json" }, - }); - }, + fetch: (incoming) => + runPromise( + Effect.gen(function* () { + const { pathname } = new URL(incoming.url); + if (pathname === `/v1/projects/${REF}`) return Response.json({}); + requests.push(`${incoming.method} ${pathname}`); + bodies.push(yield* Effect.promise(() => incoming.text())); + const served = route({ method: incoming.method, pathname }); + return new Response(served.body, { + status: served.status, + headers: { "content-type": "application/json" }, + }); + }), + ), }), catch: (cause) => new ApiCommandsE2eSetupError({ cause }), }), @@ -97,23 +103,9 @@ const runWarehouse = ( SUPABASE_YES: undefined, }, }); - return { result, requests }; + return { result, requests, bodies }; }).pipe(Effect.scoped); -it.live("warehouse enable prints the accepted response byte for byte", () => - Effect.gen(function* () { - const accepted = `{"data":{"type":"warehouse_setup","attributes":{"selection_id":"${SEL}","status":"pending","future_field":{"nested":[1, 2]}}}}`; - const { result, requests } = yield* runWarehouse( - ["enable", "--schema", "public", "--yes", "-o", "json"], - () => ({ status: 202, body: accepted }), - ); - - requireCliSuccess(result, "warehouse enable --yes -o json"); - expect(result.stdout, result.stderr).toBe(accepted); - expect(requests).toEqual([`POST ${ENABLE_PATH}`]); - }).pipe(Effect.provide(BunServices.layer)), -); - it.live("warehouse status reports a 409 as a conflict failure document on stderr", () => Effect.gen(function* () { const { result } = yield* runWarehouse(["status", "-o", "json"], () => @@ -175,9 +167,9 @@ it.live("warehouse enable --wait prints the final status read", () => it.live("warehouse enable --file - reads the request body piped on stdin", () => Effect.gen(function* () { - const accepted = `{"data":{"type":"warehouse_setup","attributes":{"selection_id":"${SEL}"}}}`; + const accepted = `{"data":{"type":"warehouse_setup","attributes":{"selection_id":"${SEL}","status":"pending","future_field":{"nested":[1, 2]}}}}`; const body = '{"data":{"type":"warehouse_setup","attributes":{"schema":"public"}}}'; - const { result, requests } = yield* runWarehouse( + const { result, requests, bodies } = yield* runWarehouse( ["enable", "--file", "-", "--yes", "-o", "json"], () => ({ status: 202, body: accepted }), { stdin: body }, @@ -186,5 +178,6 @@ it.live("warehouse enable --file - reads the request body piped on stdin", () => requireCliSuccess(result, "warehouse enable --file -"); expect(result.stdout, result.stderr).toBe(accepted); expect(requests).toEqual([`POST ${ENABLE_PATH}`]); + expect(decodeJson(bodies[0] ?? "")).toEqual(decodeJson(body)); }).pipe(Effect.provide(BunServices.layer)), ); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 6c2d0d91ee..a5e6c8c5b0 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -1,6 +1,18 @@ import { BunServices } from "@effect/platform-bun"; import { describe, expect, it } from "@effect/vitest"; -import { Effect, Exit, Fiber, FileSystem, Layer, Option, Path, Schema, Stdio } from "effect"; +import { + Cause, + Console, + Effect, + Exit, + Fiber, + FileSystem, + Layer, + Option, + Path, + Schema, + Stdio, +} from "effect"; import { CliOutput, Command } from "effect/cli"; import * as HttpClientError from "effect/http/HttpClientError"; import * as TestClock from "effect/testing/TestClock"; @@ -24,6 +36,7 @@ import { } from "../../../tests/helpers/command-mocks.ts"; import { describeHostedConsent } from "../../../tests/helpers/hosted-consent.ts"; import { + fakeConsole, mockOutput, mockRuntimeInfo, mockStdin, @@ -35,12 +48,12 @@ import { ApiCommandStatusError, ApiCommandUsageError, ApiCommandWaitTimeoutError, -} from "./api-command.errors.ts"; +} from "../../command-internal/command-errors/api-command.errors.ts"; import type { ApiCommandEntry } from "./api-command.model.ts"; import { assembleInput, decodeInput, previewRequest } from "./api-command-request.ts"; import { apiCommands } from "./generated.ts"; import { readApiCommand } from "./api-command.annotation.ts"; -import { readCommandStage } from "./api-command-stage.ts"; +import { readCommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; import { apiCommandGroup, apiCommandGroups } from "./runtime.ts"; import { resolveWarehouseEnabled } from "./warehouse-backend.ts"; @@ -393,6 +406,7 @@ describe("generated warehouse commands", () => { method: "POST", path: ENABLE_PATH, query: {}, + headers: {}, body: { data: { type: "warehouse_setup", attributes: { schema: "public", tables: ["a"] } }, }, @@ -433,6 +447,7 @@ describe("generated warehouse commands", () => { method: "GET", path: STATUS_PATH, query: { inspect_fdw: "false" }, + headers: {}, body: null, }); }); @@ -449,6 +464,7 @@ describe("generated warehouse commands", () => { method: "POST", path: ENABLE_PATH, query: {}, + headers: {}, body: { data: { type: "warehouse_setup", attributes: { schema: "public" } } }, }); }); @@ -616,6 +632,20 @@ describe("generated warehouse commands", () => { }); }); + describe("help", () => { + it.effect("marks a required API flag as required in its description", () => { + const { console, calls } = fakeConsole(); + const { run } = setup(["warehouse", "enable", "--help"], { route: accepted }); + return Effect.gen(function* () { + yield* run.pipe(Effect.provideService(Console.Console, console)); + const lines = calls.join("\n").split("\n"); + const flagLine = (name: string) => lines.find((line) => line.includes(`--${name} `)); + expect(flagLine("schema")).toContain("Required unless the field is in --body or --file."); + expect(flagLine("table")).not.toContain("Required"); + }); + }); + }); + describe("--wait", () => { const driveClock = (fiber: Fiber.Fiber) => Effect.raceFirst(Effect.forever(TestClock.adjust("2 seconds")), Fiber.await(fiber)); @@ -689,37 +719,76 @@ describe("generated warehouse commands", () => { }); it.effect( - "prints the original response and reads nothing when the change gives no selection_id", + "fails with the standard operation_failed error when a failed status has no error", () => { - const noSelection = { - data: { type: "warehouse_setup", attributes: { status: "pending" } }, - }; - const { sent, out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + const { run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { yes: true, - route: () => ({ status: 202, body: noSelection }), + route: enableThenPoll([{ status: 200, body: statusBody("failed") }]), }); return Effect.gen(function* () { - yield* run; - expect(sent.map((request) => request.method)).toEqual(["POST"]); - expect(out.stdoutText).toBe(encodeJson(noSelection)); + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + const failure = yield* Fiber.join(fiber); + expect(failure).toBeInstanceOf(ApiCommandOperationFailedError); + expect(failure).toMatchObject({ + status: "failed", + message: 'The operation failed with status "failed".', + }); }); }, ); - it.effect("fails when the status_error pointer is set, whatever the status", () => { - const { run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + it.effect("succeeds and prints the read when a succeeded status carries an error value", () => { + const settled = statusBody("succeeded", "earlier attempt failed"); + const { out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { yes: true, - route: enableThenPoll([{ status: 200, body: statusBody("pending", "disk full") }]), + route: enableThenPoll([{ status: 200, body: settled }]), }); return Effect.gen(function* () { - const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); yield* driveClock(fiber); - const failure = yield* Fiber.join(fiber); - expect(failure).toBeInstanceOf(ApiCommandOperationFailedError); - expect(failure).toMatchObject({ status: "pending", message: "disk full" }); + yield* Fiber.join(fiber); + expect(out.stdoutText).toBe(encodeJson(settled)); + }); + }); + + it.effect("keeps polling while a non-terminal status carries an error value", () => { + const { sent, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([ + { status: 200, body: statusBody("pending", "retrying") }, + { status: 200, body: statusBody("succeeded") }, + ]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + yield* Fiber.join(fiber); + expect(sent.filter((request) => request.method === "GET")).toHaveLength(2); }); }); + it.effect( + "ends the wait with a defect when the accepted response lacks the selection id", + () => { + const { sent, run } = setup( + ["warehouse", "enable", "--schema", "public", "--yes", "--wait"], + { + yes: true, + route: (request) => + request.method === "POST" + ? { status: 202, body: { data: { type: "warehouse_setup", attributes: {} } } } + : { status: 200, body: statusBody("succeeded") }, + }, + ); + return Effect.gen(function* () { + const exit = yield* Effect.exit(run); + expect(Exit.isFailure(exit) && Cause.hasDies(exit.cause)).toBe(true); + expect(sent.map((request) => request.method)).toEqual(["POST"]); + }); + }, + ); + it.effect("names the status command when the setup fails and when the wait times out", () => { const failing = setup(["warehouse", "enable", "--schema", "public", "--wait"], { yes: true, @@ -760,6 +829,74 @@ describe("generated warehouse commands", () => { }); }); + describe("on a read that polls itself", () => { + const statusWait = ["warehouse", "status", "--wait"]; + const reads = (...replies: ReadonlyArray): Route => { + let read = 0; + return () => replies[Math.min(read++, replies.length - 1)] ?? { status: 200, body: {} }; + }; + + it.effect("polls its own route until the setup succeeds and prints the last read", () => { + const { sent, out, run } = setup(statusWait, { + route: reads( + { status: 200, body: statusBody("pending") }, + { status: 200, body: statusBody("pending") }, + { status: 200, body: statusBody("succeeded") }, + ), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + yield* Fiber.join(fiber); + expect(sent.map((request) => request.method)).toEqual(["GET", "GET", "GET"]); + expect(sent.every((request) => request.path === STATUS_PATH)).toBe(true); + expect(out.stdoutText).toBe(encodeJson(statusBody("succeeded"))); + }); + }); + + it.effect("fails with the reported status_error when the setup fails", () => { + const { run } = setup(statusWait, { + route: reads({ status: 200, body: statusBody("failed", "pipeline crashed") }), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + const failure = yield* Fiber.join(fiber); + expect(failure).toBeInstanceOf(ApiCommandOperationFailedError); + expect(failure).toMatchObject({ + message: expect.stringContaining("pipeline crashed"), + hint: expect.stringContaining(`supabase warehouse status --remote=${VALID_REF}`), + }); + }); + }); + + it.effect("times out and names the status command to check later", () => { + const { sent, run } = setup([...statusWait, "--timeout", "10s"], { + route: reads({ status: 200, body: statusBody("pending") }), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + const failure = yield* Fiber.join(fiber); + expect(failure).toBeInstanceOf(ApiCommandWaitTimeoutError); + expect(failure).toMatchObject({ + hint: expect.stringContaining(`supabase warehouse status --remote=${VALID_REF}`), + }); + expect(sent.length).toBeGreaterThan(1); + }); + }); + + it.effect("sends nothing under --dry-run", () => { + const { sent, run } = setup([...statusWait, "--dry-run"], { + route: ok(statusBody("succeeded")), + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([]); + }); + }); + }); + it.effect("rejects an invalid --timeout before sending anything", () => { const { sent, run } = setup( ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "soon"], @@ -779,7 +916,11 @@ describe("generated warehouse commands", () => { }; const fixtureRoot = (entry: ApiCommandEntry) => Command.make("supabase").pipe( - Command.withSubcommands([apiCommandGroup("fixture", "Fixture commands", [entry])]), + Command.withSubcommands([ + apiCommandGroup("fixture", { description: "Fixture commands", feature: "fixture" }, [ + entry, + ]), + ]), Command.withGlobalFlags(GLOBAL_FLAGS), ); @@ -866,7 +1007,7 @@ describe("generated warehouse commands", () => { Option.some(entry.operationId), ); expect(readCommandStage(command)).toEqual( - Option.some({ status: "experimental", gate: { kind: "feature", feature: "warehouse" } }), + Option.some({ status: "experimental", feature: "warehouse" }), ); } }); diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 2262ba47b3..7ae0b55a84 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -10,10 +10,8 @@ export const apiCommands = [ apiPath: "/v2/projects/{ref}/warehouse/enable", summary: "Enable Warehouse replication", description: - "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.\n\nThis endpoint is currently in its **Alpha** stage.", - scope: "project", + "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.", readOnly: false, - stability: "experimental", feature: "warehouse", body: { contentType: "application/json", @@ -127,10 +125,8 @@ export const apiCommands = [ apiPath: "/v2/projects/{ref}/warehouse/setups/current", summary: "Get Warehouse initial synchronization status", description: - "Returns setup phases, linked tables, pipeline and routing state, cleanup errors, and optional FDW inspection. Set inspect_fdw=false to skip database FDW inspection. A null table replication_state means no observation is available. Status succeeded requires initial copy, a running pipeline and ready routing; it does not verify query connectivity. Pass the selection_id returned by enable to reject a changed selection while waiting.\n\nThis endpoint is currently in its **Alpha** stage.", - scope: "project", + "Returns setup phases, linked tables, pipeline and routing state, cleanup errors, and optional FDW inspection. Set inspect_fdw=false to skip database FDW inspection. A null table replication_state means no observation is available. Status succeeded requires initial copy, a running pipeline and ready routing; it does not verify query connectivity. Pass the selection_id returned by enable to reject a changed selection while waiting.", readOnly: true, - stability: "experimental", feature: "warehouse", response: { status: 200, @@ -174,5 +170,13 @@ export const apiCommands = [ flag: "selection-id", }, ], + wait: { + read: "v2-get-warehouse-setup", + params: {}, + status: "/data/attributes/status", + succeeded: ["succeeded"], + failed: ["failed"], + error: "/data/attributes/status_error", + }, }, ] as const satisfies readonly ApiCommandEntry[]; diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index ad2b32f624..3226d5e763 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -1,8 +1,14 @@ import { Effect, Layer, Option } from "effect"; -import { Command, Flag } from "effect/cli"; +import { Argument, Command, Flag } from "effect/cli"; +import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; +import { withStandardErrors } from "../../command-internal/command-errors/command-errors.annotation.ts"; import { withPermissions } from "../../command-internal/command-permissions/command-permissions.annotation.ts"; import { compose, type OperationEntry } from "../../command-internal/command-permissions/model.ts"; +import { + type CommandStage, + withCommandStage, +} from "../../command-internal/command-stage/command-stage.annotation.ts"; import { parseDuration } from "../../command-internal/duration.ts"; import { OutputFlag } from "../../command-internal/global-flags.ts"; import { requireHostedMutationConsent } from "../../command-internal/hosted-consent/hosted-consent.ts"; @@ -19,38 +25,65 @@ import { linkedProjectCache } from "../../telemetry/linked-project-cache.layer.t import { TelemetryState } from "../../telemetry/telemetry-state.service.ts"; import { type ApiOutputFormat, + linkedReadInput, sendApiRequest, waitForOperation, writeApiResponse, writeDocument, } from "./api-command-execute.ts"; -import { apiFlag } from "./api-command-flags.ts"; +import { type ApiFlagLocation, apiFlag } from "./api-command-flags.ts"; +import { type ApiNoun, nouns } from "./api-command-policy.ts"; import { assembleInput, decodeInput, previewRequest, readBodyOverride, } from "./api-command-request.ts"; -import { type CommandStage, enforceStage, withCommandStage } from "./api-command-stage.ts"; import { withApiCommand } from "./api-command.annotation.ts"; -import { ApiCommandUsageError } from "./api-command.errors.ts"; -import type { ApiCommandEntry } from "./api-command.model.ts"; +import type { ApiCommandEntry, ApiCommandFlag, ApiCommandWait } from "./api-command.model.ts"; import { apiCommands } from "./generated.ts"; -import { withStandardErrors } from "../../command-internal/command-errors/command-errors.annotation.ts"; -import { nouns } from "./api-command-overrides.ts"; const DEFAULT_WAIT_TIMEOUT = "10m"; const NANOSECONDS_PER_MILLISECOND = 1_000_000; const stageOf = (entry: ApiCommandEntry): CommandStage => ({ status: "experimental", - gate: - entry.feature === undefined ? { kind: "flag" } : { kind: "feature", feature: entry.feature }, + feature: entry.feature, }); -/** The flag config of a generated command: target flags, runtime flags and one flag per API field. */ -const flagConfig = (entry: ApiCommandEntry) => ({ +/** A command's `--wait`: the wait declared on its entry and the entry of the operation it polls. */ +interface ResolvedWait { + readonly wait: ApiCommandWait; + readonly readEntry: ApiCommandEntry; +} + +const resolveWait = ( + entry: ApiCommandEntry, + entries: ReadonlyArray, +): ResolvedWait | undefined => { + const { wait } = entry; + if (wait === undefined) return undefined; + const readEntry = entries.find((candidate) => candidate.operationId === wait.read); + return readEntry === undefined ? undefined : { wait, readEntry }; +}; + +const flagLocation = (entry: ApiCommandEntry, flag: ApiCommandFlag): ApiFlagLocation => { + for (const binding of entry.bindings) { + if (binding.source === "flag" && binding.flag === flag.name) return binding.location; + } + return "body"; +}; + +/** The config of a generated command: target flags, runtime flags, one flag per API field and the positional. */ +const flagConfig = (entry: ApiCommandEntry, waitable: boolean) => ({ ...projectTargetFlags(), + ...(entry.argument === undefined + ? {} + : { + argument: Argument.String(entry.argument.name).pipe( + Argument.withDescription(entry.argument.description ?? `Set ${entry.argument.name}.`), + ), + }), ...(entry.body === undefined ? {} : { @@ -71,7 +104,7 @@ const flagConfig = (entry: ApiCommandEntry) => ({ Flag.withDescription("Print the request that would be sent and send nothing."), Flag.withDefault(false), ), - ...(entry.wait === undefined + ...(!waitable ? {} : { wait: Flag.Boolean("wait").pipe( @@ -83,7 +116,9 @@ const flagConfig = (entry: ApiCommandEntry) => ({ Flag.withDefault(DEFAULT_WAIT_TIMEOUT), ), }), - api: Object.fromEntries(entry.flags.map((flag) => [flag.name, apiFlag(flag)])), + api: Object.fromEntries( + entry.flags.map((flag) => [flag.name, apiFlag(flag, flagLocation(entry, flag))]), + ), }); const parseTimeoutMillis = (value: string) => @@ -113,6 +148,7 @@ const OUTPUT_FORMATS: ReadonlyArray = ["json", "yaml"]; interface ApiCommandFlags { readonly remote: Parameters[0]["remote"]; readonly projectRef: Parameters[0]["projectRef"]; + readonly argument?: string; readonly body?: Option.Option; readonly file?: Option.Option; readonly dryRun: boolean; @@ -124,6 +160,7 @@ interface ApiCommandFlags { /** Runs one generated command: assemble and validate the request, consent, send, optionally wait, print. */ const handle = Effect.fn("api-command.run")(function* ( entry: ApiCommandEntry, + resolved: ResolvedWait | undefined, flags: ApiCommandFlags, ) { yield* Effect.annotateCurrentSpan("operation.id", entry.operationId); @@ -132,18 +169,17 @@ const handle = Effect.fn("api-command.run")(function* ( const outputFlag = yield* OutputFlag; const format: ApiOutputFormat = Option.getOrUndefined(outputFlag) === "yaml" ? "yaml" : "json"; yield* Effect.gen(function* () { - yield* enforceStage(stageOf(entry)); const ref = yield* resolveProjectTarget(flags); yield* Effect.gen(function* () { - const timeoutMillis = - entry.wait !== undefined && flags.wait === true - ? yield* parseTimeoutMillis(flags.timeout ?? DEFAULT_WAIT_TIMEOUT) - : 0; + const waiting = resolved !== undefined && flags.wait === true; + const timeoutMillis = waiting + ? yield* parseTimeoutMillis(flags.timeout ?? DEFAULT_WAIT_TIMEOUT) + : 0; const override = yield* readBodyOverride({ body: flags.body ?? Option.none(), file: flags.file ?? Option.none(), }); - const input = yield* assembleInput(entry, ref, flags.api, override); + const input = yield* assembleInput(entry, ref, flags.api, override, flags.argument); const decoded = yield* decodeInput(entry, input); if (flags.dryRun) { @@ -154,21 +190,28 @@ const handle = Effect.fn("api-command.run")(function* ( yield* requireHostedMutationConsent({ action: consentAction(entry) }); } - const response = yield* sendApiRequest(entry, decoded); - if (entry.wait !== undefined && flags.wait === true) { + if (waiting) { + // A read that polls itself needs no change request: its own input is what gets polled. + const selfPolling = resolved.readEntry.operationId === entry.operationId; + const readInput = selfPolling + ? input + : yield* linkedReadInput({ + wait: resolved.wait, + changedOperationId: entry.operationId, + ref, + changed: yield* sendApiRequest(entry, decoded), + }); const settled = yield* waitForOperation({ - wait: entry.wait, - changedEntry: entry, + wait: resolved.wait, + readEntry: resolved.readEntry, + readInput, ref, - changed: response, timeoutMillis, }); - yield* Effect.annotateCurrentSpan( - "run.outcome", - settled.entry === entry ? "wait_skipped" : "waited", - ); - return yield* writeApiResponse(settled.entry, settled.response, format); + yield* Effect.annotateCurrentSpan("run.outcome", "waited"); + return yield* writeApiResponse(resolved.readEntry, settled, format); } + const response = yield* sendApiRequest(entry, decoded); yield* Effect.annotateCurrentSpan("run.outcome", "sent"); return yield* writeApiResponse(entry, response, format); }).pipe(Effect.ensuring(cache.cache(ref))); @@ -179,17 +222,19 @@ const exampleFor = (entry: ApiCommandEntry): string => { const required = entry.flags .filter((flag) => flag.required) .map((flag) => `--${flag.name}${flag.type === "boolean" ? "" : ` <${flag.name}>`}`); - return ["supabase", ...entry.command, ...required].join(" "); + const positional = entry.argument === undefined ? [] : [`<${entry.argument.name}>`]; + return ["supabase", ...entry.command, ...positional, ...required].join(" "); }; -const permissionsOf = (entry: ApiCommandEntry) => { +const permissionsOf = (entry: ApiCommandEntry, resolved: ResolvedWait | undefined) => { + const polled = resolved?.readEntry.operationId; const operations: ReadonlyArray = [ { operationId: entry.operationId, kind: "required" }, - ...(entry.wait === undefined + ...(polled === undefined || polled === entry.operationId ? [] : [ { - operationId: entry.wait.read, + operationId: polled, kind: "required" as const, when: [{ flag: "wait", is: true }], }, @@ -198,7 +243,8 @@ const permissionsOf = (entry: ApiCommandEntry) => { const noApiEffectFlags = [ "dry-run", ...(entry.body === undefined ? [] : ["body", "file"]), - ...(entry.wait === undefined ? [] : ["timeout"]), + ...(resolved === undefined ? [] : ["timeout"]), + ...(polled === entry.operationId ? ["wait"] : []), ...entry.flags.map((flag) => flag.name), ]; return compose( @@ -209,9 +255,10 @@ const permissionsOf = (entry: ApiCommandEntry) => { ); }; -const leafOf = (entry: ApiCommandEntry) => { +const leafOf = (entry: ApiCommandEntry, entries: ReadonlyArray) => { const verb = entry.command[entry.command.length - 1] ?? entry.operationId; - const config = flagConfig(entry); + const resolved = resolveWait(entry, entries); + const config = flagConfig(entry, resolved !== undefined); return Command.make(verb, config).pipe( Command.withDescription(entry.description ?? entry.summary), Command.withShortDescription(`${entry.summary} (experimental)`), @@ -221,12 +268,12 @@ const leafOf = (entry: ApiCommandEntry) => { bindings: entry.bindings, response: entry.response, }), - withPermissions(permissionsOf(entry)), + withPermissions(permissionsOf(entry, resolved)), withCommandStage(stageOf(entry)), withStandardErrors, Command.withHandler((flags) => { - const { api: _generated, ...recorded } = flags; - return handle(entry, flags).pipe( + const { api: _generated, argument: _argument, ...recorded } = flags; + return handle(entry, resolved, flags).pipe( withCommandTelemetry({ flags: recorded, outputFormats: OUTPUT_FORMATS }), ); }), @@ -236,36 +283,56 @@ const leafOf = (entry: ApiCommandEntry) => { ); }; -/** The command group of `noun`, with one leaf per entry whose command path sits under it. */ -export const apiCommandGroup = ( - noun: string, +type ApiLeaf = ReturnType; +type ApiGroup = Command.Command, Command.Services>; + +const startsWith = (command: ReadonlyArray, prefix: ReadonlyArray): boolean => + prefix.every((word, index) => command[index] === word); + +const groupOf = ( + path: ReadonlyArray, description: string, + definition: ApiNoun, entries: ReadonlyArray, -) => { - const leaves = entries - .filter((entry) => entry.command.slice(0, -1).join(".") === noun) - .map(leafOf); - return Command.make(noun).pipe( +): ApiGroup => { + const under = entries.filter((entry) => startsWith(entry.command, path)); + const leaves = under + .filter((entry) => entry.command.length === path.length + 1) + .map((entry) => leafOf(entry, entries)); + const children = Object.entries(definition.groups ?? {}).flatMap(([key, childDescription]) => { + const childPath = [...path.slice(0, 1), ...key.split(".")]; + const isChild = childPath.length === path.length + 1 && startsWith(childPath, path); + const hasCommands = under.some((entry) => startsWith(entry.command, childPath)); + return isChild && hasCommands + ? [groupOf(childPath, childDescription, definition, entries)] + : []; + }); + return Command.make(path[path.length - 1] ?? "").pipe( Command.withDescription(`${description} (experimental)`), Command.withShortDescription(`${description} (experimental)`), - Command.withSubcommands(leaves), + Command.withSubcommands([...leaves, ...children]), ); }; +/** The command group of `noun`, with its sub-groups and one leaf per entry whose command sits under it. */ +export const apiCommandGroup = ( + noun: string, + definition: ApiNoun, + entries: ReadonlyArray, +) => groupOf([noun], definition.description, definition, entries); + const groupCache = new Map>(); /** * The noun groups of the generated Management API commands, one per noun whose feature is - * enabled (or that has no feature); a group is built on first use. + * enabled; a group is built on first use. */ export const apiCommandGroups = (enabledFeatures: ReadonlyArray) => Object.entries(nouns).flatMap(([noun, definition]) => { - if (definition.feature !== undefined && !enabledFeatures.includes(definition.feature)) { - return []; - } + if (!enabledFeatures.includes(definition.feature)) return []; const cached = groupCache.get(noun); if (cached !== undefined) return [cached]; - const group = apiCommandGroup(noun, definition.description, apiCommands); + const group = apiCommandGroup(noun, definition, apiCommands); groupCache.set(noun, group); return [group]; }); diff --git a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md index 521401fe54..a43abec59f 100644 --- a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md @@ -1,6 +1,6 @@ # `supabase warehouse enable` -Target: hosted, consent `no` (confirm unless `--yes`; a non-interactive run without `--yes` is a usage error), see [Command target](../../../../../docs/command-target.md) +Target: hosted, consent default No (confirm unless `--yes`; a run that cannot prompt and has no `--yes` is a usage error), see [Command target](../../../../../docs/command-target.md) ## Feature gate @@ -34,11 +34,12 @@ The command is generated from the Management API contract (`generated.ts`). | `POST` | `/v2/projects/{ref}/warehouse/enable` | Bearer token | `{"data":{"type":"warehouse_setup","attributes":{…}}}`; only the flags that were given are present | passed through unchanged; `data.attributes.selection_id` feeds `--wait` | | `GET` | `/v2/projects/{ref}/warehouse/setups/current` | Bearer token | none | `data.attributes.status`, `status_error`; polled with backoff from 1s doubling to a 10s cap (a longer `Retry-After` wins), only with `--wait` | | `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive (project picker) | +| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}`; linked-project cache miss only (best-effort, after the command) | `--body` or `--file` supply the whole body; a flag replaces its own field and nothing else. The input is validated before consent and before any request, so a top-level body key outside the -declared request-body fields, an unknown nested field or a missing `--schema` fails with nothing sent. `--dry-run` prints `{method, path, query, body}` and sends -nothing, before consent. +declared request-body fields, an unknown nested field or a missing `--schema` fails with nothing sent. `--dry-run` prints `{method, path, query, headers, body}` and sends no command request (the linked-project cache read in the table above can still run), +before consent. ## Exit Codes @@ -48,7 +49,7 @@ nothing, before consent. | `2` | `usage_error`: invalid flags or body, or consent needed without `--yes` | | `130` | consent declined at the prompt (`cancelled`) | | `1` | API error (non-2xx) | -| `1` | with `--wait`: `operation_failed` (failed status) or `wait_timeout` | +| `1` | with `--wait`: `operation_failed` (a failed status) or `wait_timeout` | ## Environment Variables @@ -83,5 +84,6 @@ and `--wait` record `true`. Generated field flags, `--body`, `--file` and `--tim ## Notes - Repeating the same selection is safe; the API rejects a different existing selection. -- A response without `data.attributes.selection_id` is printed as is, without waiting. +- `--wait` fails only on a status in the failed set; `status_error` supplies the failure message and does not end the wait by itself. +- `data.attributes.selection_id` is required in the accepted response; a response without it is a defect and ends `--wait` with an internal error, never a silent success. - `--wait` never resumes after a 409; any non-2xx while polling ends the command with the API error. diff --git a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md index 67fa87e803..7c841c6676 100644 --- a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md @@ -28,21 +28,29 @@ The command is generated from the Management API contract (`generated.ts`). ## API Routes -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | --------------------------------------------- | ------------ | ------------ | -------------------------------------------------------- | -| `GET` | `/v2/projects/{ref}/warehouse/setups/current` | Bearer token | none | passed through unchanged | -| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive | +| Method | Path | Auth | Request body | Response (used fields) | +| ------ | --------------------------------------------- | ------------ | ------------ | --------------------------------------------------------------- | +| `GET` | `/v2/projects/{ref}/warehouse/setups/current` | Bearer token | none | passed through unchanged | +| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive | +| `GET` | `/v1/projects/{ref}` | Bearer token | none | linked-project cache miss only (best-effort, after the command) | Query: `inspect_fdw=true|false` and `selection_id=`, each only when its flag was given. -`--dry-run` prints `{method, path, query, body}` and sends nothing. +`--dry-run` prints `{method, path, query, headers, body}` and sends no command request (the linked-project cache read in the table above can still run). + +With `--wait` the command sends no change request: the first send is the first poll, and it polls +its own route with its own flags. Polling backs off from 1s, doubling to a 10s cap (a longer +`Retry-After` wins), until `data.attributes.status` is `succeeded` or `failed` or `--timeout` +(default `10m`) elapses. The output is the last read. Any non-2xx while polling ends the command +with the API error. ## Exit Codes -| Code | Condition | -| ---- | ---------------------------------- | -| `0` | success | -| `2` | `usage_error`: invalid flags | -| `1` | API error (non-2xx, including 409) | +| Code | Condition | +| ---- | ------------------------------------------------------------------------------------------ | +| `0` | success (with `--wait`, the setup succeeded) | +| `2` | `usage_error`: invalid flags | +| `1` | API error (non-2xx, including 409) | +| `1` | with `--wait`: `operation_failed` (a failed status, with `status_error`) or `wait_timeout` | ## Environment Variables @@ -62,14 +70,14 @@ Query: `inspect_fdw=true|false` and `selection_id=`, each only when its flag | `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` -records `true`. Generated field flags (`--inspect-fdw`, `--selection-id`), `--body` and `--file` are -recorded as ``. +and `--wait` record `true`. Generated field flags (`--inspect-fdw`, `--selection-id`) and `--timeout` +are recorded as ``. ## Output -| Mode | stdout | -| -------------- | ---------------------------------------- | -| text (default) | the API's JSON response bytes, unchanged | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML | -| `--dry-run` | the request preview as JSON | +| Mode | stdout | +| -------------- | --------------------------------------------------------------------- | +| text (default) | the API's JSON response bytes, unchanged; with `--wait` the last read | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML | +| `--dry-run` | the request preview as JSON | diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index 34bc4ba30f..86589a072c 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -17,7 +17,7 @@ import { ApiCommandStatusError, ApiCommandUsageError, ApiCommandWaitTimeoutError, -} from "../../commands/api/api-command.errors.ts"; +} from "../../command-internal/command-errors/api-command.errors.ts"; import { LinkBranchListStatusError } from "../../command-internal/target/branch-resolution.errors.ts"; import { normalizeCause } from "../output/normalize-error.ts"; import { writeStdio } from "../output/output.layer.ts"; diff --git a/apps/cli/src/shared/cli/standard-errors.unit.test.ts b/apps/cli/src/shared/cli/standard-errors.unit.test.ts index 4bf0b59cb1..f95aa96146 100644 --- a/apps/cli/src/shared/cli/standard-errors.unit.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.unit.test.ts @@ -15,7 +15,7 @@ import { ApiCommandStatusError, ApiCommandUsageError, ApiCommandWaitTimeoutError, -} from "../../commands/api/api-command.errors.ts"; +} from "../../command-internal/command-errors/api-command.errors.ts"; import { LinkBranchListNetworkError, LinkBranchListStatusError, diff --git a/apps/cli/tests/fixtures/standard-errors-cli.ts b/apps/cli/tests/fixtures/standard-errors-cli.ts index ee0d15c1e6..746973d93c 100644 --- a/apps/cli/tests/fixtures/standard-errors-cli.ts +++ b/apps/cli/tests/fixtures/standard-errors-cli.ts @@ -8,7 +8,7 @@ import { } from "../../src/command-internal/hosted-consent/hosted-consent.errors.ts"; import { parseTargetSelector } from "../../src/command-internal/target/target-selector.ts"; import { projectTargetFlags } from "../../src/command-internal/target/target-flags.ts"; -import { ApiCommandStatusError } from "../../src/commands/api/api-command.errors.ts"; +import { ApiCommandStatusError } from "../../src/command-internal/command-errors/api-command.errors.ts"; import { runCli } from "../../src/shared/cli/run.ts"; import { mockAnalytics } from "../helpers/mocks.ts"; From e176ddcaf7771eabf87f2b3a7b5ba1a1ffd75f17 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Mon, 16 Nov 2026 18:49:46 +0100 Subject: [PATCH 06/45] fix(cli): forward plan-gate entitlements and decode wait pointers in generated commands Generated commands now parse the Management API entitlement_required body on a 4xx, carry the entitlement in the standard error document, print the upgrade hint in text mode, and fire cli_upgrade_suggested. The generator decodes ~1 and ~0 in --wait link pointers the same way the runtime does. --- apps/cli/scripts/api-command-derive.ts | 10 ++- .../scripts/api-command-derive.unit.test.ts | 37 +++++++++++ .../command-errors/api-command.errors.ts | 2 + .../src/commands/api/api-command-execute.ts | 12 +++- .../api/api-commands.integration.test.ts | 65 +++++++++++++++++++ .../api/warehouse/enable/SIDE_EFFECTS.md | 2 + .../api/warehouse/status/SIDE_EFFECTS.md | 2 + .../cli/standard-errors.integration.test.ts | 29 +++++++++ apps/cli/src/shared/cli/standard-errors.ts | 20 ++++-- .../cli/tests/fixtures/standard-errors-cli.ts | 13 ++++ 10 files changed, 183 insertions(+), 9 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 95170f0ef2..6901a786b6 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -419,10 +419,16 @@ const findSecret = ( const schemaDescription = (spec: JsonObject, raw: unknown): string | undefined => asString(asRecord(resolve(spec, raw))?.description); +const pointerSegments = (pointer: string): ReadonlyArray => + pointer + .slice(1) + .split("/") + .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~")); + const resolvePointer = (spec: JsonObject, root: unknown, pointer: string): unknown => { if (!pointer.startsWith("/")) return undefined; let current = resolve(spec, root); - for (const segment of pointer.slice(1).split("/")) { + for (const segment of pointerSegments(pointer)) { const node = asRecord(current); if (node === undefined) return undefined; const property = asRecord(node.properties)?.[segment]; @@ -441,7 +447,7 @@ const resolvePointer = (spec: JsonObject, root: unknown, pointer: string): unkno const pointerAlwaysPresent = (spec: JsonObject, root: unknown, pointer: string): boolean => { if (!pointer.startsWith("/")) return false; let current = resolve(spec, root); - for (const segment of pointer.slice(1).split("/")) { + for (const segment of pointerSegments(pointer)) { const node = asRecord(current); const property = asRecord(node?.properties)?.[segment]; if (property === undefined || !asArray(node?.required).includes(segment)) return false; diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index c49152e662..9a9483859e 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -585,6 +585,43 @@ describe("deriveApiCommands", () => { expect(waitOf(result)?.read).toBe("get-thing"); }); + it("resolves escaped status and error pointers against property names", () => { + const escapedRead = { + type: "object", + properties: { + "a/b": { type: "string", enum: ["done", "broken"] }, + "c~d": { type: "string" }, + }, + }; + const result = derive({ + "create-thing": changeThing(link({ thing_id: "$response.body#/data/id" })), + "get-thing": readWith( + { ...poll, status: "/a~1b", error: "/c~0d" }, + jsonResponse(escapedRead), + ), + }); + + expect(result.problems).toEqual([]); + expect(waitOf(result)).toMatchObject({ status: "/a~1b", error: "/c~0d" }); + }); + + it("accepts a link parameter pointing at a required property with escaped characters", () => { + const escapedChange = { + type: "object", + required: ["a~/b"], + properties: { "a~/b": { type: "string" } }, + }; + const result = derive( + { + "create-thing": changeThing(link({ thing_id: "$response.body#/a~0~1b" }), escapedChange), + "get-thing": readThing, + }, + ["create-thing", "get-thing"], + ); + + expect(result.problems).toEqual([]); + }); + it("ignores a link whose target has no poll", () => { const result = derive({ "create-thing": changeThing(link({})), diff --git a/apps/cli/src/command-internal/command-errors/api-command.errors.ts b/apps/cli/src/command-internal/command-errors/api-command.errors.ts index 83daf29295..6970331079 100644 --- a/apps/cli/src/command-internal/command-errors/api-command.errors.ts +++ b/apps/cli/src/command-internal/command-errors/api-command.errors.ts @@ -1,5 +1,6 @@ import { Data } from "effect"; +import type { PlanGateEntitlement } from "../../shared/output/normalize-error.ts"; import { actionability, type CliErrorActionabilityDeclaration, @@ -13,6 +14,7 @@ export class ApiCommandStatusError extends Data.TaggedError("ApiCommandStatusErr readonly message: string; readonly apiCode?: string | undefined; readonly hint?: string | undefined; + readonly entitlement?: PlanGateEntitlement | undefined; }> { get [ErrorActionabilityId](): CliErrorActionabilityDeclaration { return statusCodeActionability(this.status, { notFoundIsInvalidInput: true }); diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index 47e9e32b69..573b6e06b4 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -6,7 +6,7 @@ import * as Headers from "effect/http/Headers"; import type * as HttpClientResponse from "effect/http/HttpClientResponse"; import { CommandPlatformApi } from "../../auth/command-platform-api.service.ts"; -import { sanitizeErrorBody } from "../../command-internal/http-errors.ts"; +import { parsePlanGateEnvelope, sanitizeErrorBody } from "../../command-internal/http-errors.ts"; import { encodeStructYaml, shapeAny } from "../../command-internal/struct-output.encoders.ts"; import { Output } from "../../shared/output/output.service.ts"; import { readPointer } from "./api-command-pointer.ts"; @@ -97,7 +97,10 @@ const statusError = Effect.fnUntraced(function* ( const text = textDecoder.decode( yield* readBytes(response).pipe(Effect.orElseSucceed(() => new Uint8Array())), ); - const fields = apiErrorFields(Option.getOrUndefined(decodeJsonText(text))); + const body = Option.getOrUndefined(decodeJsonText(text)); + const fields = apiErrorFields(body); + const entitlement = + response.status >= 400 && response.status < 500 ? parsePlanGateEnvelope(body) : undefined; return yield* new ApiCommandStatusError({ status: response.status, message: @@ -105,7 +108,10 @@ const statusError = Effect.fnUntraced(function* ( ? `Unexpected status ${response.status}` : sanitizeErrorBody(fields.message), apiCode: fields.apiCode, - hint: fields.hint ?? statusHint(operationId, response.status), + hint: + fields.hint ?? + (entitlement === undefined ? statusHint(operationId, response.status) : undefined), + ...(entitlement === undefined ? {} : { entitlement }), }); }); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index a5e6c8c5b0..a85859fc1a 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -37,6 +37,7 @@ import { import { describeHostedConsent } from "../../../tests/helpers/hosted-consent.ts"; import { fakeConsole, + mockAnalytics, mockOutput, mockRuntimeInfo, mockStdin, @@ -55,6 +56,8 @@ import { apiCommands } from "./generated.ts"; import { readApiCommand } from "./api-command.annotation.ts"; import { readCommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; import { apiCommandGroup, apiCommandGroups } from "./runtime.ts"; +import { standardFailureFor } from "../../shared/cli/standard-errors.ts"; +import { EventUpgradeSuggested } from "../../shared/telemetry/event-catalog.ts"; import { resolveWarehouseEnabled } from "./warehouse-backend.ts"; const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); @@ -206,6 +209,7 @@ interface CliOpts { readonly yes?: boolean; readonly route: Route; readonly root?: typeof warehouseRoot; + readonly analytics?: ReturnType; } /** @@ -229,6 +233,7 @@ const setup = (argv: ReadonlyArray, opts: CliOpts) => { buildTestRuntime({ out, api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), + ...(opts.analytics === undefined ? {} : { analytics: opts.analytics }), cliSettings: mockCommandSettings({ workdir: tempRoot.current }), tty: mockTty({ stdinIsTty: false, stdoutIsTty: false }), stdin: mockStdin(false), @@ -599,6 +604,66 @@ describe("generated warehouse commands", () => { }); }); + it.effect("reports a plan-gated 403 with its entitlement in the document and telemetry", () => { + const analytics = mockAnalytics(); + const planGate = { + error: { + code: "entitlement_required", + feature: "warehouse", + upgrade_url: "https://supabase.com/dashboard/org/acme/billing", + }, + }; + const { run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: () => ({ status: 403, body: planGate }), + analytics, + }); + return Effect.gen(function* () { + const exit = yield* Effect.exit(run); + expect(Exit.isFailure(exit) && standardFailureFor(exit.cause).document).toMatchObject({ + code: "forbidden", + status: 403, + hint: null, + entitlement: { + feature: "warehouse", + upgrade_url: "https://supabase.com/dashboard/org/acme/billing", + }, + }); + expect(analytics.captured.find((c) => c.event === EventUpgradeSuggested)).toMatchObject({ + properties: { feature_key: "warehouse", org_slug: "acme" }, + }); + }); + }); + + it.effect.each([ + { name: "a 403 without the plan-gate code", status: 403, body: { message: "Forbidden" } }, + { + name: "a 5xx carrying a plan-gate body", + status: 503, + body: { + error: { + code: "entitlement_required", + feature: "warehouse", + upgrade_url: "https://supabase.com/dashboard/org/acme/billing", + }, + }, + }, + ])("reports no entitlement for $name", ({ status, body }) => { + const analytics = mockAnalytics(); + const { run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: () => ({ status, body }), + analytics, + }); + return Effect.gen(function* () { + const exit = yield* Effect.exit(run); + expect(Exit.isFailure(exit) && standardFailureFor(exit.cause).document).not.toHaveProperty( + "entitlement", + ); + expect(analytics.captured.some((c) => c.event === EventUpgradeSuggested)).toBe(false); + }); + }); + it.effect("prints a JSON response as YAML of the parsed document under -o yaml", () => { const { out, run } = setup(["warehouse", "enable", "--schema", "public", "-o", "yaml"], { yes: true, diff --git a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md index a43abec59f..9e6134094b 100644 --- a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md @@ -51,6 +51,8 @@ before consent. | `1` | API error (non-2xx) | | `1` | with `--wait`: `operation_failed` (a failed status) or `wait_timeout` | +A 4xx `entitlement_required` body (`{"error":{"code":"entitlement_required","feature","upgrade_url"}}`) adds `entitlement: {feature, upgrade_url}` to the stderr error document in place of the token-permission hint; a terminal run prints the upgrade hint, and `cli_upgrade_suggested` fires. Other statuses and bodies carry no `entitlement` key. + ## Environment Variables | Variable | Purpose | Required? | diff --git a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md index 7c841c6676..9e64962c0d 100644 --- a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md @@ -52,6 +52,8 @@ with the API error. | `1` | API error (non-2xx, including 409) | | `1` | with `--wait`: `operation_failed` (a failed status, with `status_error`) or `wait_timeout` | +A 4xx `entitlement_required` body (`{"error":{"code":"entitlement_required","feature","upgrade_url"}}`) adds `entitlement: {feature, upgrade_url}` to the stderr error document in place of the token-permission hint; a terminal run prints the upgrade hint, and `cli_upgrade_suggested` fires. Other statuses and bodies carry no `entitlement` key. + ## Environment Variables | Variable | Purpose | Required? | diff --git a/apps/cli/src/shared/cli/standard-errors.integration.test.ts b/apps/cli/src/shared/cli/standard-errors.integration.test.ts index a4b4fadc94..aae8165a2b 100644 --- a/apps/cli/src/shared/cli/standard-errors.integration.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.integration.test.ts @@ -139,6 +139,35 @@ describe("errors.standard failure contract", () => { }).pipe(Effect.provide(BunServices.layer)), ); + it.live("a plan-gated denial carries its entitlement in the JSON document", () => + Effect.gen(function* () { + const { exitCode, stderr } = yield* runFixture(["plan-gated", "-o", "json"]); + expect(exitCode).toBe(1); + expect(yield* decodeJson(lastLine(stderr))).toEqual({ + code: "forbidden", + status: 403, + message: "Upgrade required", + hint: null, + entitlement: { + feature: "warehouse", + upgrade_url: "https://supabase.com/dashboard/org/acme/billing", + }, + }); + }).pipe(Effect.provide(BunServices.layer)), + ); + + it.live("a terminal run prints the upgrade hint for a plan-gated denial", () => + Effect.gen(function* () { + const { exitCode, stderr } = yield* runFixture(["plan-gated"], { + STANDARD_ERRORS_FIXTURE_TTY: "1", + }); + expect(exitCode).toBe(1); + expect(stderr).toContain("Upgrade required"); + expect(lastLine(stderr)).toContain("https://supabase.com/dashboard/org/acme/billing"); + expect(stderr).not.toContain('"code"'); + }).pipe(Effect.provide(BunServices.layer)), + ); + it.live("a terminal run prints the message and hint as text with the same exit code", () => Effect.gen(function* () { const { exitCode, stdout, stderr } = yield* runFixture(["conflict"], { diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index 86589a072c..890ed1b5f4 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -19,7 +19,11 @@ import { ApiCommandWaitTimeoutError, } from "../../command-internal/command-errors/api-command.errors.ts"; import { LinkBranchListStatusError } from "../../command-internal/target/branch-resolution.errors.ts"; -import { normalizeCause } from "../output/normalize-error.ts"; +import { + normalizeCause, + upgradeHint, + type PlanGateEntitlement, +} from "../output/normalize-error.ts"; import { writeStdio } from "../output/output.layer.ts"; import { classifyCliErrorActionability, @@ -58,6 +62,7 @@ interface StandardErrorDocument { readonly message: string; readonly hint: string | null; readonly api_code?: string; + readonly entitlement?: PlanGateEntitlement; readonly context?: Readonly>; } @@ -79,7 +84,11 @@ const EXIT_CANCELLED = 130; const documentForStatus = ( status: number, message: string, - extras: { readonly apiCode?: string | undefined; readonly hint?: string | undefined }, + extras: { + readonly apiCode?: string | undefined; + readonly hint?: string | undefined; + readonly entitlement?: PlanGateEntitlement | undefined; + }, ): StandardErrorDocument => { const code: StandardErrorCode = status === 400 || status === 422 @@ -101,6 +110,7 @@ const documentForStatus = ( message, hint: extras.hint ?? null, ...(extras.apiCode === undefined ? {} : { api_code: extras.apiCode }), + ...(extras.entitlement === undefined ? {} : { entitlement: extras.entitlement }), }; }; @@ -248,8 +258,10 @@ export const isMachineFailureMode = ( /** Renders the failure as the stderr text: a leading blank line plus JSON, or a human message and hint. */ const renderStandardFailure = (pending: PendingStandardFailure): string => { if (pending.machine) return `\n${JSON.stringify(pending.document)}\n`; - const { message, hint } = pending.document; - return `${styleText("red", message)}\n${hint === null ? "" : `${hint}\n`}`; + const { message, hint, entitlement } = pending.document; + return `${styleText("red", message)}\n${hint === null ? "" : `${hint}\n`}${ + entitlement === undefined ? "" : `${upgradeHint(entitlement.upgrade_url)}\n` + }`; }; /** Writes the pending failure to stderr; a closed or failing stderr never changes the exit code. */ diff --git a/apps/cli/tests/fixtures/standard-errors-cli.ts b/apps/cli/tests/fixtures/standard-errors-cli.ts index 746973d93c..8a2cea6c7e 100644 --- a/apps/cli/tests/fixtures/standard-errors-cli.ts +++ b/apps/cli/tests/fixtures/standard-errors-cli.ts @@ -30,6 +30,19 @@ const root = Command.make("supabase").pipe( }), ), ), + standard( + "plan-gated", + Effect.fail( + new ApiCommandStatusError({ + status: 403, + message: "Upgrade required", + entitlement: { + feature: "warehouse", + upgrade_url: "https://supabase.com/dashboard/org/acme/billing", + }, + }), + ), + ), standard( "needs-consent", Effect.fail( From 4ae9f6a894ebd551195d3021368cc34f39faccae Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Tue, 17 Nov 2026 10:16:59 +0100 Subject: [PATCH 07/45] feat(cli): render generated command results as text in a terminal --- .../src/commands/api/api-command-execute.ts | 40 ++- .../src/commands/api/api-command.format.ts | 189 +++++++++++++ .../api/api-command.format.unit.test.ts | 36 +++ .../src/commands/api/api-commands.e2e.test.ts | 25 ++ .../api/api-commands.integration.test.ts | 262 +++++++++++++++++- apps/cli/src/commands/api/runtime.ts | 98 +++++-- .../api/warehouse/enable/SIDE_EFFECTS.md | 23 +- .../api/warehouse/status/SIDE_EFFECTS.md | 23 +- apps/cli/src/shared/cli/agent-output.ts | 5 + apps/cli/tests/helpers/mocks.ts | 10 +- 10 files changed, 668 insertions(+), 43 deletions(-) create mode 100644 apps/cli/src/commands/api/api-command.format.ts create mode 100644 apps/cli/src/commands/api/api-command.format.unit.test.ts diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index 573b6e06b4..439540aa07 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -10,7 +10,8 @@ import { parsePlanGateEnvelope, sanitizeErrorBody } from "../../command-internal import { encodeStructYaml, shapeAny } from "../../command-internal/struct-output.encoders.ts"; import { Output } from "../../shared/output/output.service.ts"; import { readPointer } from "./api-command-pointer.ts"; -import { decodeInput, definitionOf } from "./api-command-request.ts"; +import { decodeInput, definitionOf, type ApiRequestPreview } from "./api-command-request.ts"; +import { renderDryRunText, renderResponseText } from "./api-command.format.ts"; import { ApiCommandOperationFailedError, ApiCommandStatusError, @@ -26,17 +27,32 @@ const decodeJsonText = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.U const textDecoder = new TextDecoder(); const encodeJsonValue = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); -/** How a generated command prints its result: the API's JSON untouched, or the same document as YAML. */ -export type ApiOutputFormat = "json" | "yaml"; +/** + * How a generated command prints its result: the API's JSON untouched, the same document as + * YAML, or a human-readable rendering. + */ +export type ApiOutputFormat = "text" | "json" | "yaml"; + +type ApiDocumentFormat = Exclude; /** Writes `value` as one document in `format`. */ -export const writeDocument = Effect.fnUntraced(function* (value: unknown, format: ApiOutputFormat) { +const writeDocument = Effect.fnUntraced(function* (value: unknown, format: ApiDocumentFormat) { const output = yield* Output; return yield* output.raw( format === "yaml" ? encodeStructYaml(value, shapeAny) : `${encodeJsonValue(value)}\n`, ); }); +/** Writes the request a dry run would send, as text or as a document. */ +export const writeDryRun = Effect.fnUntraced(function* ( + preview: ApiRequestPreview, + format: ApiOutputFormat, +) { + if (format !== "text") return yield* writeDocument(preview, format); + const output = yield* Output; + return yield* output.raw(renderDryRunText(preview)); +}); + const stringField = (source: unknown, key: string): string | undefined => { if (!Predicate.isObject(source)) return undefined; const value: unknown = Reflect.get(source, key); @@ -148,7 +164,8 @@ const parseResponse = (response: ApiCommandResponse): unknown => /** * Writes a success response. `json` passes JSON bytes through untouched, prints text as a JSON - * string and an empty body as `null`; `yaml` encodes that same document. + * string and an empty body as `null`; `yaml` encodes that same document; `text` renders it for a + * person. */ export const writeApiResponse = Effect.fnUntraced(function* ( entry: ApiCommandEntry, @@ -157,6 +174,13 @@ export const writeApiResponse = Effect.fnUntraced(function* ( ) { const hasBody = response.bytes.length > 0; const text = textDecoder.decode(response.bytes); + if (format === "text") { + const output = yield* Output; + if (!hasBody || entry.response.kind === "empty") return yield* output.raw("Done.\n"); + const parsed = entry.response.kind === "json" ? decodeJsonText(text) : Option.none(); + if (Option.isNone(parsed)) return yield* output.raw(text.endsWith("\n") ? text : `${text}\n`); + return yield* output.raw(renderResponseText(parsed.value)); + } if (format === "json" && entry.response.kind === "json" && hasBody) { const output = yield* Output; return yield* output.rawBytes(response.bytes); @@ -178,6 +202,8 @@ interface WaitInput { readonly readInput: Readonly>; readonly ref: string; readonly timeoutMillis: number; + /** Called after each successful poll with the status it read. */ + readonly onPoll?: (status: string | undefined) => Effect.Effect; } export interface PollOutcome { @@ -292,6 +318,10 @@ export const waitForOperation = Effect.fn("api-command.wait")(function* (input: const poll = Ref.update(attempts, (count) => count + 1).pipe( Effect.andThen(sendApiRequest(readEntry, decoded)), Effect.flatMap((response) => classify(wait, response, hint)), + Effect.tap(({ response }) => { + const status = readPointer(parseResponse(response), wait.status); + return input.onPoll?.(typeof status === "string" ? status : undefined) ?? Effect.void; + }), Effect.withTracerEnabled(false), ); diff --git a/apps/cli/src/commands/api/api-command.format.ts b/apps/cli/src/commands/api/api-command.format.ts new file mode 100644 index 0000000000..a877488dce --- /dev/null +++ b/apps/cli/src/commands/api/api-command.format.ts @@ -0,0 +1,189 @@ +import { renderGlamourTable } from "../../output/glamour-table.ts"; +import type { ApiRequestPreview } from "./api-command-request.ts"; + +const INDENT = " "; +const ACRONYMS: ReadonlySet = new Set(["id", "url", "fdw", "dns", "api", "sql"]); + +type JsonObject = Readonly>; + +const isObject = (value: unknown): value is JsonObject => + typeof value === "object" && value !== null && !Array.isArray(value); + +const isScalar = (value: unknown): boolean => value === null || typeof value !== "object"; + +const CONTROL_ESCAPES: Readonly> = { + "\r": "\\r", + "\n": "\\n", + "\t": "\\t", +}; + +/** Keeps a value on one line by escaping line breaks, tabs and other control characters. */ +const singleLine = (text: string): string => + text.replace( + // oxlint-disable-next-line no-control-regex -- escaping control characters is the purpose + /[\u0000-\u001f\u007f]/gu, + (char) => CONTROL_ESCAPES[char] ?? `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`, + ); + +const compactJson = (value: unknown): string => singleLine(JSON.stringify(value) ?? "null"); + +/** `snake_case` becomes a sentence-case label; known acronyms stay upper-case. */ +const humanize = (key: string): string => + singleLine(key) + .split("_") + .filter((word) => word !== "") + .map((word, index) => { + const lower = word.toLowerCase(); + if (ACRONYMS.has(lower)) return lower.toUpperCase(); + return index === 0 ? `${lower.charAt(0).toUpperCase()}${lower.slice(1)}` : lower; + }) + .join(" "); + +const scalarText = (value: unknown): string => { + if (value === null || value === undefined) return "-"; + if (typeof value === "boolean") return value ? "yes" : "no"; + if (typeof value === "string") return value === "" ? "-" : singleLine(value); + return singleLine(String(value)); +}; + +const cellText = (value: unknown): string => + isScalar(value) || value === undefined ? scalarText(value) : compactJson(value); + +const isObjectArray = (value: unknown): value is ReadonlyArray => + Array.isArray(value) && value.length > 0 && value.every(isObject); + +/** A table indented under its label; the table's own blank framing lines are dropped. */ +const tableLines = ( + headers: ReadonlyArray, + rows: ReadonlyArray>, + indent: string, +): ReadonlyArray => + renderGlamourTable(headers, rows) + .split("\n") + .filter((line) => line.trim() !== "") + .map((line) => `${indent}${line}`); + +const objectTable = ( + items: ReadonlyArray, + columns: ReadonlyArray, + indent: string, +): ReadonlyArray => + tableLines( + columns.map((column) => humanize(column).toUpperCase()), + items.map((item) => columns.map((column) => cellText(item[column]))), + indent, + ); + +const unionKeys = (items: ReadonlyArray): ReadonlyArray => { + const seen = new Set(); + for (const item of items) for (const key of Object.keys(item)) seen.add(key); + return [...seen]; +}; + +/** The inline text of a value that fits on one line, or `undefined` when it needs its own block. */ +const inlineText = (value: unknown): string | undefined => { + if (isScalar(value) || value === undefined) return scalarText(value); + if (Array.isArray(value)) { + if (value.length === 0) return "-"; + if (value.every(isScalar)) return value.map(scalarText).join(", "); + return isObjectArray(value) ? undefined : compactJson(value); + } + return isObject(value) && Object.keys(value).length > 0 ? undefined : "-"; +}; + +const blockLines = (entries: ReadonlyArray, indent: string) => { + const rows = entries.map(([key, value]) => ({ + label: humanize(key), + value, + inline: inlineText(value), + })); + const width = Math.max( + 0, + ...rows.flatMap((row) => (row.inline === undefined ? [] : [row.label.length])), + ); + const lines: Array = []; + for (const { label, value, inline } of rows) { + if (inline !== undefined) { + lines.push(`${indent}${label.padEnd(width)}${INDENT}${inline}`); + continue; + } + lines.push(`${indent}${label}`); + if (isObjectArray(value)) { + lines.push(...objectTable(value, unionKeys(value), indent)); + } else if (isObject(value)) { + lines.push(...blockLines(Object.entries(value), `${indent}${INDENT}`)); + } + } + return lines; +}; + +const isResource = (value: unknown): value is JsonObject & { readonly attributes: JsonObject } => + isObject(value) && typeof value["type"] === "string" && isObject(value["attributes"]); + +const resourceEntries = (resource: JsonObject & { readonly attributes: JsonObject }) => { + const id = resource["id"]; + return [ + ...(id === undefined || id === null ? [] : ([["id", id]] as const)), + ...Object.entries(resource.attributes), + ]; +}; + +const resourceLines = (document: JsonObject): ReadonlyArray | undefined => { + const keys = Object.keys(document); + const data = document["data"]; + if (keys.length !== 1 || keys[0] !== "data") return undefined; + if (isResource(data)) { + return [humanize(String(data["type"])), ...blockLines(resourceEntries(data), INDENT)]; + } + if (Array.isArray(data) && data.length > 0 && data.every(isResource)) { + const rows = data.map((resource) => Object.fromEntries(resourceEntries(resource))); + const columns = unionKeys(rows).filter((column) => + rows.some((row) => isScalar(row[column]) && row[column] !== undefined), + ); + return [humanize(String(data[0]?.["type"])), ...objectTable(rows, columns, "")]; + } + return undefined; +}; + +/** Renders a decoded JSON response as the text a person reads; always ends with a newline. */ +export const renderResponseText = (value: unknown): string => { + if (isObject(value)) { + const lines = resourceLines(value) ?? blockLines(Object.entries(value), ""); + return `${(lines.length === 0 ? ["-"] : lines).join("\n")}\n`; + } + if (isObjectArray(value)) { + return `${objectTable(value, unionKeys(value), "").join("\n")}\n`; + } + return `${inlineText(value) ?? compactJson(value)}\n`; +}; + +const rawBlock = (title: string, values: Readonly>) => { + const entries = Object.entries(values); + if (entries.length === 0) return []; + const width = Math.max(...entries.map(([key]) => key.length)); + return [ + title, + ...entries.map( + ([key, value]) => `${INDENT}${singleLine(key).padEnd(width)}${INDENT}${cellText(value)}`, + ), + ]; +}; + +/** Renders the request a dry run would send: a summary line, query and headers, then the body. */ +export const renderDryRunText = (preview: ApiRequestPreview): string => { + const body = + preview.body === null || preview.body === undefined + ? [] + : [ + "Body", + ...JSON.stringify(preview.body, null, 2) + .split("\n") + .map((line) => `${INDENT}${line}`), + ]; + return `${[ + `Dry run: ${singleLine(preview.method)} ${singleLine(preview.path)}`, + ...rawBlock("Query", preview.query), + ...rawBlock("Headers", preview.headers), + ...body, + ].join("\n")}\n`; +}; diff --git a/apps/cli/src/commands/api/api-command.format.unit.test.ts b/apps/cli/src/commands/api/api-command.format.unit.test.ts new file mode 100644 index 0000000000..60621a4a4e --- /dev/null +++ b/apps/cli/src/commands/api/api-command.format.unit.test.ts @@ -0,0 +1,36 @@ +import { describe, expect, it } from "@effect/vitest"; +import { renderResponseText } from "./api-command.format.ts"; + +describe("renderResponseText", () => { + it("keeps known acronyms upper-case in labels", () => { + expect(renderResponseText({ project_id: "p", base_url: "u", fdw_name: "f", name: "n" })).toBe( + ["Project ID p", "Base URL u", "FDW name f", "Name n", ""].join("\n"), + ); + }); + + it("escapes line breaks and control characters so every value stays on one line", () => { + expect(renderResponseText({ message: "a\nb\tc\u0001d" })).toBe("Message a\\nb\\tc\\u0001d\n"); + }); + + it("escapes control characters in keys so labels stay on one line", () => { + expect(renderResponseText({ "a\nb\u001bc": 1 })).toBe("A\\nb\\u001bc 1\n"); + }); + + it("prints a dash for null and empty strings, arrays and objects", () => { + expect(renderResponseText({ owner: null, note: "", tags: [], limits: {} })).toBe( + ["Owner -", "Note -", "Tags -", "Limits -", ""].join("\n"), + ); + }); + + it("joins arrays of scalars with commas", () => { + expect(renderResponseText({ regions: ["eu", "us"], flags: [true, false] })).toBe( + ["Regions eu, us", "Flags yes, no", ""].join("\n"), + ); + }); + + it("indents nested objects under their label", () => { + expect(renderResponseText({ name: "n", limits: { max: 1, nested: { deep: true } } })).toBe( + ["Name n", "Limits", " Max 1", " Nested", " Deep yes", ""].join("\n"), + ); + }); +}); diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index 6d344c6780..83f1247dfe 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -130,6 +130,31 @@ it.live("warehouse status reports a 409 as a conflict failure document on stderr }).pipe(Effect.provide(BunServices.layer)), ); +it.live("warehouse status keeps the API bytes when stdout is piped", () => + Effect.gen(function* () { + const { result } = yield* runWarehouse(["status"], () => statusBody("succeeded")); + + requireCliSuccess(result, "warehouse status"); + expect(result.stdout, result.stderr).toBe(statusBody("succeeded").body); + }).pipe(Effect.provide(BunServices.layer)), +); + +it.live("warehouse status --output-format text renders the response for people", () => + Effect.gen(function* () { + const { result } = yield* runWarehouse(["status", "--output-format", "text"], () => + statusBody("succeeded"), + ); + + requireCliSuccess(result, "warehouse status --output-format text"); + expect(result.exitCode, result.stderr).toBe(0); + expect( + result.stdout.endsWith( + `Warehouse setup\n Selection ID ${SEL}\n Status succeeded\n`, + ), + ).toBe(true); + }).pipe(Effect.provide(BunServices.layer)), +); + it.live("warehouse enable without --yes refuses to run when stdin is piped", () => Effect.gen(function* () { const { result, requests } = yield* runWarehouse( diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index a85859fc1a..4418cc1f3c 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -19,11 +19,12 @@ import * as TestClock from "effect/testing/TestClock"; import { respondToComplete } from "../../cli/complete.ts"; import { rootCommandForFeatures } from "../../cli/root.ts"; -import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; +import { ExperimentalFlag, ROOT_GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; import { HostedMutationConsentRequiredError } from "../../command-internal/hosted-consent/hosted-consent.errors.ts"; import { InvalidOutputFormatError } from "../../command-internal/output-formats.ts"; import { ExperimentalFeatureFlagError } from "../../shared/config/experimental-feature.ts"; import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; +import type { OutputFormat } from "../../shared/output/types.ts"; import { commandTreeFor } from "../../../tests/helpers/command-flags.ts"; import { VALID_REF, @@ -97,6 +98,52 @@ const statusBody = (state: string, statusError?: string) => ({ }, }); +const RICH_STATUS = { + data: { + type: "warehouse_setup", + id: SEL, + attributes: { + dns: { hostname: "wh.example.test", region: "us-east-1", status: "active" }, + delete_data: false, + setup_status: "ready", + pipeline_id: 42, + steps: [ + { name: "create_pipeline", status: "succeeded" }, + { name: "import_foreign_schema", status: "failed", message: "line one\nline two" }, + ], + tables: [ + { + schema: "public", + name: "orders", + state: "synced", + lag_ms: 120, + last_synced_at: "2026-01-01T00:00:00Z", + copy_name: '"public"."orders"', + replication_state: "streaming", + }, + { + schema: "public", + name: "users", + state: "copying", + copy_name: '"public"."users"', + warehouse_size_bytes: 2048, + replication_state: "copying", + }, + ], + fdw_status: { + extension_available: true, + extension_installed: true, + wrapper_installed: false, + server_configured: false, + schema_created: false, + foreign_schema_imported: false, + }, + status: "succeeded", + replication_state: "streaming", + }, + }, +}; + /** One request the CLI sent to the stubbed Management API. */ interface Sent { readonly method: string; @@ -189,7 +236,7 @@ const withApi = (route: Route, sent: Array) => { const warehouseRoot = Command.make("supabase").pipe( Command.withSubcommands(apiCommandGroups(["warehouse"])), - Command.withGlobalFlags(GLOBAL_FLAGS), + Command.withGlobalFlags(ROOT_GLOBAL_FLAGS), ); const tempRoot = useTempWorkdir("supabase-api-commands-int-"); @@ -210,6 +257,10 @@ interface CliOpts { readonly route: Route; readonly root?: typeof warehouseRoot; readonly analytics?: ReturnType; + /** The Output layer's resolved format; defaults to `text`. */ + readonly outputFormat?: OutputFormat; + /** Whether stdout is a terminal; defaults to a pipe. */ + readonly stdoutIsTty?: boolean; } /** @@ -227,7 +278,7 @@ const execute = (argv: ReadonlyArray, opts: CliOpts) => { }; const setup = (argv: ReadonlyArray, opts: CliOpts) => { - const out = mockOutput({ format: "text" }); + const out = mockOutput({ format: opts.outputFormat ?? "text" }); const { args, sent, run } = execute(argv, opts); const layer = Layer.mergeAll( buildTestRuntime({ @@ -235,7 +286,7 @@ const setup = (argv: ReadonlyArray, opts: CliOpts) => { api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), ...(opts.analytics === undefined ? {} : { analytics: opts.analytics }), cliSettings: mockCommandSettings({ workdir: tempRoot.current }), - tty: mockTty({ stdinIsTty: false, stdoutIsTty: false }), + tty: mockTty({ stdinIsTty: false, stdoutIsTty: opts.stdoutIsTty ?? false }), stdin: mockStdin(false), cliArgs: args, }), @@ -247,6 +298,9 @@ const setup = (argv: ReadonlyArray, opts: CliOpts) => { const failureOf = (exit: Exit.Exit): unknown => Exit.isFailure(exit) ? Exit.findErrorOption(exit).pipe(Option.getOrUndefined) : undefined; +const driveClock = (fiber: Fiber.Fiber) => + Effect.raceFirst(Effect.forever(TestClock.adjust("2 seconds")), Fiber.await(fiber)); + const bodiesOf = (sent: ReadonlyArray) => sent.map((request) => request.body); describe("generated warehouse commands", () => { @@ -712,9 +766,6 @@ describe("generated warehouse commands", () => { }); describe("--wait", () => { - const driveClock = (fiber: Fiber.Fiber) => - Effect.raceFirst(Effect.forever(TestClock.adjust("2 seconds")), Fiber.await(fiber)); - it.effect("polls the read operation until the setup succeeds and prints its response", () => { const { sent, out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { yes: true, @@ -974,6 +1025,201 @@ describe("generated warehouse commands", () => { }); }); + describe("text output", () => { + const STATUS_TEXT = + [ + "Warehouse setup", + ` ID ${SEL}`, + " DNS", + " Hostname wh.example.test", + " Region us-east-1", + " Status active", + " Delete data no", + " Setup status ready", + " Pipeline ID 42", + " Steps", + " NAME | STATUS | MESSAGE ", + " -----------------------|-----------|--------------------", + " create_pipeline | succeeded | - ", + " import_foreign_schema | failed | line one\\nline two ", + " Tables", + " SCHEMA | NAME | STATE | LAG MS | LAST SYNCED AT | COPY NAME | REPLICATION STATE | WAREHOUSE SIZE BYTES ", + " --------|--------|---------|--------|----------------------|-------------------|-------------------|----------------------", + ' public | orders | synced | 120 | 2026-01-01T00:00:00Z | "public"."orders" | streaming | - ', + ' public | users | copying | - | - | "public"."users" | copying | 2048 ', + " FDW status", + " Extension available yes", + " Extension installed yes", + " Wrapper installed no", + " Server configured no", + " Schema created no", + " Foreign schema imported no", + " Status succeeded", + " Replication state streaming", + ].join("\n") + "\n"; + + it.effect("renders the status as text on a terminal by default", () => { + const { out, run } = setup(["warehouse", "status"], { + route: ok(RICH_STATUS), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(STATUS_TEXT); + }); + }); + + it.effect("keeps the API bytes by default when stdout is piped", () => { + const { out, run } = setup(["warehouse", "status"], { route: ok(RICH_STATUS) }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(encodeJson(RICH_STATUS)); + }); + }); + + it.effect("renders text through a pipe when --output-format text is explicit", () => { + const { out, run } = setup(["warehouse", "status", "--output-format", "text"], { + route: ok(RICH_STATUS), + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(STATUS_TEXT); + }); + }); + + it.effect( + "prints only the text rendering for -o pretty under --output-format stream-json", + () => { + const { out, run } = setup( + ["warehouse", "status", "-o", "pretty", "--output-format", "stream-json"], + { route: ok(RICH_STATUS), outputFormat: "stream-json", stdoutIsTty: true }, + ); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(STATUS_TEXT); + expect(out.progressEvents).toEqual([]); + }); + }, + ); + + it.effect("keeps the API bytes for -o json on a terminal", () => { + const { out, run } = setup(["warehouse", "status", "-o", "json"], { + route: ok(RICH_STATUS), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(encodeJson(RICH_STATUS)); + }); + }); + + it.effect("shows the request as one task that is cleared when it succeeds", () => { + const { out, run } = setup(["warehouse", "status"], { + route: ok(RICH_STATUS), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(out.progressEvents).toEqual([ + { type: "start", message: "Get Warehouse initial synchronization status" }, + ]); + expect(out.taskSettlements).toEqual([{ type: "clear" }]); + }); + }); + + it.effect("prints the final status as text and tracks the wait in one polling task", () => { + const { out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + stdoutIsTty: true, + route: enableThenPoll([ + { status: 200, body: statusBody("pending") }, + { status: 200, body: statusBody("succeeded") }, + ]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + yield* Fiber.join(fiber); + expect(out.stdoutText).toBe( + ["Warehouse setup", ` Selection ID ${SEL}`, " Status succeeded", ""].join("\n"), + ); + const polling = "Get Warehouse initial synchronization status"; + expect(out.progressEvents).toEqual([ + { type: "start", message: "Enable Warehouse replication" }, + { type: "start", message: polling }, + { type: "message", message: `${polling} (status: pending)` }, + { type: "message", message: `${polling} (status: succeeded)` }, + ]); + expect(out.taskSettlements).toEqual([{ type: "clear" }, { type: "clear" }]); + }); + }); + + it.effect("fails the polling task and keeps the standard error when the setup fails", () => { + const { out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + stdoutIsTty: true, + route: enableThenPoll([{ status: 200, body: statusBody("failed", "pipeline crashed") }]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + const failure = yield* Fiber.join(fiber); + expect(failure).toBeInstanceOf(ApiCommandOperationFailedError); + expect(failure).toMatchObject({ message: expect.stringContaining("pipeline crashed") }); + expect(out.stdoutText).toBe(""); + expect(out.taskSettlements).toEqual([{ type: "clear" }, { type: "fail" }]); + }); + }); + + it.effect("cancels the polling task when the run is interrupted mid-wait", () => { + const { out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + stdoutIsTty: true, + route: enableThenPoll([{ status: 200, body: statusBody("pending") }]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); + yield* TestClock.adjust("2 seconds").pipe( + Effect.andThen(Effect.yieldNow), + Effect.repeat({ until: () => out.progressEvents.some((e) => e.type === "message") }), + ); + yield* Fiber.interrupt(fiber); + expect(out.stdoutText).toBe(""); + expect(out.taskSettlements).toEqual([{ type: "clear" }, { type: "cancel" }]); + }); + }); + + it.effect("prints the dry run as text with its query values", () => { + const { out, sent, run } = setup( + [ + "warehouse", + "status", + "--inspect-fdw", + "false", + "--selection-id", + SEL, + "--dry-run", + "--output-format", + "text", + ], + { route: ok({}) }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([]); + expect(out.stdoutText).toBe( + [ + `Dry run: GET ${STATUS_PATH}`, + "Query", + " inspect_fdw false", + ` selection_id ${SEL}`, + "", + ].join("\n"), + ); + }); + }); + }); + describe("generic response writing", () => { const fixture: ApiCommandEntry = { ...status, @@ -986,7 +1232,7 @@ describe("generated warehouse commands", () => { entry, ]), ]), - Command.withGlobalFlags(GLOBAL_FLAGS), + Command.withGlobalFlags(ROOT_GLOBAL_FLAGS), ); it.effect.each([ diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 3226d5e763..536468aaa2 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -1,4 +1,4 @@ -import { Effect, Layer, Option } from "effect"; +import { Cause, Effect, Exit, Layer, Option } from "effect"; import { Argument, Command, Flag } from "effect/cli"; import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; @@ -18,7 +18,12 @@ import { resolveProjectTarget } from "../../command-internal/target/resolve-proj import { projectTargetFlags } from "../../command-internal/target/target-flags.ts"; import { withTargetPolicy } from "../../command-internal/target/target-policy.ts"; import { projectRefPicker } from "../../config/project-ref.layer.ts"; +import { CliArgs } from "../../shared/cli/cli-args.service.ts"; +import { readExplicitOutputFormat } from "../../shared/cli/agent-output.ts"; +import { Output } from "../../shared/output/output.service.ts"; +import type { OutputFormat } from "../../shared/output/types.ts"; import { stdinLayer } from "../../shared/runtime/stdin.layer.ts"; +import { Tty } from "../../shared/runtime/tty.service.ts"; import { withCommandTelemetry } from "../../telemetry/command-telemetry.ts"; import { LinkedProjectCache } from "../../telemetry/linked-project-cache.service.ts"; import { linkedProjectCache } from "../../telemetry/linked-project-cache.layer.ts"; @@ -29,7 +34,7 @@ import { sendApiRequest, waitForOperation, writeApiResponse, - writeDocument, + writeDryRun, } from "./api-command-execute.ts"; import { type ApiFlagLocation, apiFlag } from "./api-command-flags.ts"; import { type ApiNoun, nouns } from "./api-command-policy.ts"; @@ -140,9 +145,52 @@ const parseTimeoutMillis = (value: string) => ), ); -const consentAction = (entry: ApiCommandEntry): string => entry.summary.replace(/\.$/, ""); +const summaryText = (entry: ApiCommandEntry): string => entry.summary.replace(/\.$/, ""); -const OUTPUT_FORMATS: ReadonlyArray = ["json", "yaml"]; +const OUTPUT_FORMATS: ReadonlyArray = ["json", "yaml", "pretty"]; + +/** + * How the result prints: `-o` decides first, then an explicit `--output-format`, then text only + * for a text-mode run on a terminal; everything else keeps the API's JSON. + */ +const presentationOf = (input: { + readonly outputFlag: Option.Option; + readonly args: ReadonlyArray; + readonly outputFormat: OutputFormat; + readonly stdoutIsTty: boolean; +}): ApiOutputFormat => { + const flag = Option.getOrUndefined(input.outputFlag); + if (flag === "yaml") return "yaml"; + if (flag === "json") return "json"; + if (flag === "pretty") return "text"; + const explicit = readExplicitOutputFormat(input.args); + if (Option.isSome(explicit)) return explicit.value === "text" ? "text" : "json"; + return input.outputFormat === "text" && input.stdoutIsTty ? "text" : "json"; +}; + +/** + * Runs `use` under a progress task when `visible`, handing it the task's message updater; the + * task is cleared on success and marked failed or cancelled otherwise. + */ +const withTask = ( + visible: boolean, + message: string, + use: (update: (message: string) => Effect.Effect) => Effect.Effect, +) => + Effect.gen(function* () { + if (!visible) return yield* use(() => Effect.void); + const output = yield* Output; + const task = yield* output.task(message); + return yield* use(task.message).pipe( + Effect.onExit((exit) => + Exit.isSuccess(exit) + ? task.clear + : Cause.hasInterruptsOnly(exit.cause) + ? task.cancel() + : task.fail(), + ), + ); + }); /** The parsed flags of a generated command. */ interface ApiCommandFlags { @@ -166,8 +214,15 @@ const handle = Effect.fn("api-command.run")(function* ( yield* Effect.annotateCurrentSpan("operation.id", entry.operationId); const telemetryState = yield* TelemetryState; const cache = yield* LinkedProjectCache; - const outputFlag = yield* OutputFlag; - const format: ApiOutputFormat = Option.getOrUndefined(outputFlag) === "yaml" ? "yaml" : "json"; + const output = yield* Output; + const format = presentationOf({ + outputFlag: yield* OutputFlag, + args: (yield* CliArgs).args, + outputFormat: output.format, + stdoutIsTty: (yield* Tty).stdoutIsTty, + }); + const progress = format === "text" && output.format === "text"; + yield* Effect.annotateCurrentSpan("output.presentation", format); yield* Effect.gen(function* () { const ref = yield* resolveProjectTarget(flags); yield* Effect.gen(function* () { @@ -184,10 +239,10 @@ const handle = Effect.fn("api-command.run")(function* ( if (flags.dryRun) { yield* Effect.annotateCurrentSpan("run.outcome", "dry_run"); - return yield* writeDocument(previewRequest(entry, decoded), format); + return yield* writeDryRun(previewRequest(entry, decoded), format); } if (!entry.readOnly) { - yield* requireHostedMutationConsent({ action: consentAction(entry) }); + yield* requireHostedMutationConsent({ action: summaryText(entry) }); } if (waiting) { @@ -199,19 +254,28 @@ const handle = Effect.fn("api-command.run")(function* ( wait: resolved.wait, changedOperationId: entry.operationId, ref, - changed: yield* sendApiRequest(entry, decoded), + changed: yield* withTask(progress, summaryText(entry), () => + sendApiRequest(entry, decoded), + ), }); - const settled = yield* waitForOperation({ - wait: resolved.wait, - readEntry: resolved.readEntry, - readInput, - ref, - timeoutMillis, - }); + const polling = summaryText(resolved.readEntry); + const settled = yield* withTask(progress, polling, (update) => + waitForOperation({ + wait: resolved.wait, + readEntry: resolved.readEntry, + readInput, + ref, + timeoutMillis, + onPoll: (status) => + update(status === undefined ? polling : `${polling} (status: ${status})`), + }), + ); yield* Effect.annotateCurrentSpan("run.outcome", "waited"); return yield* writeApiResponse(resolved.readEntry, settled, format); } - const response = yield* sendApiRequest(entry, decoded); + const response = yield* withTask(progress, summaryText(entry), () => + sendApiRequest(entry, decoded), + ); yield* Effect.annotateCurrentSpan("run.outcome", "sent"); return yield* writeApiResponse(entry, response, format); }).pipe(Effect.ensuring(cache.cache(ref))); diff --git a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md index 9e6134094b..4d6362adee 100644 --- a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md @@ -76,12 +76,23 @@ and `--wait` record `true`. Generated field flags, `--body`, `--file` and `--tim ## Output -| Mode | stdout | -| -------------- | --------------------------------------------------------------------------------- | -| text (default) | the API's JSON response bytes, unchanged; with `--wait` the final status response | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML; other `-o` values are a usage error | -| `--dry-run` | the request preview as JSON | +Text rendering applies on a terminal by default, with `--output-format text` (also when piped), and +with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the +API's JSON bytes. `-o` takes precedence over `--output-format`. + +| Mode | stdout | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | +| text presentation | the response as labelled fields and tables; with `--wait` the final status response; an empty response prints `Done.` | +| JSON presentation | the API's JSON response bytes, unchanged; with `--wait` the final status response | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | +| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | +| `--dry-run` otherwise | the request preview as JSON | + +When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the +whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it +is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task +message prints as a step line on stdout before the response. JSON and YAML output show no progress. ## Notes diff --git a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md index 9e64962c0d..1d5088c3a1 100644 --- a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md @@ -77,9 +77,20 @@ are recorded as ``. ## Output -| Mode | stdout | -| -------------- | --------------------------------------------------------------------- | -| text (default) | the API's JSON response bytes, unchanged; with `--wait` the last read | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML | -| `--dry-run` | the request preview as JSON | +Text rendering applies on a terminal by default, with `--output-format text` (also when piped), and +with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the +API's JSON bytes. `-o` takes precedence over `--output-format`. + +| Mode | stdout | +| ------------------------------ | --------------------------------------------------------------------------------------------------------- | +| text presentation | the response as labelled fields and tables; with `--wait` the last read; an empty response prints `Done.` | +| JSON presentation | the API's JSON response bytes, unchanged; with `--wait` the last read | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML | +| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | +| `--dry-run` otherwise | the request preview as JSON | + +When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the +whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it +is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task +message prints as a step line on stdout before the response. JSON and YAML output show no progress. diff --git a/apps/cli/src/shared/cli/agent-output.ts b/apps/cli/src/shared/cli/agent-output.ts index 0807730cbf..0b6ae41155 100644 --- a/apps/cli/src/shared/cli/agent-output.ts +++ b/apps/cli/src/shared/cli/agent-output.ts @@ -65,6 +65,11 @@ function outputFormatFromArg(value: string | undefined): Option.Option): Option.Option { + return outputFormatFromArg(readLongFlag(args, "--output-format")); +} + function outputFlagFormatFromArg(value: string | undefined): Option.Option { switch (value) { case "env": diff --git a/apps/cli/tests/helpers/mocks.ts b/apps/cli/tests/helpers/mocks.ts index 911c045fe8..7f11e95c04 100644 --- a/apps/cli/tests/helpers/mocks.ts +++ b/apps/cli/tests/helpers/mocks.ts @@ -228,6 +228,8 @@ export function mockProcessControl( }; } +const optionalMessage = (message: string | undefined) => (message === undefined ? {} : { message }); + export function mockOutput( opts: { format?: OutputFormat; @@ -245,6 +247,7 @@ export function mockOutput( const messages: OutputMessage[] = []; const failures: Array["fail"]>[0]> = []; const progressEvents: ProgressEvent[] = []; + const taskSettlements: Array<{ type: "clear" | "fail" | "cancel"; message?: string }> = []; const events: OutputEvent[] = []; const rawChunks: Array<{ text: string; stream: "stdout" | "stderr" }> = []; const promptConfirmCalls: Array<{ @@ -315,6 +318,7 @@ export function mockOutput( }), fail: (nextMessage?: string) => Effect.sync(() => { + taskSettlements.push({ type: "fail", ...optionalMessage(nextMessage) }); if (nextMessage !== undefined) { messages.push({ type: "error", message: nextMessage }); } @@ -327,11 +331,14 @@ export function mockOutput( }), cancel: (nextMessage?: string) => Effect.sync(() => { + taskSettlements.push({ type: "cancel", ...optionalMessage(nextMessage) }); if (nextMessage !== undefined) { messages.push({ type: "warn", message: nextMessage }); } }), - clear: Effect.void, + clear: Effect.sync(() => { + taskSettlements.push({ type: "clear" }); + }), }; }), event: (event) => @@ -451,6 +458,7 @@ export function mockOutput( messages, failures, progressEvents, + taskSettlements, events, promptConfirmCalls, promptSelectCalls, From 731950dae3053295e934c5996bfd4605cbb20c75 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Tue, 17 Nov 2026 10:28:07 +0100 Subject: [PATCH 08/45] test(cli): size standard-errors subprocess timeout for loaded runners --- .../cli/src/shared/cli/standard-errors.integration.test.ts | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/apps/cli/src/shared/cli/standard-errors.integration.test.ts b/apps/cli/src/shared/cli/standard-errors.integration.test.ts index aae8165a2b..c4dc204752 100644 --- a/apps/cli/src/shared/cli/standard-errors.integration.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.integration.test.ts @@ -47,10 +47,13 @@ const runFixture = Effect.fn("StandardErrorsTest.run")(function* ( return { exitCode: Number(exitCode), stdout, stderr }; }, Effect.scoped); +/** Each case boots a cold `bun` process whose time scales with CPU contention, so the default 5s budget is too tight. */ +const SUBPROCESS_TIMEOUT_MS = 60_000; + const lastLine = (text: string) => text.trimEnd().split("\n").at(-1) ?? ""; const decodeJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown)); -describe("errors.standard failure contract", () => { +describe("errors.standard failure contract", { timeout: SUBPROCESS_TIMEOUT_MS }, () => { it.live("reports an API conflict as the last stderr line and nothing on stdout", () => Effect.gen(function* () { const { exitCode, stdout, stderr } = yield* runFixture(["conflict", "-o", "json"]); @@ -182,7 +185,7 @@ describe("errors.standard failure contract", () => { ); }); -describe("commands without the standard marker", () => { +describe("commands without the standard marker", { timeout: SUBPROCESS_TIMEOUT_MS }, () => { it.live("keep the legacy JSON envelope on stdout and exit 1", () => Effect.gen(function* () { const { exitCode, stdout, stderr } = yield* runFixture(["legacy", "--output-format", "json"]); From b2f91f24b512f8bbd7ab7608469010707afb8742 Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Tue, 17 Nov 2026 14:56:57 +0000 Subject: [PATCH 09/45] feat(cli): add generated Warehouse disable command (#7660) Add generated `warehouse disable` and `warehouse teardowns get` commands with explicit `--delete-data`, bounded waiting, and the existing Warehouse feature gate. Retain data by default, poll the accepted cleanup identity, and include the last observed lifecycle state in timeout errors. Reuse shared targeting, consent, output, and error handling. `warehouse teardowns get` reads current cleanup without an ID. Optional `--operation-id` pins observation; `warehouse disable --wait` supplies its ID automatically. Stacks on #7640. Depends on https://github.com/supabase/platform/pull/42016. Implements PIPE-1447. Keeps the local request-preview contract; resolved impact previews remain follow-up work. --- .../command-surface.integration.test.ts | 23 ++ .../command-errors/api-command.errors.ts | 1 + .../src/commands/api/api-command-execute.ts | 22 +- .../src/commands/api/api-command-policy.ts | 8 +- .../api/api-commands.integration.test.ts | 184 +++++++++- .../cli/src/commands/api/generated.schemas.ts | 104 ++++++ apps/cli/src/commands/api/generated.ts | 96 +++++ .../api/warehouse/disable/SIDE_EFFECTS.md | 58 +++ .../warehouse/teardowns/get/SIDE_EFFECTS.md | 21 ++ apps/cli/src/shared/cli/standard-errors.ts | 4 +- packages/api/scripts/openapi-overrides.json | 338 ++++++++++++++++++ packages/api/src/generated/contracts.ts | 138 +++++++ packages/api/src/generated/effect-client.ts | 32 ++ packages/api/src/generated/openapi.json | 323 +++++++++++++++++ packages/api/src/generated/permissions.ts | 5 + 15 files changed, 1346 insertions(+), 11 deletions(-) create mode 100644 apps/cli/src/commands/api/warehouse/disable/SIDE_EFFECTS.md create mode 100644 apps/cli/src/commands/api/warehouse/teardowns/get/SIDE_EFFECTS.md diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 7230e9bc1b..0e19ff9f5e 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -46,8 +46,11 @@ describe("command surface", () => { const { variants } = yield* Effect.promise(() => surface); expect(Object.keys(variants.warehouse)).toEqual([ "warehouse", + "warehouse disable", "warehouse enable", "warehouse status", + "warehouse teardowns", + "warehouse teardowns get", ]); }), ); @@ -85,6 +88,26 @@ describe("command surface", () => { }), ); + it.effect("describes retained-data disable and its linked cleanup read", () => + Effect.gen(function* () { + const { variants } = yield* Effect.promise(() => surface); + const disable = variants.warehouse["warehouse disable"]; + expect(disable).toMatchObject({ + target: { group: "hosted", consent: "no" }, + stage: { status: "experimental", feature: "warehouse" }, + errors: "standard", + api: { operationId: "v2-disable-warehouse" }, + }); + expect(disable?.flags["delete-data"]).toMatchObject({ type: "boolean", required: false }); + expect(disable?.flags["wait"]).toMatchObject({ type: "boolean" }); + expect(disable?.flags["timeout"]).toMatchObject({ type: "string" }); + expect(titlesOf(disable?.result)).toEqual(["response", "waited", "dryRun"]); + expect(variants.warehouse["warehouse teardowns get"]?.flags["operation-id"]).toMatchObject({ + required: false, + }); + }), + ); + it.effect("emits global flags once at the top level, not per command", () => Effect.gen(function* () { const { globalFlags, commands } = yield* Effect.promise(() => surface); diff --git a/apps/cli/src/command-internal/command-errors/api-command.errors.ts b/apps/cli/src/command-internal/command-errors/api-command.errors.ts index 6970331079..0edef12c58 100644 --- a/apps/cli/src/command-internal/command-errors/api-command.errors.ts +++ b/apps/cli/src/command-internal/command-errors/api-command.errors.ts @@ -48,6 +48,7 @@ export class ApiCommandOperationFailedError extends Data.TaggedError( export class ApiCommandWaitTimeoutError extends Data.TaggedError("ApiCommandWaitTimeoutError")<{ readonly message: string; readonly timeoutMillis: number; + readonly lastStatus?: string | null; readonly hint: string; }> { get [ErrorActionabilityId](): CliErrorActionabilityDeclaration { diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index 439540aa07..cb10c63c54 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -314,9 +314,14 @@ export const waitForOperation = Effect.fn("api-command.wait")(function* (input: const decoded = yield* decodeInput(readEntry, readInput); const hint = `Check it with \`${statusCommand(readEntry, input.ref, readInput)}\`.`; const attempts = yield* Ref.make(0); + const lastStatus = yield* Ref.make(null); const poll = Ref.update(attempts, (count) => count + 1).pipe( Effect.andThen(sendApiRequest(readEntry, decoded)), + Effect.tap((response) => { + const status = readPointer(parseResponse(response), wait.status); + return Ref.set(lastStatus, typeof status === "string" ? status : null); + }), Effect.flatMap((response) => classify(wait, response, hint)), Effect.tap(({ response }) => { const status = readPointer(parseResponse(response), wait.status); @@ -330,12 +335,17 @@ export const waitForOperation = Effect.fn("api-command.wait")(function* (input: Effect.timeoutOrElse({ duration: input.timeoutMillis, orElse: () => - Effect.fail( - new ApiCommandWaitTimeoutError({ - message: `Timed out waiting for ${wait.read} to report ${wait.succeeded.join(" or ")}.`, - timeoutMillis: input.timeoutMillis, - hint, - }), + Ref.get(lastStatus).pipe( + Effect.flatMap((status) => + Effect.fail( + new ApiCommandWaitTimeoutError({ + message: `Timed out waiting for ${wait.read} to report ${wait.succeeded.join(" or ")}. Last observed status: ${status === null ? "unavailable" : sanitizeErrorBody(status)}.`, + timeoutMillis: input.timeoutMillis, + lastStatus: status, + hint, + }), + ), + ), ), }), Effect.tapError((error) => diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 08bb5477c1..0a831d3d9d 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -31,8 +31,14 @@ export type ApiCommandPoll = Pick = [ "v2-enable-warehouse", "v2-get-warehouse-setup", + "v2-disable-warehouse", + "v2-get-warehouse-teardown", ]; export const nouns = { - warehouse: { description: "Manage the data warehouse for a project", feature: "warehouse" }, + warehouse: { + description: "Manage the data warehouse for a project", + feature: "warehouse", + groups: { teardowns: "Inspect Warehouse cleanup operations" }, + }, } as const satisfies Readonly>; diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 4418cc1f3c..3a32b50af5 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -298,12 +298,178 @@ const setup = (argv: ReadonlyArray, opts: CliOpts) => { const failureOf = (exit: Exit.Exit): unknown => Exit.isFailure(exit) ? Exit.findErrorOption(exit).pipe(Option.getOrUndefined) : undefined; +const bodiesOf = (sent: ReadonlyArray) => sent.map((request) => request.body); + const driveClock = (fiber: Fiber.Fiber) => Effect.raceFirst(Effect.forever(TestClock.adjust("2 seconds")), Fiber.await(fiber)); -const bodiesOf = (sent: ReadonlyArray) => sent.map((request) => request.body); - describe("generated warehouse commands", () => { + describe("warehouse disable", () => { + const operationId = "7579647f-2cdc-466c-982e-425958a2f985"; + const disablePath = `/v2/projects/${VALID_REF}/warehouse`; + const teardownPath = `${disablePath}/teardowns/current`; + const teardown = (lifecycleStatus: string, deleteData = false) => ({ + data: { + type: "warehouse_teardown", + id: operationId, + attributes: { + lifecycle_status: lifecycleStatus, + delete_data: deleteData, + updated_at: "2026-11-17T10:00:00Z", + cleanup_error: null, + unknown_observation: null, + }, + }, + }); + + it.effect.each([false, true])( + "keeps retention as the default and sends explicit deletion=%s", + (deleteData) => { + const body = teardown("disabling", deleteData); + const { sent, out, run } = setup( + ["warehouse", "disable", ...(deleteData ? ["--delete-data"] : [])], + { + yes: true, + route: () => ({ status: 202, body }), + }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toStrictEqual([ + { + method: "DELETE", + path: disablePath, + search: deleteData ? "delete_data=true" : "", + body: undefined, + }, + ]); + expect(out.stdoutText).toBe(encodeJson(body)); + }); + }, + ); + + it.effect("previews permanent deletion without consent or a command request", () => { + const { sent, out, run } = setup(["warehouse", "disable", "--delete-data", "--dry-run"], { + route: accepted, + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([]); + expect(decodeJson(out.stdoutText)).toMatchObject({ + method: "DELETE", + path: disablePath, + query: { delete_data: true }, + }); + }); + }); + + it.effect("waits on the accepted cleanup identity and prints the final raw resource", () => { + const final = teardown("disabled"); + const { sent, out, run } = setup(["warehouse", "disable", "--wait"], { + yes: true, + route: (request) => + request.method === "DELETE" + ? { status: 202, body: teardown("disabling") } + : { status: 200, body: final }, + }); + return Effect.gen(function* () { + yield* run; + expect(sent.map(({ method, path, search }) => ({ method, path, search }))).toStrictEqual([ + { method: "DELETE", path: disablePath, search: "" }, + { method: "GET", path: teardownPath, search: `operation_id=${operationId}` }, + ]); + expect(out.stdoutText).toBe(encodeJson(final)); + }); + }); + + it.effect.each([undefined, operationId])( + "reads cleanup without mutation consent using optional operation identity %s", + (requestedId) => { + const body = teardown("disabling"); + const { sent, out, run } = setup( + [ + "warehouse", + "teardowns", + "get", + ...(requestedId === undefined ? [] : ["--operation-id", requestedId]), + ], + { route: () => ({ status: 200, body }) }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toStrictEqual([ + { + method: "GET", + path: teardownPath, + search: requestedId === undefined ? "" : `operation_id=${requestedId}`, + body: undefined, + }, + ]); + expect(out.stdoutText).toBe(encodeJson(body)); + }); + }, + ); + + it.effect("waits for the current cleanup without an operation identity", () => { + const final = teardown("disabled"); + let reads = 0; + const { sent, out, run } = setup(["warehouse", "teardowns", "get", "--wait"], { + route: () => ({ + status: 200, + body: reads++ === 0 ? teardown("disabling") : final, + }), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + yield* Fiber.join(fiber); + expect(sent.map(({ method, path, search }) => ({ method, path, search }))).toStrictEqual([ + { method: "GET", path: teardownPath, search: "" }, + { method: "GET", path: teardownPath, search: "" }, + ]); + expect(out.stdoutText).toBe(encodeJson(final)); + }); + }); + + it.effect("preserves partial cleanup failure and the command for inspecting it", () => { + const failed = teardown("deletion_failed", true); + const { run } = setup(["warehouse", "disable", "--delete-data", "--wait"], { + yes: true, + route: (request) => ({ status: request.method === "DELETE" ? 202 : 200, body: failed }), + }); + return Effect.gen(function* () { + const error = yield* run.pipe(Effect.flip); + expect(standardFailureFor(Cause.fail(error)).document).toMatchObject({ + code: "operation_failed", + context: { status: "deletion_failed" }, + hint: expect.stringContaining(`--operation-id ${operationId}`), + }); + }); + }); + + it.effect("reports the last cleanup state on a bounded timeout", () => { + const { run, sent } = setup(["warehouse", "disable", "--wait", "--timeout", "10s"], { + yes: true, + route: (request) => ({ + status: request.method === "DELETE" ? 202 : 200, + body: teardown("disabling"), + }), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + const error = yield* Fiber.join(fiber); + expect(standardFailureFor(Cause.fail(error)).document).toMatchObject({ + code: "wait_timeout", + context: { timeout_ms: 10000, last_status: "disabling" }, + message: expect.stringContaining("disabling"), + hint: expect.stringContaining(`--operation-id ${operationId}`), + }); + expect(sent.filter((request) => request.method === "DELETE")).toHaveLength(1); + }); + }); + }); + describe("warehouse enable request", () => { it.effect("sends only the schema when no other flag is given", () => { const { sent, run } = setup(["warehouse", "enable", "--schema", "public"], { @@ -1357,3 +1523,17 @@ describeHostedConsent("warehouse enable", { }; }, }); + +const disableConsentCommand = commandTreeFor({ warehouseEnabled: true }).get( + "warehouse disable", +)?.command; +describeHostedConsent("warehouse disable", { + ...(disableConsentCommand === undefined ? {} : { command: disableConsentCommand }), + invoke: ({ workdir, yes }) => { + const { args, sent, run } = execute(["warehouse", "disable"], { yes, route: accepted }); + return { + run: run.pipe(Effect.provide(cliServices(workdir, args))), + mutations: () => sent.filter((request) => request.method !== "GET").length, + }; + }, +}); diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index 3c19b03fb1..31c6af8366 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -2,6 +2,58 @@ import type { ApiCommandSchemas } from "./api-command.model.ts"; export const apiCommandSchemas = { + "v2-disable-warehouse": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + cleanup_error: { + description: + "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + type: ["string", "null"], + }, + delete_data: { + description: + "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", + type: "boolean", + }, + lifecycle_status: { + enum: ["deletion_failed", "disabled", "disabling"], + type: "string", + }, + updated_at: { + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + type: "string", + }, + }, + required: ["cleanup_error", "delete_data", "lifecycle_status", "updated_at"], + type: "object", + }, + id: { + format: "uuid", + pattern: + "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + type: "string", + }, + type: { + description: "Resource type.", + enum: ["warehouse_teardown"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-enable-warehouse": { request: { contentType: "application/json", @@ -434,4 +486,56 @@ export const apiCommandSchemas = { required: ["data"], }, }, + "v2-get-warehouse-teardown": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + cleanup_error: { + description: + "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + type: ["string", "null"], + }, + delete_data: { + description: + "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", + type: "boolean", + }, + lifecycle_status: { + enum: ["deletion_failed", "disabled", "disabling"], + type: "string", + }, + updated_at: { + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + type: "string", + }, + }, + required: ["cleanup_error", "delete_data", "lifecycle_status", "updated_at"], + type: "object", + }, + id: { + format: "uuid", + pattern: + "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + type: "string", + }, + type: { + description: "Resource type.", + enum: ["warehouse_teardown"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, } as const satisfies Readonly>; diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 7ae0b55a84..fbff6d8dba 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -2,6 +2,55 @@ import type { ApiCommandEntry } from "./api-command.model.ts"; export const apiCommands = [ + { + command: ["warehouse", "disable"], + operationId: "v2-disable-warehouse", + definition: "v2DisableWarehouse", + method: "DELETE", + apiPath: "/v2/projects/{ref}/warehouse", + summary: "Disable Warehouse replication and access", + description: + "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.", + readOnly: false, + feature: "warehouse", + response: { + status: 202, + kind: "json", + }, + flags: [ + { + name: "delete-data", + type: "boolean", + repeatable: false, + required: false, + description: + "Permanently delete managed Warehouse data. Defaults to false (retain data). Source Postgres tables and legacy shared buckets are preserved.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "query", + name: "delete_data", + source: "flag", + flag: "delete-data", + }, + ], + wait: { + read: "v2-get-warehouse-teardown", + params: { + operation_id: "/data/id", + }, + status: "/data/attributes/lifecycle_status", + succeeded: ["disabled"], + failed: ["deletion_failed"], + error: "/data/attributes/cleanup_error", + }, + }, { command: ["warehouse", "enable"], operationId: "v2-enable-warehouse", @@ -179,4 +228,51 @@ export const apiCommands = [ error: "/data/attributes/status_error", }, }, + { + command: ["warehouse", "teardowns", "get"], + operationId: "v2-get-warehouse-teardown", + definition: "v2GetWarehouseTeardown", + method: "GET", + apiPath: "/v2/projects/{ref}/warehouse/teardowns/current", + summary: "Get Warehouse cleanup status", + description: + "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.", + readOnly: true, + feature: "warehouse", + response: { + status: 200, + kind: "json", + }, + flags: [ + { + name: "operation-id", + type: "string", + repeatable: false, + required: false, + description: + "Optional cleanup operation identity returned by disable. Omit to read the current cleanup; when supplied, a different current operation returns a conflict.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "query", + name: "operation_id", + source: "flag", + flag: "operation-id", + }, + ], + wait: { + read: "v2-get-warehouse-teardown", + params: {}, + status: "/data/attributes/lifecycle_status", + succeeded: ["disabled"], + failed: ["deletion_failed"], + error: "/data/attributes/cleanup_error", + }, + }, ] as const satisfies readonly ApiCommandEntry[]; diff --git a/apps/cli/src/commands/api/warehouse/disable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/disable/SIDE_EFFECTS.md new file mode 100644 index 0000000000..3078cc8b57 --- /dev/null +++ b/apps/cli/src/commands/api/warehouse/disable/SIDE_EFFECTS.md @@ -0,0 +1,58 @@ +# `supabase warehouse disable` + +Target: hosted. Consent defaults to No; noninteractive mutations require `--yes` or shell +`SUPABASE_YES`. Registration requires `experimental.warehouse` in project config or +`SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. + +## Requests and retention + +`DELETE /v2/projects/{ref}/warehouse` starts asynchronous cleanup. Omitted `--delete-data` retains +Warehouse data; `--delete-data` sends `delete_data=true` and permanently deletes the managed +catalog schema and dedicated Storage bucket. Source Postgres tables and legacy shared buckets +remain. The server checks source administrator/database permissions and entitlement, plus +destination SQL/Storage write permissions for data deletion. + +Both modes stop replication and remove the Warehouse publication, FDW and dependent foreign +tables, reader group, external catalog access and query routing. Acceptance does not mean these +effects have completed. Reader memberships must be granted again after re-enablement. + +The response contains the cleanup identity in `data.id`, with `lifecycle_status`, `delete_data`, +`updated_at` and nullable `cleanup_error` in `data.attributes`. Safe retries return the current +operation; the server rejects a changed in-progress data policy. Failed cleanup can be partial. + +`--wait` follows the response link to +`GET /v2/projects/{ref}/warehouse/teardowns/current?operation_id=`. +It uses the shared bounded poller: 1s exponential backoff, capped at 10s, honoring a longer +`Retry-After`. The default timeout is 10m. `disabled` succeeds and `deletion_failed` fails. +Polling uses durable metadata, without an ETL, FDW or source-health dependency. A replaced or +cleared operation returns a conflict. Timeout and cancellation stop local polling only. + +`warehouse teardowns get --remote=` reads current cleanup without an operation ID. +`warehouse teardowns get --operation-id --wait --remote=` resumes observation +of the accepted disable attempt; `disable --wait` always passes this ID through its response link. +That command is read-only and needs no mutation consent. It accepts the same `--timeout` and +output options and requires database-read permission. + +## Local effects and output + +The generated runtime uses the same config, auth/profile, target resolution, linked-project cache, +and telemetry reads/writes as [warehouse enable](../enable/SIDE_EFFECTS.md). Neither command +writes source configuration or executes SQL locally. Command telemetry records generated field +values as redacted; neither cleanup responses nor error contents become telemetry properties. + +Piped and agent runs, `--output-format json|stream-json`, and `-o json` write the raw API JSON +response to stdout, preserving unknown and null fields. An interactive terminal renders the +shared text view unless an output mode is selected; `-o pretty` also selects text. `-o yaml` writes the same document as YAML. With `--wait`, stdout contains the terminal read. +Errors use the standard stderr envelope. `wait_timeout` includes `timeout_ms`, nullable +`last_status`, and the command for resuming observation; terminal text includes the last status. +`operation_failed` includes the failed status and reported cleanup error. + +`--dry-run` prints only the local request in the selected text/JSON/YAML presentation, with the +chosen deletion query, before +consent and without a command request. The post-run best-effort linked-project cache read may +still run. This is not a resolved impact preview; server preview/apply and revision checks remain +follow-up work. Consent uses the operation summary; it does not render a deletion-specific impact +plan. Permanent deletion is described in command and flag help. + +Exit 0 means acceptance, completed waiting or dry-run. Standard API/wait errors exit 1, invalid +usage or missing noninteractive consent exits 2, and cancellation exits 130. diff --git a/apps/cli/src/commands/api/warehouse/teardowns/get/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/teardowns/get/SIDE_EFFECTS.md new file mode 100644 index 0000000000..95419cf7e4 --- /dev/null +++ b/apps/cli/src/commands/api/warehouse/teardowns/get/SIDE_EFFECTS.md @@ -0,0 +1,21 @@ +# `supabase warehouse teardowns get` + +Target: hosted. This read-only command requires the Warehouse family feature gate and no mutation +consent. It calls `GET /v2/projects/{ref}/warehouse/teardowns/current` with bearer authentication. +Omit `--operation-id` to read current cleanup; supply it to pin the read to a specific disable +attempt through the `operation_id` query. The server checks database-read permission +and OAuth scope, then reads durable primary metadata without checking source health, ETL or FDW. + +Piped/agent output and explicit JSON modes preserve the raw JSON response; `-o yaml` encodes +the same document. Interactive terminals use the shared text renderer. Unknown and null +observations remain unchanged in machine output. `--wait` repeats this read until `disabled` or `deletion_failed`, +with the shared backoff and bounded timeout. Without an operation ID, each read observes current +cleanup. A supplied ID that no longer matches fails with a conflict. Missing cleanup state, +including after re-enablement clears it, fails with a conflict in either mode. +Polling does not modify Warehouse state. `--dry-run` prints only the local request, without a +status read. + +The local config/profile/auth reads, linked-project cache, telemetry writes, output, wait-error +context and exit codes are shared with [warehouse disable](../../disable/SIDE_EFFECTS.md). +It does not write project config or read stdin. Post-run best-effort cache requests and telemetry +flushes still run on success, dry-run or failure. diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index 890ed1b5f4..36c14b6dd1 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -63,7 +63,7 @@ interface StandardErrorDocument { readonly hint: string | null; readonly api_code?: string; readonly entitlement?: PlanGateEntitlement; - readonly context?: Readonly>; + readonly context?: Readonly>; } /** A mapped failure: the process exit code and the document to report. */ @@ -172,7 +172,7 @@ const failureForError = ( } if (error instanceof ApiCommandWaitTimeoutError) { return failure(EXIT_FAILURE, "wait_timeout", error.message, error.hint, { - context: { timeout_ms: error.timeoutMillis }, + context: { timeout_ms: error.timeoutMillis, last_status: error.lastStatus ?? null }, }); } if (error instanceof AccessTokenRequiredError || error instanceof InvalidAccessTokenError) { diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 3f9d38d521..42cbdf833a 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -867,5 +867,343 @@ "required": ["data"] }, "$comment": "Staging-only operation; remove once the production Management API ships it." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse", + "value": { + "delete": { + "description": "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-disable-warehouse", + "parameters": [ + { + "description": "Permanently delete managed Warehouse data. Defaults to false (retain data). Source Postgres tables and legacy shared buckets are preserved.", + "in": "query", + "name": "delete_data", + "required": false, + "schema": { + "default": false, + "type": "boolean" + } + }, + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" + } + } + }, + "description": "", + "links": { + "teardown": { + "operationId": "v2-get-warehouse-teardown", + "parameters": { + "operation_id": "$response.body#/data/id", + "ref": "$request.path.ref" + } + } + } + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid deletion option or unmanaged destination" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse mutation or cleanup policy conflict" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse cleanup unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Disable Warehouse replication and access", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse", + "method": "disable" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The public Warehouse disablement and teardown contracts are not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1teardowns~1current", + "value": { + "get": { + "description": "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-teardown", + "parameters": [ + { + "description": "Optional cleanup operation identity returned by disable. Omit to read the current cleanup; when supplied, a different current operation returns a conflict.", + "in": "query", + "name": "operation_id", + "required": false, + "schema": { + "format": "uuid", + "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "type": "string" + } + }, + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Cleanup state is unavailable or the supplied operation identity is no longer current" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse cleanup state unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get Warehouse cleanup status", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.teardowns", + "method": "get", + "poll": { + "error": "/data/attributes/cleanup_error", + "failed": ["deletion_failed"], + "status": "/data/attributes/lifecycle_status", + "succeeded": ["disabled"] + } + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The public Warehouse disablement and teardown contracts are not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseTeardownResponse_Output", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "cleanup_error": { + "description": "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + "nullable": true, + "type": "string" + }, + "delete_data": { + "description": "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", + "type": "boolean" + }, + "lifecycle_status": { + "enum": ["deletion_failed", "disabled", "disabling"], + "type": "string" + }, + "updated_at": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + }, + "required": ["cleanup_error", "delete_data", "lifecycle_status", "updated_at"], + "type": "object" + }, + "id": { + "format": "uuid", + "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_teardown"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The public Warehouse disablement and teardown contracts are not yet in the deployed Management API specification." } ] diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 95c03eee29..6fd95411d0 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -12911,6 +12911,54 @@ export const V2DeployAComputeInstanceOutput = Schema.Struct({ }), }), }); +export const V2DisableWarehouseInput = Schema.Struct({ + delete_data: Schema.optionalKey(Schema.Boolean), + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), +}); +export const V2DisableWarehouseOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + cleanup_error: Schema.Union([ + Schema.String.annotate({ + description: + "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + }), + Schema.Null, + ]), + delete_data: Schema.Boolean.annotate({ + description: + "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", + }), + lifecycle_status: Schema.Union([ + Schema.Literals(["deletion_failed", "disabled", "disabling"]), + OpenString, + ]), + updated_at: Schema.String.annotate({ format: "date-time" }), + }), + id: Schema.String.annotate({ format: "uuid" }).check( + Schema.isPattern( + new RegExp( + "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "u", + ), + ).annotate({ + expected: + "a string matching the RegExp ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + }), + ), + type: Schema.Literal("warehouse_teardown").annotate({ description: "Resource type." }), + }), +}); export const V2DownloadProjectBackupInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -14286,6 +14334,66 @@ export const V2GetWarehouseSetupOutput = Schema.Struct({ }), }), }); +export const V2GetWarehouseTeardownInput = Schema.Struct({ + operation_id: Schema.optionalKey( + Schema.String.annotate({ format: "uuid" }).check( + Schema.isPattern( + new RegExp( + "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "u", + ), + ).annotate({ + expected: + "a string matching the RegExp ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + }), + ), + ), + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), +}); +export const V2GetWarehouseTeardownOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + cleanup_error: Schema.Union([ + Schema.String.annotate({ + description: + "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + }), + Schema.Null, + ]), + delete_data: Schema.Boolean.annotate({ + description: + "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", + }), + lifecycle_status: Schema.Union([ + Schema.Literals(["deletion_failed", "disabled", "disabling"]), + OpenString, + ]), + updated_at: Schema.String.annotate({ format: "date-time" }), + }), + id: Schema.String.annotate({ format: "uuid" }).check( + Schema.isPattern( + new RegExp( + "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "u", + ), + ).annotate({ + expected: + "a string matching the RegExp ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + }), + ), + type: Schema.Literal("warehouse_teardown").annotate({ description: "Resource type." }), + }), +}); export const V2ListAllComputeInstancesInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -19278,12 +19386,14 @@ export const openApiOperationIdMap = { "v2-delete-private-link-association": "v2DeletePrivateLinkAssociation", "v2-delete-private-link-association-for-database": "v2DeletePrivateLinkAssociationForDatabase", "v2-deploy-a-compute-instance": "v2DeployAComputeInstance", + "v2-disable-warehouse": "v2DisableWarehouse", "v2-download-project-backup": "v2DownloadProjectBackup", "v2-enable-warehouse": "v2EnableWarehouse", "v2-get-a-compute-instance": "v2GetAComputeInstance", "v2-get-notebook": "v2GetNotebook", "v2-get-project-config": "v2GetProjectConfig", "v2-get-warehouse-setup": "v2GetWarehouseSetup", + "v2-get-warehouse-teardown": "v2GetWarehouseTeardown", "v2-list-all-compute-instances": "v2ListAllComputeInstances", "v2-list-log-drains": "v2ListLogDrains", "v2-list-notebooks": "v2ListNotebooks", @@ -22360,6 +22470,20 @@ export const operationDefinitions = { inputSchema: V2DeployAComputeInstanceInput, outputSchema: V2DeployAComputeInstanceOutput, }, + v2DisableWarehouse: { + id: "v2DisableWarehouse", + description: + "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "DELETE", + path: "/v2/projects/{ref}/warehouse", + pathParams: ["ref"], + queryParams: ["delete_data"], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2DisableWarehouseInput, + outputSchema: V2DisableWarehouseOutput, + }, v2DownloadProjectBackup: { id: "v2DownloadProjectBackup", description: "Download project backup", @@ -22442,6 +22566,20 @@ export const operationDefinitions = { inputSchema: V2GetWarehouseSetupInput, outputSchema: V2GetWarehouseSetupOutput, }, + v2GetWarehouseTeardown: { + id: "v2GetWarehouseTeardown", + description: + "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/teardowns/current", + pathParams: ["ref"], + queryParams: ["operation_id"], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2GetWarehouseTeardownInput, + outputSchema: V2GetWarehouseTeardownOutput, + }, v2ListAllComputeInstances: { id: "v2ListAllComputeInstances", description: diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index 4f9df89294..2ec5e00e76 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -2980,6 +2980,22 @@ export const versionedEffectOperations = { options, ); }), + disableWarehouse: ( + input: typeof operationDefinitions.v2DisableWarehouse.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2DisableWarehouse.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2DisableWarehouse">( + operationDefinitions.v2DisableWarehouse, + input, + options, + ); + }), downloadProjectBackup: ( input: typeof operationDefinitions.v2DownloadProjectBackup.inputSchema.Type, options?: SupabaseApiRequestOptions, @@ -3076,6 +3092,22 @@ export const versionedEffectOperations = { options, ); }), + getWarehouseTeardown: ( + input: typeof operationDefinitions.v2GetWarehouseTeardown.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2GetWarehouseTeardown.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2GetWarehouseTeardown">( + operationDefinitions.v2GetWarehouseTeardown, + input, + options, + ); + }), listAllComputeInstances: ( input: typeof operationDefinitions.v2ListAllComputeInstances.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index 598de4b9be..ee5a026eb9 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -32241,6 +32241,283 @@ "x-oauth-scope": "database:read", "x-scalar-stability": "experimental" } + }, + "/v2/projects/{ref}/warehouse": { + "delete": { + "description": "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-disable-warehouse", + "parameters": [ + { + "description": "Permanently delete managed Warehouse data. Defaults to false (retain data). Source Postgres tables and legacy shared buckets are preserved.", + "in": "query", + "name": "delete_data", + "required": false, + "schema": { + "default": false, + "type": "boolean" + } + }, + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" + } + } + }, + "description": "", + "links": { + "teardown": { + "operationId": "v2-get-warehouse-teardown", + "parameters": { + "operation_id": "$response.body#/data/id", + "ref": "$request.path.ref" + } + } + } + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid deletion option or unmanaged destination" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse mutation or cleanup policy conflict" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse cleanup unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Disable Warehouse replication and access", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse", + "method": "disable" + }, + "x-scalar-stability": "experimental" + } + }, + "/v2/projects/{ref}/warehouse/teardowns/current": { + "get": { + "description": "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-teardown", + "parameters": [ + { + "description": "Optional cleanup operation identity returned by disable. Omit to read the current cleanup; when supplied, a different current operation returns a conflict.", + "in": "query", + "name": "operation_id", + "required": false, + "schema": { + "format": "uuid", + "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "type": "string" + } + }, + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Cleanup state is unavailable or the supplied operation identity is no longer current" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse cleanup state unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get Warehouse cleanup status", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.teardowns", + "method": "get", + "poll": { + "error": "/data/attributes/cleanup_error", + "failed": ["deletion_failed"], + "status": "/data/attributes/lifecycle_status", + "succeeded": ["disabled"] + } + }, + "x-scalar-stability": "experimental" + } } }, "components": { @@ -47321,6 +47598,52 @@ } }, "required": ["data"] + }, + "V2WarehouseTeardownResponse_Output": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "cleanup_error": { + "description": "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + "nullable": true, + "type": "string" + }, + "delete_data": { + "description": "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", + "type": "boolean" + }, + "lifecycle_status": { + "enum": ["deletion_failed", "disabled", "disabling"], + "type": "string" + }, + "updated_at": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + }, + "required": ["cleanup_error", "delete_data", "lifecycle_status", "updated_at"], + "type": "object" + }, + "id": { + "format": "uuid", + "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_teardown"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index b5fc0dd7f6..135d32ae05 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -436,4 +436,9 @@ export const operationPermissions: Readonly "v2-organizations-slug-webhooks-deliveries-id-retry-post": { fga: [] }, "v2-enable-warehouse": { fga: [["database_write"]], oauthScope: "database:write" }, "v2-get-warehouse-setup": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-disable-warehouse": { + fga: [["database_write", "project_admin_write"]], + oauthScope: "database:write", + }, + "v2-get-warehouse-teardown": { fga: [["database_read"]], oauthScope: "database:read" }, }; From 39e27f3b48d7cc021b46ee7af8252bc1986a527f Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Tue, 17 Nov 2026 22:21:28 +0100 Subject: [PATCH 10/45] feat(cli): expose consolidated Warehouse status (#7671) Generate `warehouse status` from `GET /v2/projects/{ref}/warehouse/status`, preserving readiness, capabilities, zero-target enablement and unavailable observations through the shared runtime. Preserve `warehouse enable --wait` with selection-bound setup polling. Discover internal polling targets from response links without exposing a `warehouse setups get` command; status has no wait flags. Retain teardown waiting. Keep text output on terminals, raw JSON when piped or requested, and YAML through `-o yaml`. Stacked on #7640 (including merged #7660). Depends on https://github.com/supabase/platform/pull/42039. Implements PIPE-1445. --------- Co-authored-by: Julien Goux --- apps/cli/scripts/api-command-derive.ts | 173 +++++- .../scripts/api-command-derive.unit.test.ts | 203 ++++++- apps/cli/scripts/generate-api-commands.ts | 16 +- .../command-surface.integration.test.ts | 22 + .../api-command-bindings.integration.test.ts | 2 + .../src/commands/api/api-command-execute.ts | 19 +- .../src/commands/api/api-command-policy.ts | 13 +- .../src/commands/api/api-command-request.ts | 3 +- .../api-command-shapes.integration.test.ts | 1 + .../cli/src/commands/api/api-command.model.ts | 12 + .../src/commands/api/api-commands.e2e.test.ts | 38 +- .../api/api-commands.integration.test.ts | 278 ++++----- .../cli/src/commands/api/generated.schemas.ts | 405 +++++++++++++ apps/cli/src/commands/api/generated.ts | 65 +-- apps/cli/src/commands/api/runtime.ts | 25 +- .../api/warehouse/enable/SIDE_EFFECTS.md | 4 +- .../api/warehouse/status/SIDE_EFFECTS.md | 57 +- packages/api/scripts/openapi-overrides.json | 547 ++++++++++++++++++ packages/api/src/generated/contracts.ts | 372 ++++++++++++ packages/api/src/generated/effect-client.ts | 16 + packages/api/src/generated/openapi.json | 512 +++++++++++++++- packages/api/src/generated/permissions.ts | 1 + 22 files changed, 2516 insertions(+), 268 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 6901a786b6..9b70ce85af 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -11,6 +11,7 @@ import type { ApiCommandFlag, ApiCommandSchemas, ApiCommandWait, + ApiPollTarget, } from "../src/commands/api/api-command.model.ts"; type JsonObject = Readonly>; @@ -85,6 +86,8 @@ interface DeriveInput { readonly spec: JsonObject; /** Operation ids that generate commands; `x-operation` on any other operation is ignored. */ readonly generated: ReadonlyArray; + /** Hidden polling operation id to the generated operation whose command inspects its state. */ + readonly pollTargets: Readonly>; readonly nouns: Readonly>; /** Kebab-case operation id to the camelCase key of the typed client's `operationDefinitions`. */ readonly operationIdMap: Readonly>; @@ -94,6 +97,7 @@ interface DeriveInput { interface DeriveResult { readonly entries: ReadonlyArray; + readonly pollTargets: ReadonlyArray; readonly schemas: Readonly>; readonly problems: ReadonlyArray; } @@ -532,6 +536,60 @@ const readMetadata = ( return metadata; }; +/** Reads each internal polling target's `poll` and checks its map entry against the generated operations. */ +const readPollTargets = ( + operations: ReadonlyMap, + generated: ReadonlyArray, + targets: Readonly>, + problems: Array, +): ReadonlyMap => { + const polls = new Map(); + for (const [targetId, inspectId] of Object.entries(targets)) { + const fail = (reason: string) => problems.push(`${targetId}: ${reason}`); + const target = operations.get(targetId); + if (target === undefined) { + fail("polling target has no operation in the spec"); + continue; + } + if (generated.includes(targetId)) { + fail("polling target is also a generated operation; remove it from pollTargets"); + } + if (!generated.includes(inspectId)) { + fail(`inspect operation "${inspectId}" is not a generated operation`); + } + const block = target.node["x-operation"]; + if (block === undefined) { + fail("polling target has no x-operation poll"); + continue; + } + const decoded = decodeXOperation(block); + if (Exit.isFailure(decoded)) { + fail(`invalid x-operation: ${Cause.pretty(decoded.cause)}`); + } else if (decoded.value.poll === undefined) { + fail("polling target declares no poll"); + } else { + polls.set(targetId, decoded.value.poll); + } + } + return polls; +}; + +const requireExperimental = (operation: Operation, fail: (reason: string) => void): void => { + if (asString(operation.node["x-scalar-stability"]) !== "experimental") { + fail("only operations marked experimental can be generated (x-scalar-stability)"); + } +}; + +const requireOneWait = ( + ownPoll: ApiCommandPoll | undefined, + linked: ApiCommandWait | undefined, + fail: (reason: string) => void, +): void => { + if (ownPoll !== undefined && linked !== undefined) { + fail(`declares poll and also links to the polled operation "${linked.read}"; use one`); + } +}; + const pollWait = ( read: string, params: Readonly>, @@ -550,12 +608,14 @@ const REQUEST_PATH = /^\$request\.path\.(.+)$/u; /** * The wait a command's 2xx response `links` declare: the one link whose target operation has - * `poll`. Links to operations without `poll` are ignored; a polled target that is not generated fails. + * `poll`. The target is a generated operation or a listed polling target; links without `poll` + * are ignored. */ const linkedWait = ( spec: JsonObject, operations: ReadonlyMap, - metadata: ReadonlyMap, + polls: ReadonlyMap, + generated: ReadonlyArray, operation: Operation, fail: (reason: string) => void, ): ApiCommandWait | undefined => { @@ -576,11 +636,14 @@ const linkedWait = ( fail(`link "${linkName}" targets unknown operation "${targetId}"`); continue; } - const poll = metadata.get(targetId)?.poll; + const poll = polls.get(targetId); if (poll === undefined) { - if (!metadata.has(targetId) && asRecord(target.node["x-operation"])?.poll !== undefined) { + if ( + !generated.includes(targetId) && + asRecord(target.node["x-operation"])?.poll !== undefined + ) { fail( - `link "${linkName}" targets "${targetId}", which declares poll but is not generated`, + `link "${linkName}" targets polled operation "${targetId}", which is neither generated nor listed in pollTargets`, ); } continue; @@ -626,11 +689,23 @@ const linkedWait = ( /** Derives the generated commands from each operation's `x-operation` and collects every lint failure. */ export function deriveApiCommands(input: DeriveInput): DeriveResult { - const { spec, generated, nouns, operationIdMap, handWrittenTopLevel } = input; + const { + spec, + generated, + pollTargets: pollTargetMap, + nouns, + operationIdMap, + handWrittenTopLevel, + } = input; const operations = collectOperations(spec); const problems: Array = []; const metadata = readMetadata(operations, generated, problems); - const commandNamed = new Set(metadata.keys()); + const polls = new Map(); + for (const [operationId, name] of metadata) { + if (name.poll !== undefined) polls.set(operationId, name.poll); + } + const hiddenPolls = readPollTargets(operations, generated, pollTargetMap, problems); + for (const [operationId, poll] of hiddenPolls) polls.set(operationId, poll); const entries: Array = []; const schemas: Record = {}; const commandOwners = new Map(); @@ -681,10 +756,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { fail(`command "${commandKey}" collides with the hand-written "${command[0]}" command`); } - const stability = asString(operation.node["x-scalar-stability"]); - if (stability !== "experimental") { - fail("only operations marked experimental can be generated (x-scalar-stability)"); - } + requireExperimental(operation, fail); const summary = asString(operation.node.summary); if (summary === undefined) fail("operation has no summary"); @@ -937,14 +1009,12 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { }); } - const linked = linkedWait(spec, operations, metadata, operation, fail); + const linked = linkedWait(spec, operations, polls, generated, operation, fail); const ownPoll = name.poll; - if (ownPoll !== undefined && linked !== undefined) { - fail(`declares poll and also links to the polled operation "${linked.read}"; use one`); - } + requireOneWait(ownPoll, linked, fail); const wait = linked ?? (ownPoll === undefined ? undefined : pollWait(operationId, {}, ownPoll)); if (wait !== undefined) { - lintWait({ spec, operations, commandNamed, operation, wait, fail }); + lintWait({ spec, operations, operation, wait, fail }); } const response = classifySuccess(spec, operation, fail); @@ -1003,28 +1073,87 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { entries.sort((left, right) => left.command.join(" ").localeCompare(right.command.join(" "), "en"), ); - return { entries, schemas, problems }; + const pollTargets: Array = []; + const reached = new Set( + entries.flatMap((entry) => (entry.wait === undefined ? [] : [entry.wait.read])), + ); + for (const [operationId, inspectId] of Object.entries(pollTargetMap).toSorted(([a], [b]) => + a.localeCompare(b, "en"), + )) { + const operation = operations.get(operationId); + const poll = hiddenPolls.get(operationId); + if (operation === undefined || poll === undefined) continue; + const fail = (reason: string) => problems.push(`${operationId}: ${reason}`); + if (!reached.has(operationId)) { + fail("polling target is not linked from any generated operation; remove it from pollTargets"); + continue; + } + const definition = operationIdMap[operationId]; + if (definition === undefined) { + fail("polling target is missing from the typed client; regenerate @supabase/api"); + continue; + } + requireExperimental(operation, fail); + requireOneWait(poll, linkedWait(spec, operations, polls, generated, operation, fail), fail); + const inspect = entries.find((entry) => entry.operationId === inspectId); + if ( + inspect !== undefined && + (inspect.argument !== undefined || + inspect.body !== undefined || + inspect.flags.some((flag) => flag.required)) + ) { + fail(`inspect operation "${inspectId}" needs input beyond the project ref`); + } + if (inspect !== undefined && !inspect.readOnly) { + fail(`inspect operation "${inspectId}" must be a read-only command`); + } + const summary = asString(operation.node.summary); + if (summary === undefined) { + fail("polling target is missing a summary"); + continue; + } + const response = classifySuccess(spec, operation, fail); + if (response === undefined) continue; + if (response.kind !== "json") { + fail("polling target must return JSON"); + continue; + } + schemas[operationId] = { result: withDialect(toJsonSchema(spec, response.schema, [], fail)) }; + pollTargets.push({ + operationId, + definition, + summary, + response: { status: response.status, kind: response.kind }, + inspect: inspectId, + }); + } + return { entries, pollTargets, schemas, problems }; } function lintWait(input: { readonly spec: JsonObject; readonly operations: ReadonlyMap; - readonly commandNamed: ReadonlySet; readonly operation: Operation; readonly wait: ApiCommandWait; readonly fail: (reason: string) => void; }): void { - const { spec, operations, commandNamed, operation, wait, fail } = input; + const { spec, operations, operation, wait, fail } = input; const readOperation = operations.get(wait.read); if (readOperation === undefined) { fail(`wait.read "${wait.read}" has no operation in the spec`); return; } - if (!commandNamed.has(wait.read)) { - fail(`wait.read "${wait.read}" is not a generated command`); + if (readOperation.method !== "GET") { + fail(`wait.read "${wait.read}" must use GET`); + } + if (readOperation.node.requestBody !== undefined) { + fail(`wait.read "${wait.read}" must not require a request body`); } const readParameters = operationParameters(spec, readOperation); + if (!readParameters.some((parameter) => parameter.in === "path" && parameter.name === "ref")) { + fail(`wait.read "${wait.read}" must be scoped by a project ref path parameter`); + } const suppliable = new Set( readParameters .filter( @@ -1052,7 +1181,7 @@ function lintWait(input: { wait.read !== operation.id && parameter.required === true && parameterName !== undefined && - parameterName !== "ref" && + !(parameterName === "ref" && parameter.in === "path") && wait.params[parameterName] === undefined ) { fail(`wait.params does not supply required parameter "${parameterName}" of ${wait.read}`); diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 9a9483859e..9775ae2366 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -77,6 +77,7 @@ const derive = ( }, }, generated, + pollTargets: {}, nouns: { thing: thingNoun }, operationIdMap: Object.fromEntries( Object.keys(operations).map((id) => [id, "v2EnableWarehouse" as const]), @@ -548,6 +549,16 @@ describe("deriveApiCommands", () => { operation({ ...create, responses: changeResponse(links, schema) }); const waitOf = (result: ReturnType) => result.entries.find((entry) => entry.operationId === "create-thing")?.wait; + const inspectThing = operation(named("status")); + /** `create-thing` and an inspect command are generated; each listed polling target stays hidden. */ + const deriveHidden = ( + operations: Record, + targets: Record = { "get-thing": "get-inspect" }, + inspect: unknown = inspectThing, + ) => + derive({ ...operations, "get-inspect": inspect }, ["create-thing", "get-inspect"], { + overrides: { pollTargets: targets }, + }); it("builds the wait from the polled target and leaves the shared path parameter to the runtime", () => { const result = derive({ @@ -632,13 +643,199 @@ describe("deriveApiCommands", () => { expect(waitOf(result)).toBeUndefined(); }); - it("rejects a link to a polled target that is not generated", () => { + it("keeps a listed polling target internal and records the command that inspects it", () => { + const result = deriveHidden({ + "create-thing": changeThing( + link({ ref: "$request.path.ref", thing_id: "$response.body#/data/id" }), + ), + "get-thing": readThing, + }); + + expect(result.problems).toEqual([]); + expect(result.entries.map((entry) => entry.command)).toEqual([ + ["thing", "create"], + ["thing", "status"], + ]); + expect(waitOf(result)).toEqual({ + read: "get-thing", + params: { thing_id: "/data/id" }, + ...poll, + }); + expect(result.pollTargets).toEqual([ + { + operationId: "get-thing", + definition: "v2EnableWarehouse", + summary: "Do the thing", + response: { status: 200, kind: "json" }, + inspect: "get-inspect", + }, + ]); + expect(result.schemas["get-thing"]?.result).toEqual({ $schema: DIALECT, ...readSchema }); + }); + + it("rejects a link to a polled operation that is neither generated nor listed", () => { const result = derive({ "create-thing": changeThing(link({})), "get-thing": readThing }, [ "create-thing", ]); + expect(result.problems.join("\n")).toContain( + 'targets polled operation "get-thing", which is neither generated nor listed in pollTargets', + ); + expect(result.pollTargets).toEqual([]); + }); + + it("rejects a listed polling target that no generated operation links to", () => { + const result = deriveHidden({ + "create-thing": operation(create), + "get-thing": readThing, + }); + + expect(result.problems).toEqual([ + "get-thing: polling target is not linked from any generated operation; remove it from pollTargets", + ]); + }); + + it("rejects a listed polling target that is also generated", () => { + const result = derive( + { "create-thing": changeThing(link({})), "get-thing": readThing }, + ["create-thing", "get-thing", "get-inspect"], + { overrides: { pollTargets: { "get-thing": "get-inspect" } } }, + ); + + expect(result.problems.join("\n")).toContain( + "get-thing: polling target is also a generated operation", + ); + }); + + it("rejects an inspect command that needs input beyond the project ref", () => { + const result = deriveHidden( + { "create-thing": changeThing(link({})), "get-thing": readThing }, + { "get-thing": "get-inspect" }, + operation({ + ...named("status"), + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "id", in: "path", required: true, schema: { type: "string" } }, + ], + }), + ); + + expect(result.problems).toEqual([ + 'get-thing: inspect operation "get-inspect" needs input beyond the project ref', + ]); + }); + + it("rejects an inspect command that changes state", () => { + const result = derive( + { + "create-thing": changeThing(link({})), + "get-thing": readThing, + "reset-thing": operation(named("delete")), + }, + ["create-thing", "reset-thing"], + { overrides: { pollTargets: { "get-thing": "reset-thing" } } }, + ); + + expect(result.problems).toEqual([ + 'get-thing: inspect operation "reset-thing" must be a read-only command', + ]); + }); + + it("rejects an inspect operation that is not generated", () => { + const result = deriveHidden( + { "create-thing": changeThing(link({})), "get-thing": readThing }, + { "get-thing": "get-missing" }, + ); + + expect(result.problems.join("\n")).toContain( + 'inspect operation "get-missing" is not a generated operation', + ); + }); + + it("rejects a listed polling target that declares poll and also links to a polled operation", () => { + const result = deriveHidden( + { + "create-thing": changeThing(link({})), + "get-thing": operation({ + ...readThing, + responses: { + "200": { ...jsonResponse(readSchema)["200"], links: link({}, "get-other") }, + }, + }), + "get-other": readThing, + }, + { "get-thing": "get-inspect", "get-other": "get-inspect" }, + ); + + expect(result.problems.join("\n")).toContain( + 'get-thing: declares poll and also links to the polled operation "get-other"; use one', + ); + }); + + it("rejects a listed polling target that is not experimental", () => { + const result = deriveHidden({ + "create-thing": changeThing(link({})), + "get-thing": { ...readThing, "x-scalar-stability": "stable" }, + }); + + expect(result.problems).toEqual([ + "get-thing: only operations marked experimental can be generated (x-scalar-stability)", + ]); + }); + + it.each([ + ["a mutation", "update-thing", readThing, "must use GET"], + [ + "a request body", + "get-thing", + { ...readThing, requestBody: envelope({}) }, + "must not require a request body", + ], + [ + "no project scope", + "get-thing", + { ...readThing, parameters: [] }, + "must be scoped by a project ref path parameter", + ], + [ + "invalid poll metadata", + "get-thing", + readWith({ ...poll, succeeded: "done" }), + "invalid x-operation", + ], + ] as const)("rejects a listed polling target with %s", (_label, id, read, message) => { + const result = deriveHidden( + { "create-thing": changeThing(link({}, id)), [id]: read }, + { + [id]: "get-inspect", + }, + ); + + expect(result.problems.join("\n")).toContain(message); + expect(result.pollTargets).toEqual([]); + }); + + it("rejects a listed polling target missing from the typed client", () => { + const result = derive( + { + "create-thing": changeThing(link({})), + "get-thing": readThing, + "get-inspect": inspectThing, + }, + ["create-thing", "get-inspect"], + { + overrides: { + pollTargets: { "get-thing": "get-inspect" }, + operationIdMap: { + "create-thing": "v2EnableWarehouse", + "get-inspect": "v2EnableWarehouse", + }, + }, + }, + ); + expect(result.problems).toEqual([ - 'create-thing: link "setup" targets "get-thing", which declares poll but is not generated', + "get-thing: polling target is missing from the typed client; regenerate @supabase/api", ]); }); @@ -708,7 +905,7 @@ describe("deriveApiCommands", () => { 'wait.params does not supply required parameter "thing_id" of get-thing', ], ])("rejects a poll with %s", (_label, read, message) => { - const result = derive({ "create-thing": changeThing(link({})), "get-thing": read }); + const result = deriveHidden({ "create-thing": changeThing(link({})), "get-thing": read }); expect(result.problems.map((problem) => problem.replace(/^[^:]+: /u, ""))).toContain(message); }); diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index d771dabc19..45b08d6f7d 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -1,7 +1,11 @@ import { BunRuntime, BunServices } from "@effect/platform-bun"; import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; -import { generatedOperations, nouns } from "../src/commands/api/api-command-policy.ts"; +import { + generatedOperations, + nouns, + pollTargets as pollTargetMap, +} from "../src/commands/api/api-command-policy.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { ApiCommandGenerationError, deriveApiCommands } from "./api-command-derive.ts"; @@ -85,9 +89,10 @@ const main = Effect.gen(function* () { return yield* new ApiCommandGenerationError({ problems: ["openapi.json is not an object"] }); } - const { entries, schemas, problems } = deriveApiCommands({ + const { entries, pollTargets, schemas, problems } = deriveApiCommands({ spec, generated: generatedOperations, + pollTargets: pollTargetMap, nouns, operationIdMap: openApiOperationIdMap, handWrittenTopLevel: yield* handWrittenTopLevel(cliRoot), @@ -100,7 +105,7 @@ const main = Effect.gen(function* () { const outputs = [ { relative: "src/commands/api/generated.ts", - source: `${HEADER}import type { ApiCommandEntry } from "./api-command.model.ts";\n\nexport const apiCommands = ${yield* encodeJson(entries)} as const satisfies readonly ApiCommandEntry[];\n`, + source: `${HEADER}import type { ApiCommandEntry, ApiPollTarget } from "./api-command.model.ts";\n\nexport const apiCommands = ${yield* encodeJson(entries)} as const satisfies readonly ApiCommandEntry[];\n\nexport const apiPollTargets = ${yield* encodeJson(pollTargets)} as const satisfies readonly ApiPollTarget[];\n`, }, { relative: "src/commands/api/generated.schemas.ts", @@ -123,7 +128,10 @@ const main = Effect.gen(function* () { } if (stale.length > 0) return yield* new ApiCommandDriftError({ files: stale }); if (check) yield* Console.log("Generated API command files are up to date."); - yield* Effect.annotateCurrentSpan("apiCommands.count", entries.length); + yield* Effect.annotateCurrentSpan({ + "apiCommands.count": entries.length, + "apiPollTargets.count": pollTargets.length, + }); }); if (import.meta.main) { diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 0e19ff9f5e..65849c9297 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -118,6 +118,28 @@ describe("command surface", () => { }), ); + it.effect("separates consolidated status from the identity-bound setup waiter", () => + Effect.gen(function* () { + const { variants } = yield* Effect.promise(() => surface); + const status = variants.warehouse["warehouse status"]; + expect(status).toMatchObject({ + api: { operationId: "v2-get-warehouse-status" }, + target: { group: "hosted", consent: "none" }, + stage: { status: "experimental", feature: "warehouse" }, + }); + expect(status?.flags).not.toHaveProperty("inspect-fdw"); + expect(status?.flags).not.toHaveProperty("selection-id"); + expect(status?.flags).not.toHaveProperty("wait"); + expect(status?.flags).not.toHaveProperty("timeout"); + expect(variants.warehouse).not.toHaveProperty("warehouse setups"); + expect(variants.warehouse).not.toHaveProperty("warehouse setups get"); + expect(variants.warehouse["warehouse enable"]?.flags).toMatchObject({ + wait: { type: "boolean" }, + timeout: { type: "string" }, + }); + }), + ); + it.effect("declares a waited result only for a command that waits on another read", () => Effect.gen(function* () { const { variants } = yield* Effect.promise(() => surface); diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 43d3bf3d36..64f65afaa4 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -111,6 +111,8 @@ const shapeOf = (schema: unknown): unknown => { const PATTERN_SAMPLES: Readonly> = { "^[a-f0-9]{64}$": "ab".repeat(32), "^[a-z]+$": "zyxwvutsrqponmlkjihg", + "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$": + "7579647f-2cdc-466c-982e-425958a2f985", }; /** A value the field's schema accepts; an unknown string pattern fails loudly instead of guessing. */ diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index cb10c63c54..4baa490e3c 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -10,14 +10,14 @@ import { parsePlanGateEnvelope, sanitizeErrorBody } from "../../command-internal import { encodeStructYaml, shapeAny } from "../../command-internal/struct-output.encoders.ts"; import { Output } from "../../shared/output/output.service.ts"; import { readPointer } from "./api-command-pointer.ts"; -import { decodeInput, definitionOf, type ApiRequestPreview } from "./api-command-request.ts"; +import { definitionOf, type ApiRequestPreview } from "./api-command-request.ts"; import { renderDryRunText, renderResponseText } from "./api-command.format.ts"; import { ApiCommandOperationFailedError, ApiCommandStatusError, ApiCommandWaitTimeoutError, } from "../../command-internal/command-errors/api-command.errors.ts"; -import type { ApiCommandEntry, ApiCommandWait } from "./api-command.model.ts"; +import type { ApiCommandEntry, ApiCommandWait, ApiPollRead } from "./api-command.model.ts"; const POLL_BASE_DELAY = "1 second"; const POLL_MAX_DELAY_MILLIS = 10_000; @@ -143,7 +143,7 @@ export interface ApiCommandResponse { * the API's own message, code and hint. */ export const sendApiRequest = Effect.fnUntraced(function* ( - entry: ApiCommandEntry, + entry: Pick, decoded: OperationInput, ) { const api = yield* CommandPlatformApi; @@ -168,7 +168,7 @@ const parseResponse = (response: ApiCommandResponse): unknown => * person. */ export const writeApiResponse = Effect.fnUntraced(function* ( - entry: ApiCommandEntry, + entry: Pick, response: ApiCommandResponse, format: ApiOutputFormat, ) { @@ -197,7 +197,9 @@ export const writeApiResponse = Effect.fnUntraced(function* ( interface WaitInput { readonly wait: ApiCommandWait; /** The operation the wait polls; its decoded input is `readInput`. */ - readonly readEntry: ApiCommandEntry; + readonly readEntry: ApiPollRead; + /** The command to name in a failure hint: the read's own, or the one that inspects a hidden read. */ + readonly statusEntry: ApiCommandEntry; /** The flat input of the read operation, as assembled from flags or the change response. */ readonly readInput: Readonly>; readonly ref: string; @@ -311,8 +313,11 @@ export const linkedReadInput = Effect.fnUntraced(function* (input: { */ export const waitForOperation = Effect.fn("api-command.wait")(function* (input: WaitInput) { const { wait, readEntry, readInput } = input; - const decoded = yield* decodeInput(readEntry, readInput); - const hint = `Check it with \`${statusCommand(readEntry, input.ref, readInput)}\`.`; + const decoded = yield* Schema.decodeEffect(definitionOf(readEntry).inputSchema, { + onExcessProperty: "error", + })(readInput).pipe(Effect.orDie); + const statusInput = input.statusEntry.operationId === readEntry.operationId ? readInput : {}; + const hint = `Check it with \`${statusCommand(input.statusEntry, input.ref, statusInput)}\`.`; const attempts = yield* Ref.make(0); const lastStatus = yield* Ref.make(null); diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 0a831d3d9d..a3b190738c 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -27,18 +27,25 @@ export interface ApiNoun { /** How to tell that the resource a read operation returns has settled. */ export type ApiCommandPoll = Pick; -/** Only these operations generate commands; `x-operation` on any other operation is ignored. */ +/** Only these operations generate commands; `x-operation` on any other operation is ignored, except on a `pollTargets` key. */ export const generatedOperations: ReadonlyArray = [ + "v2-get-warehouse-status", "v2-enable-warehouse", - "v2-get-warehouse-setup", "v2-disable-warehouse", "v2-get-warehouse-teardown", ]; +/** Hidden polling operations a generated link may target, each with the generated operation whose command inspects its state. */ +export const pollTargets: Readonly>> = { + "v2-get-warehouse-setup": "v2-get-warehouse-status", +}; + export const nouns = { warehouse: { description: "Manage the data warehouse for a project", feature: "warehouse", - groups: { teardowns: "Inspect Warehouse cleanup operations" }, + groups: { + teardowns: "Inspect Warehouse cleanup operations", + }, }, } as const satisfies Readonly>; diff --git a/apps/cli/src/commands/api/api-command-request.ts b/apps/cli/src/commands/api/api-command-request.ts index c88681f384..fcb3233463 100644 --- a/apps/cli/src/commands/api/api-command-request.ts +++ b/apps/cli/src/commands/api/api-command-request.ts @@ -16,7 +16,8 @@ const isRecord = (value: unknown): value is Readonly> => Predicate.isObject(value) && !Array.isArray(value); /** The operation's typed definition; the entry names it as a key of `operationDefinitions`. */ -export const definitionOf = (entry: ApiCommandEntry) => operationDefinitions[entry.definition]; +export const definitionOf = (entry: Pick) => + operationDefinitions[entry.definition]; const parseBodyText = Effect.fnUntraced(function* (text: string, source: string) { const parsed = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe( diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts index f4ab030df0..c5acdc1402 100644 --- a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts @@ -73,6 +73,7 @@ const fixtureSpec = () => { const derived = deriveApiCommands({ spec: fixtureSpec(), generated: Object.keys(FIXTURE_OPERATIONS), + pollTargets: {}, nouns: { fixture: fixtureNoun }, operationIdMap: openApiOperationIdMap, handWrittenTopLevel: new Set(), diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index 7c7823ea88..8181339d26 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -106,6 +106,18 @@ export interface ApiCommandEntry { readonly wait?: ApiCommandWait; } +/** The operation a wait polls: a generated command's entry or a hidden {@link ApiPollTarget}. */ +export type ApiPollRead = Pick< + ApiCommandEntry, + "operationId" | "definition" | "summary" | "response" +>; + +/** A response-linked read used for polling without registering a CLI command. */ +export interface ApiPollTarget extends ApiPollRead { + /** Operation id of the generated command that inspects the state after a failed or timed-out wait. */ + readonly inspect: string; +} + /** OpenAPI schemas of one operation with every `$ref` inlined. */ export interface ApiCommandSchemas { readonly request?: { readonly contentType: "application/json"; readonly schema: unknown }; diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index 83f1247dfe..69e4233203 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -16,7 +16,7 @@ const REF = "abcdefghijklmnopqrst"; const ACCESS_TOKEN = `sbp_${"a".repeat(40)}`; const SEL = "ab".repeat(32); const ENABLE_PATH = `/v2/projects/${REF}/warehouse/enable`; -const STATUS_PATH = `/v2/projects/${REF}/warehouse/setups/current`; +const SETUP_PATH = `/v2/projects/${REF}/warehouse/setups/current`; const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); @@ -130,22 +130,42 @@ it.live("warehouse status reports a 409 as a conflict failure document on stderr }).pipe(Effect.provide(BunServices.layer)), ); -it.live("warehouse status keeps the API bytes when stdout is piped", () => +it.live("warehouse status keeps consolidated API bytes when stdout is piped", () => Effect.gen(function* () { - const { result } = yield* runWarehouse(["status"], () => statusBody("succeeded")); + const response = json(200, { + data: { + type: "warehouse_context", + id: REF, + attributes: { + enabled: true, + status: "ready", + configured_readiness: "ready", + query_connectivity: "not_checked", + tables: { status: "available", items: [] }, + replication: { status: "not_started", apply_lag: null }, + capabilities: { replication_add: false, replication_remove: false }, + }, + }, + }); + const { result, requests } = yield* runWarehouse(["status"], () => response); requireCliSuccess(result, "warehouse status"); - expect(result.stdout, result.stderr).toBe(statusBody("succeeded").body); + expect(result.stdout, result.stderr).toBe(response.body); + expect(requests).toEqual([`GET /v2/projects/${REF}/warehouse/status`]); }).pipe(Effect.provide(BunServices.layer)), ); -it.live("warehouse status --output-format text renders the response for people", () => +it.live("warehouse enable --wait --output-format text renders the final response for people", () => Effect.gen(function* () { - const { result } = yield* runWarehouse(["status", "--output-format", "text"], () => - statusBody("succeeded"), + const { result } = yield* runWarehouse( + ["enable", "--schema", "public", "--wait", "--yes", "--output-format", "text"], + (request) => + request.method === "POST" + ? json(202, { data: { attributes: { selection_id: SEL } } }) + : statusBody("succeeded"), ); - requireCliSuccess(result, "warehouse status --output-format text"); + requireCliSuccess(result, "warehouse enable --wait --output-format text"); expect(result.exitCode, result.stderr).toBe(0); expect( result.stdout.endsWith( @@ -186,7 +206,7 @@ it.live("warehouse enable --wait prints the final status read", () => requireCliSuccess(result, "warehouse enable --wait"); expect(result.stdout, result.stderr).toBe(statusBody("succeeded").body); - expect(requests).toEqual([`POST ${ENABLE_PATH}`, `GET ${STATUS_PATH}`]); + expect(requests).toEqual([`POST ${ENABLE_PATH}`, `GET ${SETUP_PATH}`]); }).pipe(Effect.provide(BunServices.layer)), ); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 3a32b50af5..ea9d7d249d 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -74,7 +74,8 @@ const enable = entryOf("warehouse enable"); const status = entryOf("warehouse status"); const ENABLE_PATH = `/v2/projects/${VALID_REF}/warehouse/enable`; -const STATUS_PATH = `/v2/projects/${VALID_REF}/warehouse/setups/current`; +const STATUS_PATH = `/v2/projects/${VALID_REF}/warehouse/status`; +const SETUP_PATH = `/v2/projects/${VALID_REF}/warehouse/setups/current`; const TARGET_LOOKUP_PATH = `/v1/projects/${VALID_REF}`; const SEL = "ab".repeat(32); @@ -304,6 +305,70 @@ const driveClock = (fiber: Fiber.Fiber) => Effect.raceFirst(Effect.forever(TestClock.adjust("2 seconds")), Fiber.await(fiber)); describe("generated warehouse commands", () => { + describe("consolidated warehouse status", () => { + const body = { + data: { + type: "warehouse_context", + id: VALID_REF, + attributes: { + enabled: true, + status: "degraded", + configured_readiness: "not_ready", + query_connectivity: "not_checked", + observed_at: "2026-11-17T10:00:00Z", + tables: { status: "available", items: [] }, + replication: { + status: "unavailable", + unavailable_reason: "observation_unavailable", + observed_at: null, + apply_lag: null, + }, + capabilities: { replication_add: false, replication_remove: true, table_resync: false }, + future_field: { retained: true }, + }, + }, + }; + + it.effect.each(["json", "yaml"] as const)( + "preserves zero targets, capabilities and unavailable observations as %s", + (format) => { + const { out, sent, run } = setup( + ["warehouse", "status", ...(format === "yaml" ? ["-o", "yaml"] : [])], + { route: ok(body) }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([ + { + method: "GET", + path: `/v2/projects/${VALID_REF}/warehouse/status`, + search: "", + body: undefined, + }, + ]); + expect( + format === "yaml" ? Bun.YAML.parse(out.stdoutText) : decodeJson(out.stdoutText), + ).toEqual(body); + expect(out.progressEvents).toEqual([]); + }); + }, + ); + + it.effect("labels configured readiness and unavailable observations in terminal output", () => { + const { out, run } = setup(["warehouse", "status"], { route: ok(body), stdoutIsTty: true }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toMatch(/Enabled\s+yes/); + expect(out.stdoutText).toMatch(/Configured readiness\s+not_ready/); + expect(out.stdoutText).toMatch(/Query connectivity\s+not_checked/); + expect(out.stdoutText).toMatch(/Status\s+unavailable/); + expect(out.stdoutText).toMatch(/Unavailable reason\s+observation_unavailable/); + expect(out.stdoutText).toMatch(/Replication add\s+no/); + expect(out.stdoutText).toMatch(/Replication remove\s+yes/); + expect(out.stdoutText).toMatch(/Observed at\s+2026-11-17T10:00:00Z/); + }); + }); + }); describe("warehouse disable", () => { const operationId = "7579647f-2cdc-466c-982e-425958a2f985"; const disablePath = `/v2/projects/${VALID_REF}/warehouse`; @@ -663,7 +728,7 @@ describe("generated warehouse commands", () => { ); it.effect("previews a read with a null body", () => { - const { out, run } = setup(["warehouse", "status", "--inspect-fdw", "false", "--dry-run"], { + const { out, run } = setup(["warehouse", "status", "--dry-run"], { route: ok({}), }); return Effect.gen(function* () { @@ -671,7 +736,7 @@ describe("generated warehouse commands", () => { expect(decodeJson(out.stdoutText)).toEqual({ method: "GET", path: STATUS_PATH, - query: { inspect_fdw: "false" }, + query: {}, headers: {}, body: null, }); @@ -894,27 +959,6 @@ describe("generated warehouse commands", () => { expect(Bun.YAML.parse(out.stdoutText)).toEqual(ACCEPTED); }); }); - - it.effect("sends status --inspect-fdw false as the inspect_fdw=false query", () => { - const { sent, out, run } = setup(["warehouse", "status", "--inspect-fdw", "false"], { - route: ok(statusBody("succeeded")), - }); - return Effect.gen(function* () { - yield* run; - expect(sent.map((request) => request.method)).toEqual(["GET"]); - expect(sent[0]?.path).toBe(STATUS_PATH); - expect(sent[0]?.search).toBe("inspect_fdw=false"); - expect(decodeJson(out.stdoutText)).toEqual(statusBody("succeeded")); - }); - }); - - it.effect("sends no query when no status flag is given", () => { - const { sent, run } = setup(["warehouse", "status"], { route: ok(statusBody("succeeded")) }); - return Effect.gen(function* () { - yield* run; - expect(sent[0]?.search).toBe(""); - }); - }); }); describe("help", () => { @@ -947,7 +991,7 @@ describe("generated warehouse commands", () => { yield* Fiber.join(fiber); const gets = sent.filter((request) => request.method === "GET"); expect(gets).toHaveLength(3); - expect(gets.every((request) => request.path === STATUS_PATH)).toBe(true); + expect(gets.every((request) => request.path === SETUP_PATH)).toBe(true); expect(gets.every((request) => request.search === `selection_id=${SEL}`)).toBe(true); expect(out.stdoutText).toBe(encodeJson(statusBody("succeeded"))); }); @@ -1071,26 +1115,32 @@ describe("generated warehouse commands", () => { }, ); - it.effect("names the status command when the setup fails and when the wait times out", () => { - const failing = setup(["warehouse", "enable", "--schema", "public", "--wait"], { - yes: true, - route: enableThenPoll([{ status: 200, body: statusBody("failed", "boom") }]), - }); - const stalling = setup( - ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "10s"], - { yes: true, route: enableThenPoll([{ status: 200, body: statusBody("pending") }]) }, - ); - const command = `supabase warehouse status --selection-id ${SEL} --remote=${VALID_REF}`; - return Effect.gen(function* () { - for (const { run } of [failing, stalling]) { - const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); - yield* driveClock(fiber); - expect(yield* Fiber.join(fiber)).toMatchObject({ - hint: expect.stringContaining(command), - }); - } - }); - }); + it.effect( + "points a failed or timed-out wait at warehouse status without exposing the internal setup read", + () => { + const failing = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([{ status: 200, body: statusBody("failed", "boom") }]), + }); + const stalling = setup( + ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "10s"], + { yes: true, route: enableThenPoll([{ status: 200, body: statusBody("pending") }]) }, + ); + const hint = `Check it with \`supabase warehouse status --remote=${VALID_REF}\`.`; + return Effect.gen(function* () { + for (const { run } of [failing, stalling]) { + const fiber = yield* run.pipe( + Effect.flip, + Effect.forkChild({ startImmediately: true }), + ); + yield* driveClock(fiber); + expect(yield* Fiber.join(fiber)).toMatchObject({ + hint, + }); + } + }); + }, + ); it.effect("prints the final status read as YAML under -o yaml", () => { const { out, run } = setup( @@ -1111,74 +1161,6 @@ describe("generated warehouse commands", () => { }); }); - describe("on a read that polls itself", () => { - const statusWait = ["warehouse", "status", "--wait"]; - const reads = (...replies: ReadonlyArray): Route => { - let read = 0; - return () => replies[Math.min(read++, replies.length - 1)] ?? { status: 200, body: {} }; - }; - - it.effect("polls its own route until the setup succeeds and prints the last read", () => { - const { sent, out, run } = setup(statusWait, { - route: reads( - { status: 200, body: statusBody("pending") }, - { status: 200, body: statusBody("pending") }, - { status: 200, body: statusBody("succeeded") }, - ), - }); - return Effect.gen(function* () { - const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); - yield* driveClock(fiber); - yield* Fiber.join(fiber); - expect(sent.map((request) => request.method)).toEqual(["GET", "GET", "GET"]); - expect(sent.every((request) => request.path === STATUS_PATH)).toBe(true); - expect(out.stdoutText).toBe(encodeJson(statusBody("succeeded"))); - }); - }); - - it.effect("fails with the reported status_error when the setup fails", () => { - const { run } = setup(statusWait, { - route: reads({ status: 200, body: statusBody("failed", "pipeline crashed") }), - }); - return Effect.gen(function* () { - const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); - yield* driveClock(fiber); - const failure = yield* Fiber.join(fiber); - expect(failure).toBeInstanceOf(ApiCommandOperationFailedError); - expect(failure).toMatchObject({ - message: expect.stringContaining("pipeline crashed"), - hint: expect.stringContaining(`supabase warehouse status --remote=${VALID_REF}`), - }); - }); - }); - - it.effect("times out and names the status command to check later", () => { - const { sent, run } = setup([...statusWait, "--timeout", "10s"], { - route: reads({ status: 200, body: statusBody("pending") }), - }); - return Effect.gen(function* () { - const fiber = yield* run.pipe(Effect.flip, Effect.forkChild({ startImmediately: true })); - yield* driveClock(fiber); - const failure = yield* Fiber.join(fiber); - expect(failure).toBeInstanceOf(ApiCommandWaitTimeoutError); - expect(failure).toMatchObject({ - hint: expect.stringContaining(`supabase warehouse status --remote=${VALID_REF}`), - }); - expect(sent.length).toBeGreaterThan(1); - }); - }); - - it.effect("sends nothing under --dry-run", () => { - const { sent, run } = setup([...statusWait, "--dry-run"], { - route: ok(statusBody("succeeded")), - }); - return Effect.gen(function* () { - yield* run; - expect(sent).toEqual([]); - }); - }); - }); - it.effect("rejects an invalid --timeout before sending anything", () => { const { sent, run } = setup( ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "soon"], @@ -1225,8 +1207,9 @@ describe("generated warehouse commands", () => { ].join("\n") + "\n"; it.effect("renders the status as text on a terminal by default", () => { - const { out, run } = setup(["warehouse", "status"], { - route: ok(RICH_STATUS), + const { out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), stdoutIsTty: true, }); return Effect.gen(function* () { @@ -1236,7 +1219,10 @@ describe("generated warehouse commands", () => { }); it.effect("keeps the API bytes by default when stdout is piped", () => { - const { out, run } = setup(["warehouse", "status"], { route: ok(RICH_STATUS) }); + const { out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), + }); return Effect.gen(function* () { yield* run; expect(out.stdoutText).toBe(encodeJson(RICH_STATUS)); @@ -1244,9 +1230,13 @@ describe("generated warehouse commands", () => { }); it.effect("renders text through a pipe when --output-format text is explicit", () => { - const { out, run } = setup(["warehouse", "status", "--output-format", "text"], { - route: ok(RICH_STATUS), - }); + const { out, run } = setup( + ["warehouse", "enable", "--schema", "public", "--wait", "--output-format", "text"], + { + yes: true, + route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), + }, + ); return Effect.gen(function* () { yield* run; expect(out.stdoutText).toBe(STATUS_TEXT); @@ -1257,8 +1247,23 @@ describe("generated warehouse commands", () => { "prints only the text rendering for -o pretty under --output-format stream-json", () => { const { out, run } = setup( - ["warehouse", "status", "-o", "pretty", "--output-format", "stream-json"], - { route: ok(RICH_STATUS), outputFormat: "stream-json", stdoutIsTty: true }, + [ + "warehouse", + "enable", + "--schema", + "public", + "--wait", + "-o", + "pretty", + "--output-format", + "stream-json", + ], + { + yes: true, + route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), + outputFormat: "stream-json", + stdoutIsTty: true, + }, ); return Effect.gen(function* () { yield* run; @@ -1269,10 +1274,14 @@ describe("generated warehouse commands", () => { ); it.effect("keeps the API bytes for -o json on a terminal", () => { - const { out, run } = setup(["warehouse", "status", "-o", "json"], { - route: ok(RICH_STATUS), - stdoutIsTty: true, - }); + const { out, run } = setup( + ["warehouse", "enable", "--schema", "public", "--wait", "-o", "json"], + { + yes: true, + route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), + stdoutIsTty: true, + }, + ); return Effect.gen(function* () { yield* run; expect(out.stdoutText).toBe(encodeJson(RICH_STATUS)); @@ -1287,7 +1296,7 @@ describe("generated warehouse commands", () => { return Effect.gen(function* () { yield* run; expect(out.progressEvents).toEqual([ - { type: "start", message: "Get Warehouse initial synchronization status" }, + { type: "start", message: "Get consolidated Warehouse status and capabilities" }, ]); expect(out.taskSettlements).toEqual([{ type: "clear" }]); }); @@ -1359,11 +1368,10 @@ describe("generated warehouse commands", () => { const { out, sent, run } = setup( [ "warehouse", - "status", - "--inspect-fdw", - "false", - "--selection-id", - SEL, + "teardowns", + "get", + "--operation-id", + "7579647f-2cdc-466c-982e-425958a2f985", "--dry-run", "--output-format", "text", @@ -1375,10 +1383,9 @@ describe("generated warehouse commands", () => { expect(sent).toEqual([]); expect(out.stdoutText).toBe( [ - `Dry run: GET ${STATUS_PATH}`, + `Dry run: GET /v2/projects/${VALID_REF}/warehouse/teardowns/current`, "Query", - " inspect_fdw false", - ` selection_id ${SEL}`, + " operation_id 7579647f-2cdc-466c-982e-425958a2f985", "", ].join("\n"), ); @@ -1471,13 +1478,14 @@ describe("generated warehouse commands", () => { ); const tree = commandTreeFor({ warehouseEnabled: true }); expect(tree.has("warehouse enable")).toBe(true); + expect(tree.has("warehouse setups get")).toBe(false); expect(tree.has("warehouse status")).toBe(true); }), ); it("marks each mounted leaf with its operation and experimental feature stage", () => { const tree = commandTreeFor({ warehouseEnabled: true }); - for (const entry of [enable, status]) { + for (const entry of apiCommands) { const command = tree.get(entry.command.join(" "))?.command; if (command === undefined) throw new Error(`${entry.command.join(" ")} is not mounted`); expect(Option.map(readApiCommand(command), (api) => api.operationId)).toEqual( diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index 31c6af8366..ec0b44652d 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -486,6 +486,411 @@ export const apiCommandSchemas = { required: ["data"], }, }, + "v2-get-warehouse-status": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + capabilities: { + description: + "Complete operations supported by this API, not caller authorization. Each operation still requires its feature, entitlement and project permission checks.", + properties: { + context: { + type: "boolean", + }, + query_explain: { + type: "boolean", + }, + replication_add: { + type: "boolean", + }, + replication_remove: { + type: "boolean", + }, + table_layout_read: { + type: "boolean", + }, + table_layout_update: { + type: "boolean", + }, + table_resync: { + type: "boolean", + }, + workload_metrics: { + type: "boolean", + }, + }, + required: [ + "context", + "query_explain", + "replication_add", + "replication_remove", + "table_layout_read", + "table_layout_update", + "table_resync", + "workload_metrics", + ], + type: "object", + }, + compute: { + description: + "Configured Warehouse compute and region, which may differ from the source database region. Live availability and capacity are not reported.", + properties: { + observed_at: { + description: + "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: ["string", "null"], + }, + region: { + type: ["string", "null"], + }, + routing_status: { + enum: ["error", null, "pending", "ready", "removed"], + type: ["string", "null"], + }, + status: { + enum: ["available", "not_provisioned", "unavailable"], + type: "string", + }, + unavailable_reason: { + enum: [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable", + ], + type: ["string", "null"], + }, + }, + required: [ + "observed_at", + "region", + "routing_status", + "status", + "unavailable_reason", + ], + type: "object", + }, + configured_readiness: { + description: + "Readiness inferred from configuration and replication observations; no query is executed.", + enum: ["not_ready", "ready", "unavailable"], + type: "string", + }, + enabled: { + description: + "Whether Warehouse is enabled, independently of selected table count. Null means provisioning could not be determined.", + type: ["boolean", "null"], + }, + lifecycle: { + properties: { + delete_data: { + type: "boolean", + }, + status: { + enum: ["deletion_failed", "disabled", "disabling"], + type: "string", + }, + updated_at: { + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: "string", + }, + }, + required: ["delete_data", "status", "updated_at"], + type: ["object", "null"], + }, + observed_at: { + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: "string", + }, + pipeline: { + properties: { + id: { + minLength: 1, + type: "string", + }, + observed_at: { + description: + "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: ["string", "null"], + }, + status: { + enum: [ + "failed", + "started", + "starting", + "stopped", + "stopping", + "unavailable", + "unknown", + ], + type: "string", + }, + unavailable_reason: { + enum: [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable", + ], + type: ["string", "null"], + }, + }, + required: ["id", "observed_at", "status", "unavailable_reason"], + type: ["object", "null"], + }, + project_ref: { + description: "Project ref", + maxLength: 20, + minLength: 20, + pattern: "^[a-z]+$", + type: "string", + examples: ["abcdefghijklmnopqrst"], + }, + query_connectivity: { + enum: ["not_checked"], + type: "string", + }, + replication: { + properties: { + apply_lag: { + description: + "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + properties: { + active: { + type: "boolean", + }, + feedback_age_ms: { + minimum: 0, + type: ["number", "null"], + }, + flush_lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + wal_status: { + enum: ["extended", "lost", null, "reserved", "unknown", "unreserved"], + type: ["string", "null"], + }, + write_lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + }, + required: [ + "active", + "feedback_age_ms", + "flush_lag_ms", + "wal_status", + "write_lag_ms", + ], + type: ["object", "null"], + }, + observed_at: { + description: + "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: ["string", "null"], + }, + status: { + enum: [ + "available", + "not_provisioned", + "not_started", + "stopped", + "unavailable", + ], + type: "string", + }, + unavailable_reason: { + enum: [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable", + ], + type: ["string", "null"], + }, + }, + required: ["apply_lag", "observed_at", "status", "unavailable_reason"], + type: "object", + }, + status: { + description: + "Warehouse setup and replication status. Ready means the Warehouse connection is configured and tables are replicating ongoing changes. It does not guarantee that a query will succeed.", + enum: [ + "degraded", + "disabled", + "disabling", + "not_provisioned", + "ready", + "starting", + "stopped", + "stopping", + "unavailable", + ], + type: "string", + }, + tables: { + properties: { + items: { + items: { + properties: { + id: { + maximum: 9007199254740991, + type: "integer", + exclusiveMinimum: 0, + }, + name: { + type: "string", + }, + replication_state: { + enum: [ + "copied_table", + "copying_table", + "error", + "following_wal", + null, + "queued", + ], + type: ["string", "null"], + }, + schema: { + type: "string", + }, + sync_lag: { + description: + "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + properties: { + active: { + type: "boolean", + }, + feedback_age_ms: { + minimum: 0, + type: ["number", "null"], + }, + flush_lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + wal_status: { + enum: [ + "extended", + "lost", + null, + "reserved", + "unknown", + "unreserved", + ], + type: ["string", "null"], + }, + write_lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + }, + required: [ + "active", + "feedback_age_ms", + "flush_lag_ms", + "wal_status", + "write_lag_ms", + ], + type: ["object", "null"], + }, + }, + required: ["id", "name", "replication_state", "schema", "sync_lag"], + type: "object", + }, + type: "array", + }, + observed_at: { + description: + "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: ["string", "null"], + }, + status: { + enum: ["available", "not_provisioned", "unavailable"], + type: "string", + }, + unavailable_reason: { + enum: [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable", + ], + type: ["string", "null"], + }, + }, + required: ["items", "observed_at", "status", "unavailable_reason"], + type: "object", + }, + }, + required: [ + "capabilities", + "compute", + "configured_readiness", + "enabled", + "lifecycle", + "observed_at", + "pipeline", + "project_ref", + "query_connectivity", + "replication", + "status", + "tables", + ], + type: "object", + }, + id: { + description: "Project ref", + maxLength: 20, + minLength: 20, + pattern: "^[a-z]+$", + type: "string", + examples: ["abcdefghijklmnopqrst"], + }, + type: { + description: "Resource type.", + enum: ["warehouse_context"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-get-warehouse-teardown": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index fbff6d8dba..832424107f 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -1,5 +1,5 @@ // Generated by scripts/generate-api-commands.ts. Do not edit. -import type { ApiCommandEntry } from "./api-command.model.ts"; +import type { ApiCommandEntry, ApiPollTarget } from "./api-command.model.ts"; export const apiCommands = [ { @@ -168,65 +168,27 @@ export const apiCommands = [ }, { command: ["warehouse", "status"], - operationId: "v2-get-warehouse-setup", - definition: "v2GetWarehouseSetup", + operationId: "v2-get-warehouse-status", + definition: "v2GetWarehouseStatus", method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/setups/current", - summary: "Get Warehouse initial synchronization status", + apiPath: "/v2/projects/{ref}/warehouse/status", + summary: "Get consolidated Warehouse status and capabilities", description: - "Returns setup phases, linked tables, pipeline and routing state, cleanup errors, and optional FDW inspection. Set inspect_fdw=false to skip database FDW inspection. A null table replication_state means no observation is available. Status succeeded requires initial copy, a running pipeline and ready routing; it does not verify query connectivity. Pass the selection_id returned by enable to reject a changed selection while waiting.", + "Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions.", readOnly: true, feature: "warehouse", response: { status: 200, kind: "json", }, - flags: [ - { - name: "inspect-fdw", - type: "string", - choices: ["true", "false"], - repeatable: false, - required: false, - description: - "Inspect database FDW state. Defaults to true for current-status reads and false when selection_id is supplied.", - }, - { - name: "selection-id", - type: "string", - repeatable: false, - required: false, - description: - "Accepted selection identity returned by enable. A different current nonempty selection returns a conflict.", - }, - ], + flags: [], bindings: [ { location: "path", name: "ref", source: "target", }, - { - location: "query", - name: "inspect_fdw", - source: "flag", - flag: "inspect-fdw", - }, - { - location: "query", - name: "selection_id", - source: "flag", - flag: "selection-id", - }, ], - wait: { - read: "v2-get-warehouse-setup", - params: {}, - status: "/data/attributes/status", - succeeded: ["succeeded"], - failed: ["failed"], - error: "/data/attributes/status_error", - }, }, { command: ["warehouse", "teardowns", "get"], @@ -276,3 +238,16 @@ export const apiCommands = [ }, }, ] as const satisfies readonly ApiCommandEntry[]; + +export const apiPollTargets = [ + { + operationId: "v2-get-warehouse-setup", + definition: "v2GetWarehouseSetup", + summary: "Get Warehouse initial synchronization status", + response: { + status: 200, + kind: "json", + }, + inspect: "v2-get-warehouse-status", + }, +] as const satisfies readonly ApiPollTarget[]; diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 536468aaa2..aa40f68f1a 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -45,8 +45,13 @@ import { readBodyOverride, } from "./api-command-request.ts"; import { withApiCommand } from "./api-command.annotation.ts"; -import type { ApiCommandEntry, ApiCommandFlag, ApiCommandWait } from "./api-command.model.ts"; -import { apiCommands } from "./generated.ts"; +import type { + ApiCommandEntry, + ApiCommandFlag, + ApiCommandWait, + ApiPollRead, +} from "./api-command.model.ts"; +import { apiCommands, apiPollTargets } from "./generated.ts"; const DEFAULT_WAIT_TIMEOUT = "10m"; const NANOSECONDS_PER_MILLISECOND = 1_000_000; @@ -59,7 +64,8 @@ const stageOf = (entry: ApiCommandEntry): CommandStage => ({ /** A command's `--wait`: the wait declared on its entry and the entry of the operation it polls. */ interface ResolvedWait { readonly wait: ApiCommandWait; - readonly readEntry: ApiCommandEntry; + readonly readEntry: ApiPollRead; + readonly statusEntry: ApiCommandEntry; } const resolveWait = ( @@ -68,8 +74,13 @@ const resolveWait = ( ): ResolvedWait | undefined => { const { wait } = entry; if (wait === undefined) return undefined; - const readEntry = entries.find((candidate) => candidate.operationId === wait.read); - return readEntry === undefined ? undefined : { wait, readEntry }; + const publicRead = entries.find((candidate) => candidate.operationId === wait.read); + if (publicRead !== undefined) return { wait, readEntry: publicRead, statusEntry: publicRead }; + const hidden = apiPollTargets.find((candidate) => candidate.operationId === wait.read); + const inspect = entries.find((candidate) => candidate.operationId === hidden?.inspect); + return hidden === undefined || inspect === undefined + ? undefined + : { wait, readEntry: hidden, statusEntry: inspect }; }; const flagLocation = (entry: ApiCommandEntry, flag: ApiCommandFlag): ApiFlagLocation => { @@ -145,7 +156,8 @@ const parseTimeoutMillis = (value: string) => ), ); -const summaryText = (entry: ApiCommandEntry): string => entry.summary.replace(/\.$/, ""); +const summaryText = (entry: Pick): string => + entry.summary.replace(/\.$/, ""); const OUTPUT_FORMATS: ReadonlyArray = ["json", "yaml", "pretty"]; @@ -263,6 +275,7 @@ const handle = Effect.fn("api-command.run")(function* ( waitForOperation({ wait: resolved.wait, readEntry: resolved.readEntry, + statusEntry: resolved.statusEntry, readInput, ref, timeoutMillis, diff --git a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md index 4d6362adee..fce91e4c38 100644 --- a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md @@ -87,7 +87,7 @@ API's JSON bytes. `-o` takes precedence over `--output-format`. | `-o json` | the same bytes; no `target` key is added | | `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | | `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview as JSON | +| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it @@ -96,6 +96,8 @@ message prints as a step line on stdout before the response. JSON and YAML outpu ## Notes +- `--wait` polls the setup endpoint internally; it does not expose a separate setup command, so a failed or timed-out wait carries the hint ``Check it with `supabase warehouse status --remote=`.`` + - Repeating the same selection is safe; the API rejects a different existing selection. - `--wait` fails only on a status in the failed set; `status_error` supplies the failure message and does not end the wait by itself. - `data.attributes.selection_id` is required in the accepted response; a response without it is a defect and ends `--wait` with an internal error, never a silent success. diff --git a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md index 1d5088c3a1..6a88659b56 100644 --- a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md @@ -28,29 +28,28 @@ The command is generated from the Management API contract (`generated.ts`). ## API Routes -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | --------------------------------------------- | ------------ | ------------ | --------------------------------------------------------------- | -| `GET` | `/v2/projects/{ref}/warehouse/setups/current` | Bearer token | none | passed through unchanged | -| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | linked-project cache miss only (best-effort, after the command) | +| Method | Path | Auth | Request body | Response (used fields) | +| ------ | ------------------------------------- | ------------ | ------------ | --------------------------------------------------------------- | +| `GET` | `/v2/projects/{ref}/warehouse/status` | Bearer token | none | passed through unchanged | +| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive | +| `GET` | `/v1/projects/{ref}` | Bearer token | none | linked-project cache miss only (best-effort, after the command) | -Query: `inspect_fdw=true|false` and `selection_id=`, each only when its flag was given. +No operation-specific query parameters or FDW inspection. `--dry-run` prints `{method, path, query, headers, body}` and sends no command request (the linked-project cache read in the table above can still run). -With `--wait` the command sends no change request: the first send is the first poll, and it polls -its own route with its own flags. Polling backs off from 1s, doubling to a 10s cap (a longer -`Retry-After` wins), until `data.attributes.status` is `succeeded` or `failed` or `--timeout` -(default `10m`) elapses. The output is the last read. Any non-2xx while polling ends the command -with the API error. +The response preserves enabled state independently of selected table count, configured readiness, +query connectivity, lifecycle, per-observation availability and capabilities. `observed_at` is +retrieval time; it is separate from table sync lag, pipeline apply lag and feedback age. +This read has no waiter. `warehouse enable --wait` observes enablement; `warehouse teardowns get --wait` +observes cleanup. Their operation identities and bounded waiting remain separate. ## Exit Codes -| Code | Condition | -| ---- | ------------------------------------------------------------------------------------------ | -| `0` | success (with `--wait`, the setup succeeded) | -| `2` | `usage_error`: invalid flags | -| `1` | API error (non-2xx, including 409) | -| `1` | with `--wait`: `operation_failed` (a failed status, with `status_error`) or `wait_timeout` | +| Code | Condition | +| ---- | ----------------------------------------------------------------------- | +| `0` | successful status read (including disabled or unavailable observations) | +| `2` | `usage_error`: invalid flags | +| `1` | API error (non-2xx, including 409) | A 4xx `entitlement_required` body (`{"error":{"code":"entitlement_required","feature","upgrade_url"}}`) adds `entitlement: {feature, upgrade_url}` to the stderr error document in place of the token-permission hint; a terminal run prints the upgrade hint, and `cli_upgrade_suggested` fires. Other statuses and bodies carry no `entitlement` key. @@ -72,8 +71,7 @@ A 4xx `entitlement_required` body (`{"error":{"code":"entitlement_required","fea | `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` -and `--wait` record `true`. Generated field flags (`--inspect-fdw`, `--selection-id`) and `--timeout` -are recorded as ``. +records `true`. ## Output @@ -81,16 +79,15 @@ Text rendering applies on a terminal by default, with `--output-format text` (al with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the API's JSON bytes. `-o` takes precedence over `--output-format`. -| Mode | stdout | -| ------------------------------ | --------------------------------------------------------------------------------------------------------- | -| text presentation | the response as labelled fields and tables; with `--wait` the last read; an empty response prints `Done.` | -| JSON presentation | the API's JSON response bytes, unchanged; with `--wait` the last read | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML | -| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview as JSON | - -When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the -whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it +| Mode | stdout | +| ------------------------------ | ----------------------------------------------------------------------------------- | +| text presentation | the response as labelled fields and tables; an empty response prints `Done.` | +| JSON presentation | the API's JSON response bytes, unchanged | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML | +| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | +| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | + +When the presentation is text and `--output-format` is `text`, the request runs under a task. On a terminal it is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task message prints as a step line on stdout before the response. JSON and YAML output show no progress. diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 68fbc15eff..7d2bbafc6b 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -490,5 +490,552 @@ "type": "object" }, "$comment": "The public Warehouse disablement and teardown contracts are not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1status", + "value": { + "get": { + "description": "Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-status", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseContextResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature or project metadata unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get consolidated Warehouse status and capabilities", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse", + "method": "status" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The consolidated Warehouse status contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseContextResponse_Output", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "capabilities": { + "description": "Complete operations supported by this API, not caller authorization. Each operation still requires its feature, entitlement and project permission checks.", + "properties": { + "context": { + "type": "boolean" + }, + "query_explain": { + "type": "boolean" + }, + "replication_add": { + "type": "boolean" + }, + "replication_remove": { + "type": "boolean" + }, + "table_layout_read": { + "type": "boolean" + }, + "table_layout_update": { + "type": "boolean" + }, + "table_resync": { + "type": "boolean" + }, + "workload_metrics": { + "type": "boolean" + } + }, + "required": [ + "context", + "query_explain", + "replication_add", + "replication_remove", + "table_layout_read", + "table_layout_update", + "table_resync", + "workload_metrics" + ], + "type": "object" + }, + "compute": { + "description": "Configured Warehouse compute and region, which may differ from the source database region. Live availability and capacity are not reported.", + "properties": { + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "region": { + "nullable": true, + "type": "string" + }, + "routing_status": { + "enum": ["error", null, "pending", "ready", "removed"], + "nullable": true, + "type": "string" + }, + "status": { + "enum": ["available", "not_provisioned", "unavailable"], + "type": "string" + }, + "unavailable_reason": { + "enum": [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable" + ], + "nullable": true, + "type": "string" + } + }, + "required": [ + "observed_at", + "region", + "routing_status", + "status", + "unavailable_reason" + ], + "type": "object" + }, + "configured_readiness": { + "description": "Readiness inferred from configuration and replication observations; no query is executed.", + "enum": ["not_ready", "ready", "unavailable"], + "type": "string" + }, + "enabled": { + "description": "Whether Warehouse is enabled, independently of selected table count. Null means provisioning could not be determined.", + "nullable": true, + "type": "boolean" + }, + "lifecycle": { + "nullable": true, + "properties": { + "delete_data": { + "type": "boolean" + }, + "status": { + "enum": ["deletion_failed", "disabled", "disabling"], + "type": "string" + }, + "updated_at": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + } + }, + "required": ["delete_data", "status", "updated_at"], + "type": "object" + }, + "observed_at": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "pipeline": { + "nullable": true, + "properties": { + "id": { + "minLength": 1, + "type": "string" + }, + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "status": { + "enum": [ + "failed", + "started", + "starting", + "stopped", + "stopping", + "unavailable", + "unknown" + ], + "type": "string" + }, + "unavailable_reason": { + "enum": [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable" + ], + "nullable": true, + "type": "string" + } + }, + "required": ["id", "observed_at", "status", "unavailable_reason"], + "type": "object" + }, + "project_ref": { + "description": "Project ref", + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + }, + "query_connectivity": { + "enum": ["not_checked"], + "type": "string" + }, + "replication": { + "properties": { + "apply_lag": { + "description": "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "nullable": true, + "properties": { + "active": { + "type": "boolean" + }, + "feedback_age_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "flush_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "wal_status": { + "enum": ["extended", "lost", null, "reserved", "unknown", "unreserved"], + "nullable": true, + "type": "string" + }, + "write_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + } + }, + "required": [ + "active", + "feedback_age_ms", + "flush_lag_ms", + "wal_status", + "write_lag_ms" + ], + "type": "object" + }, + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "status": { + "enum": [ + "available", + "not_provisioned", + "not_started", + "stopped", + "unavailable" + ], + "type": "string" + }, + "unavailable_reason": { + "enum": [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable" + ], + "nullable": true, + "type": "string" + } + }, + "required": ["apply_lag", "observed_at", "status", "unavailable_reason"], + "type": "object" + }, + "status": { + "description": "Warehouse setup and replication status. Ready means the Warehouse connection is configured and tables are replicating ongoing changes. It does not guarantee that a query will succeed.", + "enum": [ + "degraded", + "disabled", + "disabling", + "not_provisioned", + "ready", + "starting", + "stopped", + "stopping", + "unavailable" + ], + "type": "string" + }, + "tables": { + "properties": { + "items": { + "items": { + "properties": { + "id": { + "exclusiveMinimum": true, + "maximum": 9007199254740991, + "minimum": 0, + "type": "integer" + }, + "name": { + "type": "string" + }, + "replication_state": { + "enum": [ + "copied_table", + "copying_table", + "error", + "following_wal", + null, + "queued" + ], + "nullable": true, + "type": "string" + }, + "schema": { + "type": "string" + }, + "sync_lag": { + "description": "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "nullable": true, + "properties": { + "active": { + "type": "boolean" + }, + "feedback_age_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "flush_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "wal_status": { + "enum": [ + "extended", + "lost", + null, + "reserved", + "unknown", + "unreserved" + ], + "nullable": true, + "type": "string" + }, + "write_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + } + }, + "required": [ + "active", + "feedback_age_ms", + "flush_lag_ms", + "wal_status", + "write_lag_ms" + ], + "type": "object" + } + }, + "required": ["id", "name", "replication_state", "schema", "sync_lag"], + "type": "object" + }, + "type": "array" + }, + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "status": { + "enum": ["available", "not_provisioned", "unavailable"], + "type": "string" + }, + "unavailable_reason": { + "enum": [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable" + ], + "nullable": true, + "type": "string" + } + }, + "required": ["items", "observed_at", "status", "unavailable_reason"], + "type": "object" + } + }, + "required": [ + "capabilities", + "compute", + "configured_readiness", + "enabled", + "lifecycle", + "observed_at", + "pipeline", + "project_ref", + "query_connectivity", + "replication", + "status", + "tables" + ], + "type": "object" + }, + "id": { + "description": "Project ref", + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_context"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The consolidated Warehouse status contract is not yet in the deployed Management API specification." + }, + { + "op": "test", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1setups~1current/get/x-operation", + "value": { + "group": "warehouse", + "method": "status", + "poll": { + "status": "/data/attributes/status", + "succeeded": ["succeeded"], + "failed": ["failed"], + "error": "/data/attributes/status_error" + } + }, + "$comment": "The deployed specification still gives the setup read the `warehouse status` command identity, which the consolidated status operation now owns." + }, + { + "op": "replace", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1setups~1current/get/x-operation", + "value": { + "group": "warehouse.setups", + "method": "get", + "poll": { + "status": "/data/attributes/status", + "succeeded": ["succeeded"], + "failed": ["failed"], + "error": "/data/attributes/status_error" + } + } } ] diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 5a5782da0f..9b4b36f86d 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -14521,6 +14521,363 @@ export const V2GetWarehouseSetupOutput = Schema.Struct({ }), }), }); +export const V2GetWarehouseStatusInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), +}); +export const V2GetWarehouseStatusOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + capabilities: Schema.Struct({ + context: Schema.Boolean, + query_explain: Schema.Boolean, + replication_add: Schema.Boolean, + replication_remove: Schema.Boolean, + table_layout_read: Schema.Boolean, + table_layout_update: Schema.Boolean, + table_resync: Schema.Boolean, + workload_metrics: Schema.Boolean, + }).annotate({ + description: + "Complete operations supported by this API, not caller authorization. Each operation still requires its feature, entitlement and project permission checks.", + }), + compute: Schema.Struct({ + observed_at: Schema.Union([ + Schema.String.annotate({ + description: + "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + format: "date-time", + }), + Schema.Null, + ]), + region: Schema.Union([Schema.String, Schema.Null]), + routing_status: Schema.Union([ + Schema.Union([Schema.Literals(["error", "pending", "ready", "removed"]), Schema.Null]), + OpenString, + ]), + status: Schema.Union([ + Schema.Literals(["available", "not_provisioned", "unavailable"]), + OpenString, + ]), + unavailable_reason: Schema.Union([ + Schema.Union([ + Schema.Literals([ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + "observation_unavailable", + ]), + Schema.Null, + ]), + OpenString, + ]), + }).annotate({ + description: + "Configured Warehouse compute and region, which may differ from the source database region. Live availability and capacity are not reported.", + }), + configured_readiness: Schema.Union([ + Schema.Literals(["not_ready", "ready", "unavailable"]).annotate({ + description: + "Readiness inferred from configuration and replication observations; no query is executed.", + }), + OpenString, + ]), + enabled: Schema.Union([ + Schema.Boolean.annotate({ + description: + "Whether Warehouse is enabled, independently of selected table count. Null means provisioning could not be determined.", + }), + Schema.Null, + ]), + lifecycle: Schema.Union([ + Schema.Struct({ + delete_data: Schema.Boolean, + status: Schema.Union([ + Schema.Literals(["deletion_failed", "disabled", "disabling"]), + OpenString, + ]), + updated_at: Schema.String.annotate({ format: "date-time" }), + }), + Schema.Null, + ]), + observed_at: Schema.String.annotate({ format: "date-time" }), + pipeline: Schema.Union([ + Schema.Struct({ + id: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + observed_at: Schema.Union([ + Schema.String.annotate({ + description: + "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + format: "date-time", + }), + Schema.Null, + ]), + status: Schema.Union([ + Schema.Literals([ + "failed", + "started", + "starting", + "stopped", + "stopping", + "unavailable", + "unknown", + ]), + OpenString, + ]), + unavailable_reason: Schema.Union([ + Schema.Union([ + Schema.Literals([ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + "observation_unavailable", + ]), + Schema.Null, + ]), + OpenString, + ]), + }), + Schema.Null, + ]), + project_ref: Schema.String.annotate({ description: "Project ref" }) + .check( + Schema.isMinCodePoints(20).annotate({ + expected: "a string with at least 20 code points", + }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + query_connectivity: Schema.Literal("not_checked"), + replication: Schema.Struct({ + apply_lag: Schema.Union([ + Schema.Struct({ + active: Schema.Boolean, + feedback_age_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + flush_lag_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + wal_status: Schema.Union([ + Schema.Union([ + Schema.Literals(["extended", "lost", "reserved", "unknown", "unreserved"]), + Schema.Null, + ]), + OpenString, + ]), + write_lag_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + }).annotate({ + description: + "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + }), + Schema.Null, + ]), + observed_at: Schema.Union([ + Schema.String.annotate({ + description: + "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + format: "date-time", + }), + Schema.Null, + ]), + status: Schema.Union([ + Schema.Literals([ + "available", + "not_provisioned", + "not_started", + "stopped", + "unavailable", + ]), + OpenString, + ]), + unavailable_reason: Schema.Union([ + Schema.Union([ + Schema.Literals([ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + "observation_unavailable", + ]), + Schema.Null, + ]), + OpenString, + ]), + }), + status: Schema.Union([ + Schema.Literals([ + "degraded", + "disabled", + "disabling", + "not_provisioned", + "ready", + "starting", + "stopped", + "stopping", + "unavailable", + ]).annotate({ + description: + "Warehouse setup and replication status. Ready means the Warehouse connection is configured and tables are replicating ongoing changes. It does not guarantee that a query will succeed.", + }), + OpenString, + ]), + tables: Schema.Struct({ + items: Schema.Array( + Schema.Struct({ + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + name: Schema.String, + replication_state: Schema.Union([ + Schema.Union([ + Schema.Literals([ + "copied_table", + "copying_table", + "error", + "following_wal", + "queued", + ]), + Schema.Null, + ]), + OpenString, + ]), + schema: Schema.String, + sync_lag: Schema.Union([ + Schema.Struct({ + active: Schema.Boolean, + feedback_age_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + flush_lag_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + wal_status: Schema.Union([ + Schema.Union([ + Schema.Literals(["extended", "lost", "reserved", "unknown", "unreserved"]), + Schema.Null, + ]), + OpenString, + ]), + write_lag_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + }).annotate({ + description: + "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + }), + Schema.Null, + ]), + }), + ), + observed_at: Schema.Union([ + Schema.String.annotate({ + description: + "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + format: "date-time", + }), + Schema.Null, + ]), + status: Schema.Union([ + Schema.Literals(["available", "not_provisioned", "unavailable"]), + OpenString, + ]), + unavailable_reason: Schema.Union([ + Schema.Union([ + Schema.Literals([ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + "observation_unavailable", + ]), + Schema.Null, + ]), + OpenString, + ]), + }), + }), + id: Schema.String.annotate({ description: "Project ref" }) + .check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + type: Schema.Literal("warehouse_context").annotate({ description: "Resource type." }), + }), +}); export const V2GetWarehouseTeardownInput = Schema.Struct({ operation_id: Schema.optionalKey( Schema.String.annotate({ format: "uuid" }).check( @@ -19582,6 +19939,7 @@ export const openApiOperationIdMap = { "v2-get-notebook": "v2GetNotebook", "v2-get-project-config": "v2GetProjectConfig", "v2-get-warehouse-setup": "v2GetWarehouseSetup", + "v2-get-warehouse-status": "v2GetWarehouseStatus", "v2-get-warehouse-teardown": "v2GetWarehouseTeardown", "v2-list-all-compute-instances": "v2ListAllComputeInstances", "v2-list-log-drains": "v2ListLogDrains", @@ -22769,6 +23127,20 @@ export const operationDefinitions = { inputSchema: V2GetWarehouseSetupInput, outputSchema: V2GetWarehouseSetupOutput, }, + v2GetWarehouseStatus: { + id: "v2GetWarehouseStatus", + description: + "Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/status", + pathParams: ["ref"], + queryParams: [], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2GetWarehouseStatusInput, + outputSchema: V2GetWarehouseStatusOutput, + }, v2GetWarehouseTeardown: { id: "v2GetWarehouseTeardown", description: diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index dc9c08a3c4..705dd7770b 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -3108,6 +3108,22 @@ export const versionedEffectOperations = { options, ); }), + getWarehouseStatus: ( + input: typeof operationDefinitions.v2GetWarehouseStatus.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2GetWarehouseStatus.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2GetWarehouseStatus">( + operationDefinitions.v2GetWarehouseStatus, + input, + options, + ); + }), getWarehouseTeardown: ( input: typeof operationDefinitions.v2GetWarehouseTeardown.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index 3f46194615..febd74ac9b 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -12262,8 +12262,8 @@ "x-fga-permissions": [["database_read"]], "x-oauth-scope": "database:read", "x-operation": { - "group": "warehouse", - "method": "status", + "group": "warehouse.setups", + "method": "get", "poll": { "status": "/data/attributes/status", "succeeded": ["succeeded"], @@ -32661,6 +32661,104 @@ }, "x-scalar-stability": "experimental" } + }, + "/v2/projects/{ref}/warehouse/status": { + "get": { + "description": "Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-status", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseContextResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature or project metadata unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get consolidated Warehouse status and capabilities", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse", + "method": "status" + }, + "x-scalar-stability": "experimental" + } } }, "components": { @@ -48010,6 +48108,416 @@ }, "required": ["data"], "type": "object" + }, + "V2WarehouseContextResponse_Output": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "capabilities": { + "description": "Complete operations supported by this API, not caller authorization. Each operation still requires its feature, entitlement and project permission checks.", + "properties": { + "context": { + "type": "boolean" + }, + "query_explain": { + "type": "boolean" + }, + "replication_add": { + "type": "boolean" + }, + "replication_remove": { + "type": "boolean" + }, + "table_layout_read": { + "type": "boolean" + }, + "table_layout_update": { + "type": "boolean" + }, + "table_resync": { + "type": "boolean" + }, + "workload_metrics": { + "type": "boolean" + } + }, + "required": [ + "context", + "query_explain", + "replication_add", + "replication_remove", + "table_layout_read", + "table_layout_update", + "table_resync", + "workload_metrics" + ], + "type": "object" + }, + "compute": { + "description": "Configured Warehouse compute and region, which may differ from the source database region. Live availability and capacity are not reported.", + "properties": { + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "region": { + "nullable": true, + "type": "string" + }, + "routing_status": { + "enum": ["error", null, "pending", "ready", "removed"], + "nullable": true, + "type": "string" + }, + "status": { + "enum": ["available", "not_provisioned", "unavailable"], + "type": "string" + }, + "unavailable_reason": { + "enum": [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable" + ], + "nullable": true, + "type": "string" + } + }, + "required": [ + "observed_at", + "region", + "routing_status", + "status", + "unavailable_reason" + ], + "type": "object" + }, + "configured_readiness": { + "description": "Readiness inferred from configuration and replication observations; no query is executed.", + "enum": ["not_ready", "ready", "unavailable"], + "type": "string" + }, + "enabled": { + "description": "Whether Warehouse is enabled, independently of selected table count. Null means provisioning could not be determined.", + "nullable": true, + "type": "boolean" + }, + "lifecycle": { + "nullable": true, + "properties": { + "delete_data": { + "type": "boolean" + }, + "status": { + "enum": ["deletion_failed", "disabled", "disabling"], + "type": "string" + }, + "updated_at": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + } + }, + "required": ["delete_data", "status", "updated_at"], + "type": "object" + }, + "observed_at": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "pipeline": { + "nullable": true, + "properties": { + "id": { + "minLength": 1, + "type": "string" + }, + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "status": { + "enum": [ + "failed", + "started", + "starting", + "stopped", + "stopping", + "unavailable", + "unknown" + ], + "type": "string" + }, + "unavailable_reason": { + "enum": [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable" + ], + "nullable": true, + "type": "string" + } + }, + "required": ["id", "observed_at", "status", "unavailable_reason"], + "type": "object" + }, + "project_ref": { + "description": "Project ref", + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + }, + "query_connectivity": { + "enum": ["not_checked"], + "type": "string" + }, + "replication": { + "properties": { + "apply_lag": { + "description": "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "nullable": true, + "properties": { + "active": { + "type": "boolean" + }, + "feedback_age_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "flush_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "wal_status": { + "enum": ["extended", "lost", null, "reserved", "unknown", "unreserved"], + "nullable": true, + "type": "string" + }, + "write_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + } + }, + "required": [ + "active", + "feedback_age_ms", + "flush_lag_ms", + "wal_status", + "write_lag_ms" + ], + "type": "object" + }, + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "status": { + "enum": [ + "available", + "not_provisioned", + "not_started", + "stopped", + "unavailable" + ], + "type": "string" + }, + "unavailable_reason": { + "enum": [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable" + ], + "nullable": true, + "type": "string" + } + }, + "required": ["apply_lag", "observed_at", "status", "unavailable_reason"], + "type": "object" + }, + "status": { + "description": "Warehouse setup and replication status. Ready means the Warehouse connection is configured and tables are replicating ongoing changes. It does not guarantee that a query will succeed.", + "enum": [ + "degraded", + "disabled", + "disabling", + "not_provisioned", + "ready", + "starting", + "stopped", + "stopping", + "unavailable" + ], + "type": "string" + }, + "tables": { + "properties": { + "items": { + "items": { + "properties": { + "id": { + "exclusiveMinimum": true, + "maximum": 9007199254740991, + "minimum": 0, + "type": "integer" + }, + "name": { + "type": "string" + }, + "replication_state": { + "enum": [ + "copied_table", + "copying_table", + "error", + "following_wal", + null, + "queued" + ], + "nullable": true, + "type": "string" + }, + "schema": { + "type": "string" + }, + "sync_lag": { + "description": "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "nullable": true, + "properties": { + "active": { + "type": "boolean" + }, + "feedback_age_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "flush_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "wal_status": { + "enum": [ + "extended", + "lost", + null, + "reserved", + "unknown", + "unreserved" + ], + "nullable": true, + "type": "string" + }, + "write_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + } + }, + "required": [ + "active", + "feedback_age_ms", + "flush_lag_ms", + "wal_status", + "write_lag_ms" + ], + "type": "object" + } + }, + "required": ["id", "name", "replication_state", "schema", "sync_lag"], + "type": "object" + }, + "type": "array" + }, + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "status": { + "enum": ["available", "not_provisioned", "unavailable"], + "type": "string" + }, + "unavailable_reason": { + "enum": [ + "assignment_unavailable", + "cleanup_failed", + "cleanup_in_progress", + "identity_mismatch", + null, + "observation_unavailable" + ], + "nullable": true, + "type": "string" + } + }, + "required": ["items", "observed_at", "status", "unavailable_reason"], + "type": "object" + } + }, + "required": [ + "capabilities", + "compute", + "configured_readiness", + "enabled", + "lifecycle", + "observed_at", + "pipeline", + "project_ref", + "query_connectivity", + "replication", + "status", + "tables" + ], + "type": "object" + }, + "id": { + "description": "Project ref", + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_context"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index 8ffde8ee89..b8db833a8c 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -448,4 +448,5 @@ export const operationPermissions: Readonly oauthScope: "database:write", }, "v2-get-warehouse-teardown": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-get-warehouse-status": { fga: [["database_read"]], oauthScope: "database:read" }, }; From a03779a08e18789861ca9fa9229e9b73c532052f Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Tue, 17 Nov 2026 22:22:10 +0100 Subject: [PATCH 11/45] feat(cli): add warehouse connection (#7674) Generate `warehouse connection` from `GET /v2/projects/{ref}/warehouse/connection`. It prints the Arrow Flight SQL endpoint, the TLS requirement and source-database login guidance: use a database role with its existing password (`postgres` uses the project's database password) and `supabase_warehouse_reader` membership. The command never fetches or prints a password, and a disabled, unconfigured or unavailable Warehouse shows no connection string. Text output on terminals, raw JSON when piped or requested, and YAML through `-o yaml`, as for the other generated Warehouse commands. Help includes a usql recipe. Add `connection` to the generated command vocabulary and render `TLS` as an acronym in text labels. The contract comes from an OpenAPI override until it ships in the deployed Management API specification. Stacked on #7671. Depends on https://github.com/supabase/platform/pull/42053. Implements PIPE-1449. --------- Co-authored-by: Julien Goux --- .../command-surface.integration.test.ts | 1 + .../src/commands/api/api-command-policy.ts | 2 + .../src/commands/api/api-command.format.ts | 2 +- .../api/api-commands.integration.test.ts | 80 ++++++ .../cli/src/commands/api/generated.schemas.ts | 171 +++++++++++ apps/cli/src/commands/api/generated.ts | 24 ++ .../api/warehouse/connection/SIDE_EFFECTS.md | 101 +++++++ packages/api/scripts/openapi-overrides.json | 272 ++++++++++++++++++ packages/api/src/generated/contracts.ts | 158 ++++++++++ packages/api/src/generated/effect-client.ts | 16 ++ packages/api/src/generated/openapi.json | 262 +++++++++++++++++ packages/api/src/generated/permissions.ts | 1 + 12 files changed, 1089 insertions(+), 1 deletion(-) create mode 100644 apps/cli/src/commands/api/warehouse/connection/SIDE_EFFECTS.md diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 65849c9297..2b21c585a9 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -46,6 +46,7 @@ describe("command surface", () => { const { variants } = yield* Effect.promise(() => surface); expect(Object.keys(variants.warehouse)).toEqual([ "warehouse", + "warehouse connection", "warehouse disable", "warehouse enable", "warehouse status", diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index a3b190738c..0c94918cf0 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -11,6 +11,7 @@ export const verbVocabulary = [ "enable", "disable", "status", + "connection", "add", "remove", "resync", @@ -30,6 +31,7 @@ export type ApiCommandPoll = Pick = [ "v2-get-warehouse-status", + "v2-get-warehouse-connection", "v2-enable-warehouse", "v2-disable-warehouse", "v2-get-warehouse-teardown", diff --git a/apps/cli/src/commands/api/api-command.format.ts b/apps/cli/src/commands/api/api-command.format.ts index a877488dce..b4d08c4c41 100644 --- a/apps/cli/src/commands/api/api-command.format.ts +++ b/apps/cli/src/commands/api/api-command.format.ts @@ -2,7 +2,7 @@ import { renderGlamourTable } from "../../output/glamour-table.ts"; import type { ApiRequestPreview } from "./api-command-request.ts"; const INDENT = " "; -const ACRONYMS: ReadonlySet = new Set(["id", "url", "fdw", "dns", "api", "sql"]); +const ACRONYMS: ReadonlySet = new Set(["id", "url", "fdw", "dns", "api", "sql", "tls"]); type JsonObject = Readonly>; diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index ea9d7d249d..7a99c0d7ce 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -369,6 +369,86 @@ describe("generated warehouse commands", () => { }); }); }); + describe("warehouse connection", () => { + const connectionPath = `/v2/projects/${VALID_REF}/warehouse/connection`; + const host = `${VALID_REF}.warehouse.example.invalid`; + const connection = (attributes: Readonly>) => ({ + data: { + type: "warehouse_connection", + id: VALID_REF, + attributes: { + project_ref: VALID_REF, + observed_at: "2026-11-17T10:00:00Z", + protocol: "arrow_flight_sql", + tls_required: true, + authentication: { + method: "database_username_password", + credential_source: "source_project_database", + default_username: "postgres", + password_guidance: + "Use the same password as this role in the source Supabase database. For postgres, use the project's database password.", + required_membership: "supabase_warehouse_reader", + }, + access_mode: "read_only", + query_connectivity: "not_checked", + ...attributes, + }, + }, + }); + + it.effect("prints the endpoint and source database login guidance from a single read", () => { + const body = connection({ + status: "available", + unavailable_reason: null, + endpoint: `grpc+tls://${host}:443`, + host, + port: 443, + region: "eu-central-1", + routing_status: "ready", + }); + const { out, sent, run } = setup(["warehouse", "connection"], { + route: ok(body), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([ + { method: "GET", path: connectionPath, search: "", body: undefined }, + ]); + expect(out.stdoutText).toMatch(/^Warehouse connection$/m); + expect(out.stdoutText).toMatch(/Status\s+available/); + expect(out.stdoutText).toContain(`grpc+tls://${host}:443`); + expect(out.stdoutText).toMatch(/TLS required\s+yes/); + expect(out.stdoutText).toMatch(/Default username\s+postgres/); + expect(out.stdoutText).toMatch(/Password guidance\s+Use the same password as this role/); + expect(out.stdoutText).toMatch(/Required membership\s+supabase_warehouse_reader/); + expect(out.stdoutText).toMatch(/Query connectivity\s+not_checked/); + }); + }); + + it.effect("shows no connection string for an unconfigured Warehouse", () => { + const body = connection({ + status: "not_configured", + unavailable_reason: null, + endpoint: null, + host: null, + port: null, + region: null, + routing_status: null, + }); + const { out, run } = setup(["warehouse", "connection"], { + route: ok(body), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toMatch(/Status\s+not_configured/); + expect(out.stdoutText).toMatch(/Endpoint\s+-$/m); + expect(out.stdoutText).toMatch(/Host\s+-$/m); + expect(out.stdoutText).not.toMatch(/grpc\+tls|flightsql:/); + }); + }); + }); describe("warehouse disable", () => { const operationId = "7579647f-2cdc-466c-982e-425958a2f985"; const disablePath = `/v2/projects/${VALID_REF}/warehouse`; diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index ec0b44652d..ea2a56d29d 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -246,6 +246,177 @@ export const apiCommandSchemas = { required: ["data"], }, }, + "v2-get-warehouse-connection": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + access_mode: { + enum: ["read_only"], + type: "string", + }, + authentication: { + description: + "How to authenticate. No credentials are returned; the password is never exposed by this API.", + properties: { + credential_source: { + enum: ["source_project_database"], + type: "string", + }, + default_username: { + enum: ["postgres"], + type: "string", + }, + membership_guidance: { + type: "string", + }, + method: { + enum: ["database_username_password"], + type: "string", + }, + password_guidance: { + type: "string", + }, + required_membership: { + enum: ["supabase_warehouse_reader"], + type: "string", + }, + }, + required: [ + "credential_source", + "default_username", + "membership_guidance", + "method", + "password_guidance", + "required_membership", + ], + type: "object", + }, + endpoint: { + description: + "Arrow Flight SQL URI, grpc+tls://:443. Null unless status is available or pending.", + type: ["string", "null"], + }, + host: { + description: + "Public hostname of the Flight SQL endpoint. Null unless status is available or pending.", + type: ["string", "null"], + }, + observed_at: { + description: + "Time the API retrieved this information. This timestamp does not indicate when connectivity was last verified.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: "string", + }, + port: { + description: + "Public TLS port of the Flight SQL endpoint. Null unless status is available or pending.", + maximum: 9007199254740991, + minimum: -9007199254740991, + type: ["integer", "null"], + }, + project_ref: { + description: "Project ref", + maxLength: 20, + minLength: 20, + pattern: "^[a-z]+$", + type: "string", + examples: ["abcdefghijklmnopqrst"], + }, + protocol: { + enum: ["arrow_flight_sql"], + type: "string", + }, + query_connectivity: { + enum: ["not_checked"], + type: "string", + }, + region: { + description: + "Assigned Warehouse compute region, which may differ from the source database region. Null when the project has no project-specific route.", + type: ["string", "null"], + }, + routing_status: { + description: + "DNS delivery status of the project route. Null when the project uses the shared legacy route.", + enum: ["error", null, "pending", "ready", "removed"], + type: ["string", "null"], + }, + status: { + description: + "Configured availability of the Warehouse endpoint, derived from routing and lifecycle state. It is not a connectivity probe: a ready route does not prove a query will succeed.", + enum: [ + "available", + "disabled", + "disabling", + "not_configured", + "pending", + "unavailable", + ], + type: "string", + }, + tls_required: { + enum: [true], + type: "boolean", + }, + unavailable_reason: { + description: + "Why the endpoint is unavailable. Null unless status is unavailable.", + enum: [ + "assignment_unavailable", + "cleanup_failed", + null, + "observation_unavailable", + "routing_failed", + ], + type: ["string", "null"], + }, + }, + required: [ + "access_mode", + "authentication", + "endpoint", + "host", + "observed_at", + "port", + "project_ref", + "protocol", + "query_connectivity", + "region", + "routing_status", + "status", + "tls_required", + "unavailable_reason", + ], + type: "object", + }, + id: { + description: "Project ref", + maxLength: 20, + minLength: 20, + pattern: "^[a-z]+$", + type: "string", + examples: ["abcdefghijklmnopqrst"], + }, + type: { + description: "Resource type.", + enum: ["warehouse_connection"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-get-warehouse-setup": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 832424107f..dd7c0ea679 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -2,6 +2,30 @@ import type { ApiCommandEntry, ApiPollTarget } from "./api-command.model.ts"; export const apiCommands = [ + { + command: ["warehouse", "connection"], + operationId: "v2-get-warehouse-connection", + definition: "v2GetWarehouseConnection", + method: "GET", + apiPath: "/v2/projects/{ref}/warehouse/connection", + summary: "Get Warehouse Flight SQL connection details", + description: + "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.", + readOnly: true, + feature: "warehouse", + response: { + status: 200, + kind: "json", + }, + flags: [], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + ], + }, { command: ["warehouse", "disable"], operationId: "v2-disable-warehouse", diff --git a/apps/cli/src/commands/api/warehouse/connection/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/connection/SIDE_EFFECTS.md new file mode 100644 index 0000000000..27d8bba8e6 --- /dev/null +++ b/apps/cli/src/commands/api/warehouse/connection/SIDE_EFFECTS.md @@ -0,0 +1,101 @@ +# `supabase warehouse connection` + +Target: hosted, no consent, see [Command target](../../../../../docs/command-target.md) + +## Feature gate + +Registered only when `experimental.warehouse` is enabled: set `[experimental] warehouse = true` or +`SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. `--experimental` alone does not expose it. When disabled the +`warehouse` group is absent from help and completion and from the generated command documentation. +The command is generated from the Management API contract (`generated.ts`). + +## Files Read + +| Path | Format | When | +| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | +| `/supabase/config.json` | JSON | when present, to resolve `experimental.warehouse` before the command tree is built | +| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | +| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential | +| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | +| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | + +## Files Written + +| Path | Format | When | +| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | +| `/telemetry.json` | JSON | always, flushed on success and on failure | +| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref | + +## API Routes + +| Method | Path | Auth | Request body | Response (used fields) | +| ------ | ----------------------------------------- | ------------ | ------------ | --------------------------------------------------------------- | +| `GET` | `/v2/projects/{ref}/warehouse/connection` | Bearer token | none | passed through unchanged | +| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive | +| `GET` | `/v1/projects/{ref}` | Bearer token | none | linked-project cache miss only (best-effort, after the command) | + +No operation-specific query parameters. The command never requests or prints a password, token or +catalog credential, and does not run a Flight SQL query: `query_connectivity` stays `not_checked`. +`--dry-run` prints `{method, path, query, headers, body}` and sends no command request (the linked-project cache read in the table above can still run). + +The response describes Arrow Flight SQL access only; DuckLake catalog access is a separate contract. +`endpoint`, `host` and `port` are present only while `status` is `available` or `pending`; a +disabled, unconfigured or unavailable Warehouse prints `-` for them instead of a connection string. + +## Connecting + +Log in as a role in the source Supabase database with that role's existing password; `postgres` +uses the project's database password. The role needs `supabase_warehouse_reader` membership in the +source database, which Management API access does not grant. With +[usql](https://github.com/xo/usql), using the `host` from the output: + +```sh +usql -W 'flightsql://postgres@:443?tls=enabled' +``` + +## Exit Codes + +| Code | Condition | +| ---- | ----------------------------------------------------------------------------- | +| `0` | successful read (including not configured, disabled or unavailable Warehouse) | +| `2` | `usage_error`: invalid flags | +| `1` | API error (non-2xx) | + +## Environment Variables + +| Variable | Purpose | Required? | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | +| `SUPABASE_EXPERIMENTAL_WAREHOUSE` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.warehouse`) | no | +| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | +| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | +| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to `supabase/.temp/project-ref`) | +| `SUPABASE_WORKDIR` | project directory the command acts on | no (falls back to `--workdir`, then the cwd) | +| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) | + +## Telemetry Events Fired + +| Event | When | Notable properties / groups | +| ---------------------- | ------------------------------------------ | ----------------------------------- | +| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | + +Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` +records `true`. + +## Output + +Text rendering applies on a terminal by default, with `--output-format text` (also when piped), and +with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the +API's JSON bytes. `-o` takes precedence over `--output-format`. + +| Mode | stdout | +| ------------------------------ | ----------------------------------------------------------------------------------- | +| text presentation | the response as labelled fields, with authentication guidance as a nested block | +| JSON presentation | the API's JSON response bytes, unchanged | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML | +| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | +| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | + +When the presentation is text and `--output-format` is `text`, the request runs under a task. On a terminal it +is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task +message prints as a step line on stdout before the response. JSON and YAML output show no progress. diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 7d2bbafc6b..6f954c365e 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -1009,6 +1009,278 @@ }, "$comment": "The consolidated Warehouse status contract is not yet in the deployed Management API specification." }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1connection", + "value": { + "get": { + "description": "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-connection", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseConnectionResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature or project metadata unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get Warehouse Flight SQL connection details", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse", + "method": "connection" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The Warehouse Flight SQL connection contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseConnectionResponse_Output", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "access_mode": { + "enum": ["read_only"], + "type": "string" + }, + "authentication": { + "description": "How to authenticate. No credentials are returned; the password is never exposed by this API.", + "properties": { + "credential_source": { + "enum": ["source_project_database"], + "type": "string" + }, + "default_username": { + "enum": ["postgres"], + "type": "string" + }, + "membership_guidance": { + "type": "string" + }, + "method": { + "enum": ["database_username_password"], + "type": "string" + }, + "password_guidance": { + "type": "string" + }, + "required_membership": { + "enum": ["supabase_warehouse_reader"], + "type": "string" + } + }, + "required": [ + "credential_source", + "default_username", + "membership_guidance", + "method", + "password_guidance", + "required_membership" + ], + "type": "object" + }, + "endpoint": { + "description": "Arrow Flight SQL URI, grpc+tls://:443. Null unless status is available or pending.", + "nullable": true, + "type": "string" + }, + "host": { + "description": "Public hostname of the Flight SQL endpoint. Null unless status is available or pending.", + "nullable": true, + "type": "string" + }, + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when connectivity was last verified.", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "port": { + "description": "Public TLS port of the Flight SQL endpoint. Null unless status is available or pending.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "nullable": true, + "type": "integer" + }, + "project_ref": { + "description": "Project ref", + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + }, + "protocol": { + "enum": ["arrow_flight_sql"], + "type": "string" + }, + "query_connectivity": { + "enum": ["not_checked"], + "type": "string" + }, + "region": { + "description": "Assigned Warehouse compute region, which may differ from the source database region. Null when the project has no project-specific route.", + "nullable": true, + "type": "string" + }, + "routing_status": { + "description": "DNS delivery status of the project route. Null when the project uses the shared legacy route.", + "enum": ["error", null, "pending", "ready", "removed"], + "nullable": true, + "type": "string" + }, + "status": { + "description": "Configured availability of the Warehouse endpoint, derived from routing and lifecycle state. It is not a connectivity probe: a ready route does not prove a query will succeed.", + "enum": [ + "available", + "disabled", + "disabling", + "not_configured", + "pending", + "unavailable" + ], + "type": "string" + }, + "tls_required": { + "enum": [true], + "type": "boolean" + }, + "unavailable_reason": { + "description": "Why the endpoint is unavailable. Null unless status is unavailable.", + "enum": [ + "assignment_unavailable", + "cleanup_failed", + null, + "observation_unavailable", + "routing_failed" + ], + "nullable": true, + "type": "string" + } + }, + "required": [ + "access_mode", + "authentication", + "endpoint", + "host", + "observed_at", + "port", + "project_ref", + "protocol", + "query_connectivity", + "region", + "routing_status", + "status", + "tls_required", + "unavailable_reason" + ], + "type": "object" + }, + "id": { + "description": "Project ref", + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_connection"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse Flight SQL connection contract is not yet in the deployed Management API specification." + }, { "op": "test", "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1setups~1current/get/x-operation", diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 9b4b36f86d..a4e29e64f0 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -14320,6 +14320,149 @@ export const V2GetProjectConfigOutput = Schema.Struct({ }), }), }); +export const V2GetWarehouseConnectionInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), +}); +export const V2GetWarehouseConnectionOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + access_mode: Schema.Literal("read_only"), + authentication: Schema.Struct({ + credential_source: Schema.Literal("source_project_database"), + default_username: Schema.Literal("postgres"), + membership_guidance: Schema.String, + method: Schema.Literal("database_username_password"), + password_guidance: Schema.String, + required_membership: Schema.Literal("supabase_warehouse_reader"), + }).annotate({ + description: + "How to authenticate. No credentials are returned; the password is never exposed by this API.", + }), + endpoint: Schema.Union([ + Schema.String.annotate({ + description: + "Arrow Flight SQL URI, grpc+tls://:443. Null unless status is available or pending.", + }), + Schema.Null, + ]), + host: Schema.Union([ + Schema.String.annotate({ + description: + "Public hostname of the Flight SQL endpoint. Null unless status is available or pending.", + }), + Schema.Null, + ]), + observed_at: Schema.String.annotate({ + description: + "Time the API retrieved this information. This timestamp does not indicate when connectivity was last verified.", + format: "date-time", + }), + port: Schema.Union([ + Schema.Number.annotate({ + description: + "Public TLS port of the Flight SQL endpoint. Null unless status is available or pending.", + }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(-9007199254740991).annotate({ + expected: "a value greater than or equal to -9007199254740991", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + Schema.Null, + ]), + project_ref: Schema.String.annotate({ description: "Project ref" }) + .check( + Schema.isMinCodePoints(20).annotate({ + expected: "a string with at least 20 code points", + }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + protocol: Schema.Literal("arrow_flight_sql"), + query_connectivity: Schema.Literal("not_checked"), + region: Schema.Union([ + Schema.String.annotate({ + description: + "Assigned Warehouse compute region, which may differ from the source database region. Null when the project has no project-specific route.", + }), + Schema.Null, + ]), + routing_status: Schema.Union([ + Schema.Union([ + Schema.Literals(["error", "pending", "ready", "removed"]), + Schema.Null, + ]).annotate({ + description: + "DNS delivery status of the project route. Null when the project uses the shared legacy route.", + }), + OpenString, + ]), + status: Schema.Union([ + Schema.Literals([ + "available", + "disabled", + "disabling", + "not_configured", + "pending", + "unavailable", + ]).annotate({ + description: + "Configured availability of the Warehouse endpoint, derived from routing and lifecycle state. It is not a connectivity probe: a ready route does not prove a query will succeed.", + }), + OpenString, + ]), + tls_required: Schema.Literal(true), + unavailable_reason: Schema.Union([ + Schema.Union([ + Schema.Literals([ + "assignment_unavailable", + "cleanup_failed", + "observation_unavailable", + "routing_failed", + ]), + Schema.Null, + ]).annotate({ + description: "Why the endpoint is unavailable. Null unless status is unavailable.", + }), + OpenString, + ]), + }), + id: Schema.String.annotate({ description: "Project ref" }) + .check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + type: Schema.Literal("warehouse_connection").annotate({ description: "Resource type." }), + }), +}); export const V2GetWarehouseSetupInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -19938,6 +20081,7 @@ export const openApiOperationIdMap = { "v2-get-a-compute-instance": "v2GetAComputeInstance", "v2-get-notebook": "v2GetNotebook", "v2-get-project-config": "v2GetProjectConfig", + "v2-get-warehouse-connection": "v2GetWarehouseConnection", "v2-get-warehouse-setup": "v2GetWarehouseSetup", "v2-get-warehouse-status": "v2GetWarehouseStatus", "v2-get-warehouse-teardown": "v2GetWarehouseTeardown", @@ -23113,6 +23257,20 @@ export const operationDefinitions = { inputSchema: V2GetProjectConfigInput, outputSchema: V2GetProjectConfigOutput, }, + v2GetWarehouseConnection: { + id: "v2GetWarehouseConnection", + description: + "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/connection", + pathParams: ["ref"], + queryParams: [], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2GetWarehouseConnectionInput, + outputSchema: V2GetWarehouseConnectionOutput, + }, v2GetWarehouseSetup: { id: "v2GetWarehouseSetup", description: diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index 705dd7770b..a50f091773 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -3092,6 +3092,22 @@ export const versionedEffectOperations = { options, ); }), + getWarehouseConnection: ( + input: typeof operationDefinitions.v2GetWarehouseConnection.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2GetWarehouseConnection.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2GetWarehouseConnection">( + operationDefinitions.v2GetWarehouseConnection, + input, + options, + ); + }), getWarehouseSetup: ( input: typeof operationDefinitions.v2GetWarehouseSetup.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index febd74ac9b..1c1b8a687b 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -32759,6 +32759,104 @@ }, "x-scalar-stability": "experimental" } + }, + "/v2/projects/{ref}/warehouse/connection": { + "get": { + "description": "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-connection", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseConnectionResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature or project metadata unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get Warehouse Flight SQL connection details", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse", + "method": "connection" + }, + "x-scalar-stability": "experimental" + } } }, "components": { @@ -48518,6 +48616,170 @@ }, "required": ["data"], "type": "object" + }, + "V2WarehouseConnectionResponse_Output": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "access_mode": { + "enum": ["read_only"], + "type": "string" + }, + "authentication": { + "description": "How to authenticate. No credentials are returned; the password is never exposed by this API.", + "properties": { + "credential_source": { + "enum": ["source_project_database"], + "type": "string" + }, + "default_username": { + "enum": ["postgres"], + "type": "string" + }, + "membership_guidance": { + "type": "string" + }, + "method": { + "enum": ["database_username_password"], + "type": "string" + }, + "password_guidance": { + "type": "string" + }, + "required_membership": { + "enum": ["supabase_warehouse_reader"], + "type": "string" + } + }, + "required": [ + "credential_source", + "default_username", + "membership_guidance", + "method", + "password_guidance", + "required_membership" + ], + "type": "object" + }, + "endpoint": { + "description": "Arrow Flight SQL URI, grpc+tls://:443. Null unless status is available or pending.", + "nullable": true, + "type": "string" + }, + "host": { + "description": "Public hostname of the Flight SQL endpoint. Null unless status is available or pending.", + "nullable": true, + "type": "string" + }, + "observed_at": { + "description": "Time the API retrieved this information. This timestamp does not indicate when connectivity was last verified.", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "port": { + "description": "Public TLS port of the Flight SQL endpoint. Null unless status is available or pending.", + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "nullable": true, + "type": "integer" + }, + "project_ref": { + "description": "Project ref", + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + }, + "protocol": { + "enum": ["arrow_flight_sql"], + "type": "string" + }, + "query_connectivity": { + "enum": ["not_checked"], + "type": "string" + }, + "region": { + "description": "Assigned Warehouse compute region, which may differ from the source database region. Null when the project has no project-specific route.", + "nullable": true, + "type": "string" + }, + "routing_status": { + "description": "DNS delivery status of the project route. Null when the project uses the shared legacy route.", + "enum": ["error", null, "pending", "ready", "removed"], + "nullable": true, + "type": "string" + }, + "status": { + "description": "Configured availability of the Warehouse endpoint, derived from routing and lifecycle state. It is not a connectivity probe: a ready route does not prove a query will succeed.", + "enum": [ + "available", + "disabled", + "disabling", + "not_configured", + "pending", + "unavailable" + ], + "type": "string" + }, + "tls_required": { + "enum": [true], + "type": "boolean" + }, + "unavailable_reason": { + "description": "Why the endpoint is unavailable. Null unless status is unavailable.", + "enum": [ + "assignment_unavailable", + "cleanup_failed", + null, + "observation_unavailable", + "routing_failed" + ], + "nullable": true, + "type": "string" + } + }, + "required": [ + "access_mode", + "authentication", + "endpoint", + "host", + "observed_at", + "port", + "project_ref", + "protocol", + "query_connectivity", + "region", + "routing_status", + "status", + "tls_required", + "unavailable_reason" + ], + "type": "object" + }, + "id": { + "description": "Project ref", + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_connection"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index b8db833a8c..18dd282fe0 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -449,4 +449,5 @@ export const operationPermissions: Readonly }, "v2-get-warehouse-teardown": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-get-warehouse-status": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-get-warehouse-connection": { fga: [["database_read"]], oauthScope: "database:read" }, }; From ec2ecb0b7a72cc36a45fa81c6785f5ca727bd98d Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 10:56:20 +0100 Subject: [PATCH 12/45] chore(cli): centralize generated command gating and docs Drive the experimental gate for generated command groups from the policy nouns instead of a warehouse-specific resolver, and replace the per-command warehouse SIDE_EFFECTS docs with a shared contract plus a generated per-command reference kept in sync by the generator check. --- .github/workflows/api-package-sync.yml | 2 +- apps/cli/AGENTS.md | 9 +- apps/cli/scripts/api-command-derive.ts | 2 +- .../scripts/api-command-derive.unit.test.ts | 2 +- apps/cli/scripts/api-command-reference.ts | 170 ++++++++++++++++++ apps/cli/scripts/generate-api-commands.ts | 22 ++- .../cli/boolean-flag-defaults.unit.test.ts | 4 +- .../command-surface.integration.test.ts | 41 +++-- .../cli/command-surface/command-surface.ts | 19 +- apps/cli/src/cli/main.ts | 8 +- apps/cli/src/cli/root.ts | 9 +- .../command-permissions.unit.test.ts | 2 +- .../fga-request-sets.unit.test.ts | 2 +- .../help-section.tree.unit.test.ts | 2 +- .../hosted-consent-coverage.unit.test.ts | 2 +- .../target/target-policy.unit.test.ts | 2 +- apps/cli/src/commands/api/SIDE_EFFECTS.md | 150 ++++++++++++++++ .../api-command-bindings.integration.test.ts | 5 +- .../src/commands/api/api-command-features.ts | 51 ++++++ .../src/commands/api/api-command-policy.ts | 3 +- .../api-command-shapes.integration.test.ts | 2 +- .../api/api-commands.integration.test.ts | 58 ++++-- apps/cli/src/commands/api/generated.md | 101 +++++++++++ .../cli/src/commands/api/warehouse-backend.ts | 35 ---- .../api/warehouse/connection/SIDE_EFFECTS.md | 101 ----------- .../api/warehouse/disable/SIDE_EFFECTS.md | 58 ------ .../api/warehouse/enable/SIDE_EFFECTS.md | 104 ----------- .../api/warehouse/status/SIDE_EFFECTS.md | 93 ---------- .../warehouse/teardowns/get/SIDE_EFFECTS.md | 21 --- .../cli-config-flag-ownership.unit.test.ts | 6 +- .../src/shared/config/experimental-feature.ts | 7 +- .../tests/helpers/command-flags.unit.test.ts | 2 +- turbo.json | 8 +- 33 files changed, 623 insertions(+), 480 deletions(-) create mode 100644 apps/cli/scripts/api-command-reference.ts create mode 100644 apps/cli/src/commands/api/SIDE_EFFECTS.md create mode 100644 apps/cli/src/commands/api/api-command-features.ts create mode 100644 apps/cli/src/commands/api/generated.md delete mode 100644 apps/cli/src/commands/api/warehouse-backend.ts delete mode 100644 apps/cli/src/commands/api/warehouse/connection/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/api/warehouse/disable/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/api/warehouse/teardowns/get/SIDE_EFFECTS.md diff --git a/.github/workflows/api-package-sync.yml b/.github/workflows/api-package-sync.yml index 95a2ccc89c..74ff75a551 100644 --- a/.github/workflows/api-package-sync.yml +++ b/.github/workflows/api-package-sync.yml @@ -37,7 +37,7 @@ jobs: - name: Check for generated changes id: check run: | - if git diff --ignore-space-at-eol --exit-code --quiet packages/api/src/generated packages/api/scripts/openapi-source.json apps/cli/src/commands/api/generated.ts apps/cli/src/commands/api/generated.schemas.ts; then + if git diff --ignore-space-at-eol --exit-code --quiet packages/api/src/generated packages/api/scripts/openapi-source.json apps/cli/src/commands/api/generated.ts apps/cli/src/commands/api/generated.schemas.ts apps/cli/src/commands/api/generated.md; then echo "No generated changes detected." echo "has_changes=false" >> "$GITHUB_OUTPUT" else diff --git a/apps/cli/AGENTS.md b/apps/cli/AGENTS.md index d4f0c70189..1f3f21647b 100644 --- a/apps/cli/AGENTS.md +++ b/apps/cli/AGENTS.md @@ -25,6 +25,9 @@ src/commands// SIDE_EFFECTS.md # required compatibility contract ``` +Generated Management API commands have no folder of their own: `src/commands/api/` holds their +shared `SIDE_EFFECTS.md` and the generated per-command `generated.md`. + Register every command in `src/cli/root.ts`. Keep `.format.ts` and `.encoders.ts` pure. Handler phase spans are named `.`; see the root tracing rule. Read `src/shared/` and the command-level infrastructure under @@ -58,9 +61,11 @@ truth. Update tests and side-effect documentation with intentional behavior chan State locations are also public: preserve `~/.supabase/…`, `/supabase/.temp/…`, and native keyring entries. Do not move or rename them. -Every command has a `SIDE_EFFECTS.md` based on the [template](src/SIDE_EFFECTS_TEMPLATE.md), documenting exact +Every hand-written command has a `SIDE_EFFECTS.md` based on the [template](src/SIDE_EFFECTS_TEMPLATE.md), documenting exact files and formats, API calls and shapes, environment variables, and exit codes. Keep it accurate; -it is the command compatibility checklist and an input to E2E coverage. +it is the command compatibility checklist and an input to E2E coverage. Generated API commands are +covered by the shared [`src/commands/api/SIDE_EFFECTS.md`](src/commands/api/SIDE_EFFECTS.md) and the +generated [`generated.md`](src/commands/api/generated.md); they get no per-command folder or file. Every applicable command must preserve these invariants: diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 9b70ce85af..f7d1af08ef 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -478,7 +478,7 @@ const successSchema = (spec: JsonObject, operation: Operation): unknown => { return undefined; }; -const collectOperations = (spec: JsonObject): ReadonlyMap => { +export const collectOperations = (spec: JsonObject): ReadonlyMap => { const operations = new Map(); for (const [path, rawItem] of Object.entries(asRecord(spec.paths) ?? {})) { const pathItem = asRecord(rawItem); diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 9775ae2366..d6498ee5e1 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -41,7 +41,7 @@ const envelope = (attributes: Record) => ({ const thingNoun: ApiNoun = { description: "Manage things", - feature: "things", + feature: "warehouse", groups: { sub: "Manage sub things", "sub.deep": "Manage deep things", status: "Status" }, }; diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts new file mode 100644 index 0000000000..afecca4434 --- /dev/null +++ b/apps/cli/scripts/api-command-reference.ts @@ -0,0 +1,170 @@ +import type { + ApiCommandBinding, + ApiCommandEntry, + ApiCommandFlag, + ApiCommandWait, + ApiPollTarget, +} from "../src/commands/api/api-command.model.ts"; + +/** Method and path of an operation, for polled reads that are not generated commands. */ +export interface ApiOperationRoute { + readonly method: string; + readonly path: string; +} + +export interface ApiCommandReferenceInput { + readonly entries: ReadonlyArray; + readonly pollTargets: ReadonlyArray; + /** Route of every poll target, keyed by operation id. */ + readonly pollRoutes: Readonly>; +} + +const code = (text: string): string => `\`${text}\``; + +const route = ({ method, path }: ApiOperationRoute): string => code(`${method} ${path}`); + +const cell = (text: string): string => text.replaceAll("|", "\\|"); + +/** Spec prose can carry `` text, which Markdown would read as an HTML tag. */ +const prose = (text: string): string => text.replaceAll("<", "\\<"); + +const commandLine = (entry: Pick): string => + ["supabase", ...entry.command].join(" "); + +const flagType = (flag: ApiCommandFlag): string => + flag.choices === undefined ? flag.type : `${flag.type} (${flag.choices.map(code).join(", ")})`; + +const bindsTo = (entry: ApiCommandEntry, flag: ApiCommandFlag): string => { + const binding = entry.bindings.find( + (candidate) => candidate.source === "flag" && candidate.flag === flag.name, + ); + if (binding === undefined) return ""; + return binding.location === "body" + ? `body ${code(binding.pointer)}` + : `${binding.location} ${code(binding.name)}`; +}; + +const flagRows = (entry: ApiCommandEntry): ReadonlyArray => + entry.flags.map((flag) => { + const label = flag.type === "boolean" ? `--${flag.name}` : `--${flag.name} <${flag.name}>`; + const notes = flag.sensitive === true ? " Sensitive: never echoed or recorded." : ""; + return `| ${code(label)} | ${cell(flagType(flag))} | ${flag.required ? "yes" : "no"} | ${flag.repeatable ? "yes" : "no"} | ${bindsTo(entry, flag)}${notes} |`; + }); + +const argumentLine = (entry: ApiCommandEntry): string | undefined => { + if (entry.argument === undefined) return undefined; + const binding = entry.bindings.find( + (candidate): candidate is Extract => + candidate.source === "argument" && candidate.argument === entry.argument?.name, + ); + const target = binding === undefined ? "" : `, bound to path parameter ${code(binding.name)}`; + return `Positional argument ${code(`<${entry.argument.name}>`)}${target}.`; +}; + +/** The command a failed or timed-out wait names, as the runtime builds it. */ +const failureHintCommand = ( + entry: ApiCommandEntry, + wait: ApiCommandWait, + input: ApiCommandReferenceInput, +): string => { + const read = input.entries.find((candidate) => candidate.operationId === wait.read); + if (read === undefined) { + const inspect = input.entries.find( + (candidate) => + candidate.operationId === + input.pollTargets.find((target) => target.operationId === wait.read)?.inspect, + ); + return `${inspect === undefined ? "" : commandLine(inspect)} --remote=`.trim(); + } + const own = read.operationId === entry.operationId; + const parts = read.bindings.flatMap((binding) => { + if (binding.source === "target" || binding.location === "body") return []; + if (!own && !(binding.name in wait.params)) return []; + const text = + binding.source === "argument" ? `<${binding.name}>` : `--${binding.flag} <${binding.name}>`; + return [own ? `[${text}]` : text]; + }); + return [commandLine(read), ...parts, "--remote="].join(" "); +}; + +const waitSection = ( + entry: ApiCommandEntry, + wait: ApiCommandWait, + input: ApiCommandReferenceInput, +): ReadonlyArray => { + const publicRead = input.entries.find((candidate) => candidate.operationId === wait.read); + const polled = + publicRead === undefined + ? input.pollRoutes[wait.read] + : { method: publicRead.method, path: publicRead.apiPath }; + const polledRoute = polled === undefined ? "unknown route" : route(polled); + const params = Object.entries(wait.params); + return [ + "### Wait", + "", + `- Polls: ${polledRoute} (${code(wait.read)}${publicRead === undefined ? ", hidden poll target" : publicRead.operationId === entry.operationId ? ", the command's own read" : ""}).`, + ...(params.length === 0 + ? [] + : [ + `- Read parameters from the change response: ${params + .map(([name, pointer]) => `${code(name)} from ${code(pointer)}`) + .join(", ")}.`, + ]), + `- Status at ${code(wait.status)}; succeeded: ${wait.succeeded.map(code).join(", ")}; failed: ${wait.failed.map(code).join(", ")}.`, + ...(wait.error === undefined ? [] : [`- Failure message from ${code(wait.error)}.`]), + `- Failure hint names ${code(failureHintCommand(entry, wait, input))}.`, + ]; +}; + +const bodyLine = (entry: ApiCommandEntry): string | undefined => { + const { body } = entry; + if (body === undefined) return undefined; + return body.kind === "json-envelope" + ? `JSON envelope ${code(`data.type = ${body.type ?? ""}`)}, fields under ${code("data.attributes")}` + : "JSON object"; +}; + +const commandSection = ( + entry: ApiCommandEntry, + input: ApiCommandReferenceInput, +): ReadonlyArray => { + const body = bodyLine(entry); + const argument = argumentLine(entry); + const flags = flagRows(entry); + return [ + `## ${code(commandLine(entry))}`, + "", + prose(entry.summary), + "", + ...(entry.description === undefined ? [] : [prose(entry.description), ""]), + `- Access: ${entry.readOnly ? "read-only, no consent" : "mutation, consent defaults to No (`--yes` when it cannot prompt)"}.`, + `- Feature: ${code(entry.feature)}.`, + `- Request: ${route({ method: entry.method, path: entry.apiPath })} (${code(entry.operationId)}), success ${entry.response.status} ${entry.response.kind}.`, + ...(body === undefined ? [] : [`- Body: ${body}.`]), + ...(argument === undefined ? [] : [`- ${argument}`]), + ...(flags.length === 0 + ? [] + : [ + "", + "### Flags", + "", + "| Flag | Type | Required | Repeatable | Binds to |", + "| ---- | ---- | -------- | ---------- | -------- |", + ...flags, + ]), + ...(entry.wait === undefined ? [] : ["", ...waitSection(entry, entry.wait, input)]), + "", + ]; +}; + +/** Renders the per-command reference from the derived entries; formatting is left to oxfmt. */ +export const renderApiCommandReference = (input: ApiCommandReferenceInput): string => + [ + "", + "", + "# Generated API commands", + "", + "Reference for the commands generated from the Management API contract. The behavior every one of them shares (feature gates, consent, files, exit codes, output, `--wait`) is in [SIDE_EFFECTS.md](./SIDE_EFFECTS.md).", + "", + ...input.entries.flatMap((entry) => commandSection(entry, input)), + ].join("\n"); diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index 45b08d6f7d..a21f506e0b 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -7,7 +7,12 @@ import { pollTargets as pollTargetMap, } from "../src/commands/api/api-command-policy.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; -import { ApiCommandGenerationError, deriveApiCommands } from "./api-command-derive.ts"; +import { renderApiCommandReference } from "./api-command-reference.ts"; +import { + ApiCommandGenerationError, + collectOperations, + deriveApiCommands, +} from "./api-command-derive.ts"; class ApiCommandFormatError extends Data.TaggedError("ApiCommandFormatError")<{ readonly message: string; @@ -102,6 +107,17 @@ const main = Effect.gen(function* () { const sortedSchemas = Object.fromEntries( Object.entries(schemas).sort(([left], [right]) => left.localeCompare(right, "en")), ); + const operations = collectOperations(spec); + const pollRoutes: Record = {}; + for (const target of pollTargets) { + const operation = operations.get(target.operationId); + if (operation === undefined) { + return yield* new ApiCommandGenerationError({ + problems: [`${target.operationId}: polling target has no operation in the spec`], + }); + } + pollRoutes[target.operationId] = { method: operation.method, path: operation.path }; + } const outputs = [ { relative: "src/commands/api/generated.ts", @@ -111,6 +127,10 @@ const main = Effect.gen(function* () { relative: "src/commands/api/generated.schemas.ts", source: `${HEADER}import type { ApiCommandSchemas } from "./api-command.model.ts";\n\nexport const apiCommandSchemas = ${yield* encodeJson(sortedSchemas)} as const satisfies Readonly>;\n`, }, + { + relative: "src/commands/api/generated.md", + source: renderApiCommandReference({ entries, pollTargets, pollRoutes }), + }, ]; const stale: Array = []; diff --git a/apps/cli/src/cli/boolean-flag-defaults.unit.test.ts b/apps/cli/src/cli/boolean-flag-defaults.unit.test.ts index bf2e675948..ff25471d5a 100644 --- a/apps/cli/src/cli/boolean-flag-defaults.unit.test.ts +++ b/apps/cli/src/cli/boolean-flag-defaults.unit.test.ts @@ -54,10 +54,10 @@ describe("boolean flag wiring", () => { it("gives every boolean flag a default, so omitting it is not a parse error", () => { for (const stackBackend of ["legacy", "stack"] as const) { for (const computeEnabled of [false, true]) { - for (const warehouseEnabled of [false, true]) { + for (const apiFeatures of [[], ["warehouse"]] as const) { expect( booleanFlagsRequiringAValue( - rootCommandForFeatures({ stackBackend, computeEnabled, warehouseEnabled }), + rootCommandForFeatures({ stackBackend, computeEnabled, apiFeatures }), ), ).toEqual([]); } diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 2b21c585a9..332a77030b 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -9,6 +9,14 @@ const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown const surface = Effect.runPromise(commandSurface()); +const warehouseVariant = Effect.promise(() => surface).pipe( + Effect.map(({ variants }) => { + const variant = variants["warehouse"]; + if (variant === undefined) throw new Error("the surface has no warehouse variant"); + return variant; + }), +); + const titlesOf = (result: unknown): ReadonlyArray => typeof result === "object" && result !== null && "anyOf" in result && Array.isArray(result.anyOf) ? result.anyOf.map((branch) => @@ -43,8 +51,8 @@ describe("command surface", () => { it.effect("lists exactly the warehouse entries the feature adds", () => Effect.gen(function* () { - const { variants } = yield* Effect.promise(() => surface); - expect(Object.keys(variants.warehouse)).toEqual([ + const warehouse = yield* warehouseVariant; + expect(Object.keys(warehouse)).toEqual([ "warehouse", "warehouse connection", "warehouse disable", @@ -58,7 +66,7 @@ describe("command surface", () => { it.effect("extracts one command from any mounted root, keyed like the full walk", () => Effect.gen(function* () { - const root = rootCommandForFeatures({ warehouseEnabled: true }); + const root = rootCommandForFeatures({ apiFeatures: ["warehouse"] }); const walked = yield* walkCommandSurface(root); const single = yield* commandSurfaceEntry(root, ["warehouse", "status"]); expect(walked["warehouse status"]).toStrictEqual(single); @@ -68,8 +76,8 @@ describe("command surface", () => { it.effect("describes a generated command from its annotations and operation schemas", () => Effect.gen(function* () { - const { variants } = yield* Effect.promise(() => surface); - const enable = variants.warehouse["warehouse enable"]; + const warehouse = yield* warehouseVariant; + const enable = warehouse["warehouse enable"]; expect(enable).toMatchObject({ path: ["warehouse", "enable"], target: { group: "hosted", consent: "no" }, @@ -91,8 +99,8 @@ describe("command surface", () => { it.effect("describes retained-data disable and its linked cleanup read", () => Effect.gen(function* () { - const { variants } = yield* Effect.promise(() => surface); - const disable = variants.warehouse["warehouse disable"]; + const warehouse = yield* warehouseVariant; + const disable = warehouse["warehouse disable"]; expect(disable).toMatchObject({ target: { group: "hosted", consent: "no" }, stage: { status: "experimental", feature: "warehouse" }, @@ -103,7 +111,7 @@ describe("command surface", () => { expect(disable?.flags["wait"]).toMatchObject({ type: "boolean" }); expect(disable?.flags["timeout"]).toMatchObject({ type: "string" }); expect(titlesOf(disable?.result)).toEqual(["response", "waited", "dryRun"]); - expect(variants.warehouse["warehouse teardowns get"]?.flags["operation-id"]).toMatchObject({ + expect(warehouse["warehouse teardowns get"]?.flags["operation-id"]).toMatchObject({ required: false, }); }), @@ -121,8 +129,8 @@ describe("command surface", () => { it.effect("separates consolidated status from the identity-bound setup waiter", () => Effect.gen(function* () { - const { variants } = yield* Effect.promise(() => surface); - const status = variants.warehouse["warehouse status"]; + const warehouse = yield* warehouseVariant; + const status = warehouse["warehouse status"]; expect(status).toMatchObject({ api: { operationId: "v2-get-warehouse-status" }, target: { group: "hosted", consent: "none" }, @@ -132,9 +140,9 @@ describe("command surface", () => { expect(status?.flags).not.toHaveProperty("selection-id"); expect(status?.flags).not.toHaveProperty("wait"); expect(status?.flags).not.toHaveProperty("timeout"); - expect(variants.warehouse).not.toHaveProperty("warehouse setups"); - expect(variants.warehouse).not.toHaveProperty("warehouse setups get"); - expect(variants.warehouse["warehouse enable"]?.flags).toMatchObject({ + expect(warehouse).not.toHaveProperty("warehouse setups"); + expect(warehouse).not.toHaveProperty("warehouse setups get"); + expect(warehouse["warehouse enable"]?.flags).toMatchObject({ wait: { type: "boolean" }, timeout: { type: "string" }, }); @@ -143,11 +151,8 @@ describe("command surface", () => { it.effect("declares a waited result only for a command that waits on another read", () => Effect.gen(function* () { - const { variants } = yield* Effect.promise(() => surface); - expect(titlesOf(variants.warehouse["warehouse status"]?.result)).toEqual([ - "response", - "dryRun", - ]); + const warehouse = yield* warehouseVariant; + expect(titlesOf(warehouse["warehouse status"]?.result)).toEqual(["response", "dryRun"]); }), ); diff --git a/apps/cli/src/cli/command-surface/command-surface.ts b/apps/cli/src/cli/command-surface/command-surface.ts index f34930eaf8..ac0ea556a6 100644 --- a/apps/cli/src/cli/command-surface/command-surface.ts +++ b/apps/cli/src/cli/command-surface/command-surface.ts @@ -10,6 +10,7 @@ import type { } from "../../commands/api/api-command.model.ts"; import { readCommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; import type { CommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; +import { nouns } from "../../commands/api/api-command-policy.ts"; import { apiCommands } from "../../commands/api/generated.ts"; import { rootCommandForFeatures } from "../root.ts"; import { flattenSubcommands } from "../../docs/docs-introspection.ts"; @@ -77,9 +78,7 @@ interface CommandSurfaceEntry { interface CommandSurface { readonly globalFlags: Readonly>; readonly commands: Readonly>; - readonly variants: { - readonly warehouse: Readonly>; - }; + readonly variants: Readonly>>>; } type CommandRoot = Command.Command.Any; @@ -280,13 +279,19 @@ export const walkCommandSurface = Effect.fn("CommandSurface.walk")(function* (ro /** The default command surface and, per feature, the entries that differ when the feature is on. */ export const commandSurface = Effect.fn("CommandSurface.build")(function* () { const base = yield* walkCommandSurface(rootCommandForFeatures()); - const warehouse = yield* walkCommandSurface(rootCommandForFeatures({ warehouseEnabled: true })); - const differing = Object.entries(warehouse).filter( - ([key, entry]) => key in base === false || encodeJson(base[key]) !== encodeJson(entry), + const features = [...new Set(Object.values(nouns).map(({ feature }) => feature))]; + const variants = yield* Effect.forEach(features, (feature) => + Effect.gen(function* () { + const walked = yield* walkCommandSurface(rootCommandForFeatures({ apiFeatures: [feature] })); + const differing = Object.entries(walked).filter( + ([key, entry]) => key in base === false || encodeJson(base[key]) !== encodeJson(entry), + ); + return [feature, sortedRecord(differing)] as const; + }), ); return { globalFlags: walkGlobalFlags(rootCommandForFeatures()), commands: base, - variants: { warehouse: sortedRecord(differing) }, + variants: sortedRecord(variants), } satisfies CommandSurface; }); diff --git a/apps/cli/src/cli/main.ts b/apps/cli/src/cli/main.ts index a14b05cb2b..d71cb3c7ce 100644 --- a/apps/cli/src/cli/main.ts +++ b/apps/cli/src/cli/main.ts @@ -7,7 +7,7 @@ import { upgradeNoticeHook } from "../command-internal/upgrade-notice.ts"; import { analyticsLayerFor } from "../telemetry/analytics.layer.ts"; import { defaultCompleteDeps, tryComplete } from "./complete.ts"; import { resolveProjectStateSelection } from "../command-internal/stack-backend.ts"; -import { resolveWarehouseEnabled } from "../commands/api/warehouse-backend.ts"; +import { resolveApiCommandFeatures } from "../commands/api/api-command-features.ts"; import { resolveComputeEnabled } from "../commands/experimental/compute/compute-backend.ts"; import { cliConfigProviderLayer } from "../shared/config/cli-config-provider.layer.ts"; import { cliEntrypointForFeatures, rootCommandForFeatures } from "./root.ts"; @@ -29,16 +29,16 @@ const selectionExit = await Effect.runPromiseExit( args, cwd: process.cwd(), }); - const warehouseEnabled = yield* resolveWarehouseEnabled({ + const apiFeatures = yield* resolveApiCommandFeatures({ args, cwd: process.cwd(), }); - return { projectState, stackBackend, computeEnabled, warehouseEnabled }; + return { projectState, stackBackend, computeEnabled, apiFeatures }; }).pipe(Effect.provide(Layer.mergeAll(BunServices.layer, cliConfigProviderLayer))), ); const selectedFeatures = Exit.isSuccess(selectionExit) ? selectionExit.value - : ({ stackBackend: "legacy", computeEnabled: false, warehouseEnabled: false } as const); + : ({ stackBackend: "legacy", computeEnabled: false, apiFeatures: [] } as const); const { rootCommand: selectedRoot, agentDefaultOutputFormat } = cliEntrypointForFeatures( selectedFeatures, args, diff --git a/apps/cli/src/cli/root.ts b/apps/cli/src/cli/root.ts index 25c295ab0e..d8f3132c1f 100644 --- a/apps/cli/src/cli/root.ts +++ b/apps/cli/src/cli/root.ts @@ -18,7 +18,10 @@ import { stackStopCommand } from "../commands/experimental/stack/stop/stop.comma import { stackStatusCommand } from "../commands/experimental/stack/status/status.command.ts"; import type { StackBackend } from "../command-internal/stack-backend.ts"; import { isFunctionsServePath, stackBackendLayer } from "../command-internal/stack-backend.ts"; -import type { ExperimentalFeatureFlagError } from "../shared/config/experimental-feature.ts"; +import type { + ExperimentalFeature, + ExperimentalFeatureFlagError, +} from "../shared/config/experimental-feature.ts"; import { type ProjectStateMode, projectStateModeLayer, @@ -148,7 +151,7 @@ interface RootCommandFeatures { readonly projectState?: Exit.Exit; readonly stackBackend?: StackBackend; readonly computeEnabled?: boolean; - readonly warehouseEnabled?: boolean; + readonly apiFeatures?: ReadonlyArray; } /** Agents default to stream-json for Stack-backed `functions serve`, which rejects json. */ @@ -206,7 +209,7 @@ export const rootCommandForFeatures = (options: RootCommandFeatures = {}) => testCommand, unlinkCommand, vanitySubdomainsCommand, - ...apiCommandGroups(options.warehouseEnabled ? ["warehouse"] : []), + ...apiCommandGroups(options.apiFeatures ?? []), whoamiCommand, ]), Command.provide( diff --git a/apps/cli/src/command-internal/command-permissions/command-permissions.unit.test.ts b/apps/cli/src/command-internal/command-permissions/command-permissions.unit.test.ts index ed4707ce11..45e0748e90 100644 --- a/apps/cli/src/command-internal/command-permissions/command-permissions.unit.test.ts +++ b/apps/cli/src/command-internal/command-permissions/command-permissions.unit.test.ts @@ -43,7 +43,7 @@ const VARIANTS: ReadonlyArray<{ readonly name: string; readonly variant: Permiss projectState: Exit.succeed("stack"), stackBackend: "stack", computeEnabled: true, - warehouseEnabled: true, + apiFeatures: ["warehouse"], } satisfies Required>, }, ]; diff --git a/apps/cli/src/command-internal/command-permissions/fga-request-sets.unit.test.ts b/apps/cli/src/command-internal/command-permissions/fga-request-sets.unit.test.ts index afe51a09ec..d43788145f 100644 --- a/apps/cli/src/command-internal/command-permissions/fga-request-sets.unit.test.ts +++ b/apps/cli/src/command-internal/command-permissions/fga-request-sets.unit.test.ts @@ -19,7 +19,7 @@ const VARIANTS: ReadonlyArray = [ projectState: Exit.succeed("stack"), stackBackend: "stack", computeEnabled: true, - warehouseEnabled: true, + apiFeatures: ["warehouse"], } satisfies Required>, ]; diff --git a/apps/cli/src/command-internal/command-permissions/help-section.tree.unit.test.ts b/apps/cli/src/command-internal/command-permissions/help-section.tree.unit.test.ts index ed5cd96bff..40fbfa0c50 100644 --- a/apps/cli/src/command-internal/command-permissions/help-section.tree.unit.test.ts +++ b/apps/cli/src/command-internal/command-permissions/help-section.tree.unit.test.ts @@ -21,7 +21,7 @@ const VARIANTS: ReadonlyArray<{ readonly name: string; readonly variant: Permiss projectState: Exit.succeed("stack"), stackBackend: "stack", computeEnabled: true, - warehouseEnabled: true, + apiFeatures: ["warehouse"], } satisfies Required>, }, ]; diff --git a/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts b/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts index 67e0174c3d..010f20f7d7 100644 --- a/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts +++ b/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts @@ -11,7 +11,7 @@ const srcDir = fileURLToPath(new URL("../..", import.meta.url)); const VARIANTS: ReadonlyArray = [ undefined, - { stackBackend: "stack", computeEnabled: true, warehouseEnabled: true }, + { stackBackend: "stack", computeEnabled: true, apiFeatures: ["warehouse"] }, ]; const consentDefaultByLeaf: ReadonlyMap = new Map( diff --git a/apps/cli/src/command-internal/target/target-policy.unit.test.ts b/apps/cli/src/command-internal/target/target-policy.unit.test.ts index 0bae66a710..b88a8e1db7 100644 --- a/apps/cli/src/command-internal/target/target-policy.unit.test.ts +++ b/apps/cli/src/command-internal/target/target-policy.unit.test.ts @@ -19,7 +19,7 @@ const VARIANTS: ReadonlyArray<{ readonly name: string; readonly variant: Permiss projectState: Exit.succeed("stack"), stackBackend: "stack", computeEnabled: true, - warehouseEnabled: true, + apiFeatures: ["warehouse"], } satisfies Required>, }, ]; diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md new file mode 100644 index 0000000000..d7d3e66d20 --- /dev/null +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -0,0 +1,150 @@ +# Generated API commands + +Target: hosted, see [Command target](../../../docs/command-target.md). Read-only commands ask for no +consent; mutations default to No (confirm unless `--yes`; a run that cannot prompt and has no `--yes` +is a usage error). + +Every command generated from the Management API contract shares this contract: one central policy +(`api-command-policy.ts`) selects the operations, `generated.ts` holds the derived command data, and +one runtime executes it. Hand-written commands keep their own `SIDE_EFFECTS.md`. The per-command +details (request route, request body, flags and where each binds, the `--wait` read) are in the +generated [per-command reference](./generated.md); that file is the source for routes, flag +bindings and wait settings, and the sections below do not repeat them. + +## Feature gate + +Each noun belongs to one feature. Its commands are registered only when `experimental.` is +enabled: set `[experimental] = true` or `SUPABASE_EXPERIMENTAL_=1`. The setting +is resolved before the command tree is built, so `--experimental` alone does not expose the +commands. When the feature is disabled the noun is absent from help, completion and the generated +command documentation. + +## Files Read + +| Path | Format | When | +| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | +| `/supabase/config.json` | JSON | when present, to resolve `experimental.` before the command tree is built | +| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | +| `` | JSON | only with `--file `: the whole request body (`--file -` reads stdin) | +| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential | +| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | +| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | + +Commands never write project configuration, execute SQL locally or read stdin, except `--file -`. + +## Files Written + +| Path | Format | When | +| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | +| `/telemetry.json` | JSON | always, flushed on success and on failure | +| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref | + +## API Routes + +Each command sends the one request described in the [per-command reference](./generated.md), with +Bearer token authentication, and passes the JSON response through unchanged. The calls every command +can add: + +| Method | Path | Auth | Request body | Response (used fields) | +| ------ | -------------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------ | +| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive (project picker) | +| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}`; linked-project cache miss only (best-effort, after the command) | + +With `--wait`, the command also polls the read operation named in its reference entry. + +### Request input + +- `--body` or `--file` supply the whole body; a flag replaces its own field and nothing else. +- The input is validated before consent and before any request: a top-level body key outside the + declared request-body fields, an unknown nested field or a missing required flag fails with + nothing sent. +- `--dry-run` prints `{method, path, query, headers, body}` and sends no command request, before + consent. The linked-project cache read in the table above can still run. It shows the local + request, not a server-resolved impact. +- Consent uses the command's summary as the action; it does not render an impact plan. + +## `--wait` + +A command whose reference entry has a Wait section accepts `--wait` and `--timeout ` +(a duration such as `90s` or `10m`; default `10m`; an invalid or non-positive value is a usage +error). + +- A mutation first sends its request, then reads the identity the wait needs from the response by + the pointers in its reference entry. A missing value is a defect in the response and ends the wait + with an internal error, never a silent success. +- A read that polls itself sends no separate change request: its own input is polled. +- Polling repeats the read with backoff from 1s doubling to a 10s cap; a longer `Retry-After` on the + last response wins. +- The wait succeeds on a status in the succeeded set and fails (`operation_failed`) on a status in + the failed set. The failure pointer only supplies the error message and never ends the wait by + itself. +- Any non-2xx response while polling, a 409 included, ends the command with the API error; the wait + never resumes. +- At the timeout the command fails with `wait_timeout`. Timeout and cancellation stop local polling + only and do not change server state. +- The failure and timeout hint names the command that re-reads the state. When the polled read is a + generated command, the hint names it with the identity the wait polled with, for example + `supabase -- --remote=`. When the polled read is a hidden + poll target, the hint names its inspect command from `pollTargets` with only `--remote=`. +- With `--wait`, stdout carries the final read response instead of the change response. + +## Exit Codes + +| Code | Condition | +| ----- | ----------------------------------------------------------------------------------------------- | +| `0` | success: the request was accepted, the dry run printed, or the wait ended on a succeeded status | +| `2` | `usage_error`: invalid flags, body or timeout, or consent needed without `--yes` | +| `130` | consent declined at the prompt (`cancelled`) | +| `1` | API error (non-2xx) | +| `1` | with `--wait`: `operation_failed` (a failed status) or `wait_timeout` | + +A 4xx `entitlement_required` body (`{"error":{"code":"entitlement_required","feature","upgrade_url"}}`) +adds `entitlement: {feature, upgrade_url}` to the stderr error document in place of the +token-permission hint; a terminal run prints the upgrade hint, and `cli_upgrade_suggested` fires. +Other statuses and bodies carry no `entitlement` key. + +Errors use the standard stderr envelope. `wait_timeout` includes `timeout_ms`, a nullable +`last_status` and the hint command; terminal text includes the last status. `operation_failed` +includes the failed status and the reported failure message. + +## Environment Variables + +| Variable | Purpose | Required? | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | +| `SUPABASE_EXPERIMENTAL_` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.`) | no | +| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | +| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | +| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to `supabase/.temp/project-ref`) | +| `SUPABASE_WORKDIR` | project directory the command acts on | no (falls back to `--workdir`, then the cwd) | +| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) | +| `SUPABASE_YES` | consent for mutations in a shell; `supabase/.env` and a cwd `.env*` file do not count | no (falls back to `--yes`) | + +## Telemetry Events Fired + +| Event | When | Notable properties / groups | +| ---------------------- | ------------------------------------------ | ----------------------------------- | +| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | + +Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` +and `--wait` record `true`. Generated field flags, `--body`, `--file` and `--timeout` are recorded as +``. Response and error contents never become telemetry properties. + +## Output + +Text rendering applies on a terminal by default, with `--output-format text` (also when piped), and +with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the +API's JSON bytes. `-o` takes precedence over `--output-format`. + +| Mode | stdout | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| text presentation | the response as labelled fields and tables, nested objects as indented blocks, `-` for null or empty values; with `--wait` the final read response; an empty response prints `Done.` | +| JSON presentation | the API's JSON response bytes, unchanged, preserving unknown and null fields; with `--wait` the final read response | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | +| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | +| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | + +When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the +whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it +is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task +message prints as a step line on stdout before the response. JSON and YAML output show no progress. diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 64f65afaa4..0436c50641 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -309,7 +309,10 @@ const send = (path: ReadonlyArray, argv: ReadonlyArray, status: const generated: readonly ApiCommandEntry[] = apiCommands; const surface = await Effect.runPromise(commandSurface()); -const rows = [...Object.values(surface.commands), ...Object.values(surface.variants.warehouse)] +const rows = [ + ...Object.values(surface.commands), + ...Object.values(surface.variants["warehouse"] ?? {}), +] .flatMap((entry) => (entry.api === undefined ? [] : [{ ...entry, api: entry.api }])) .toSorted((a, b) => a.api.operationId.localeCompare(b.api.operationId)); diff --git a/apps/cli/src/commands/api/api-command-features.ts b/apps/cli/src/commands/api/api-command-features.ts new file mode 100644 index 0000000000..4720fe9b49 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-features.ts @@ -0,0 +1,51 @@ +import { Effect, type FileSystem, type Path } from "effect"; + +import { extractCommandPath, hasRootVersionFlag } from "../../shared/cli/run.ts"; +import { + type ExperimentalFeature, + type ExperimentalFeatureFlagError, + readExperimentalFeatureConfig, + resolveExperimentalFeature, +} from "../../shared/config/experimental-feature.ts"; +import { nouns } from "./api-command-policy.ts"; + +const nounFeatures = (noun: string | undefined): ReadonlyArray => { + if (noun === undefined) return [...new Set(Object.values(nouns).map(({ feature }) => feature))]; + const definition = Object.entries(nouns).find(([name]) => name === noun)?.[1]; + return definition === undefined ? [] : [definition.feature]; +}; + +/** + * Resolves the experimental features that gate generated API command groups, reading + * configuration only for the features this invocation can reach: every noun feature when no + * command is named (root help and completion), the named noun's feature otherwise. + */ +export const resolveApiCommandFeatures = Effect.fn("ApiCommands.resolveFeatures")( + function* (input: { + readonly args: ReadonlyArray; + readonly cwd: string; + }): Effect.fn.Return< + ReadonlyArray, + ExperimentalFeatureFlagError, + FileSystem.FileSystem | Path.Path + > { + const routingArgs = + input.args[0] === "__complete" || input.args[0] === "__completeNoDesc" + ? input.args.slice(0, -1) + : input.args; + if (hasRootVersionFlag(routingArgs)) return []; + const commandPath = extractCommandPath(routingArgs); + const completePath = + commandPath[0] === "__complete" || commandPath[0] === "__completeNoDesc" + ? commandPath.slice(1) + : commandPath; + const enabled = yield* Effect.filter(nounFeatures(completePath[0]), (feature) => + resolveExperimentalFeature({ + feature, + configValue: readExperimentalFeatureConfig({ feature, cwd: input.cwd, args: routingArgs }), + }), + ); + yield* Effect.annotateCurrentSpan("features", enabled); + return enabled; + }, +); diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 0c94918cf0..b9e12e11c0 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -1,4 +1,5 @@ import type { OpenApiOperationId } from "@supabase/api/effect"; +import type { ExperimentalFeature } from "../../shared/config/experimental-feature.ts"; import type { ApiCommandWait } from "./api-command.model.ts"; /** Verbs every generated command may use. */ @@ -20,7 +21,7 @@ export const verbVocabulary = [ export interface ApiNoun { readonly description: string; /** Feature that gates every command under the noun. */ - readonly feature: string; + readonly feature: ExperimentalFeature; /** Help text of each sub-group, keyed by its dotted path below the noun, e.g. `"tables.layout"`. */ readonly groups?: Readonly>; } diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts index c5acdc1402..74d9c30327 100644 --- a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts @@ -37,7 +37,7 @@ const isRecord = (value: unknown): value is Record => const fixtureNoun: ApiNoun = { description: "Fixture commands", - feature: "fixture", + feature: "warehouse", groups: { migrations: "Migration fixtures", auth: "Auth fixtures", diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 7a99c0d7ce..43ee32e503 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -59,7 +59,7 @@ import { readCommandStage } from "../../command-internal/command-stage/command-s import { apiCommandGroup, apiCommandGroups } from "./runtime.ts"; import { standardFailureFor } from "../../shared/cli/standard-errors.ts"; import { EventUpgradeSuggested } from "../../shared/telemetry/event-catalog.ts"; -import { resolveWarehouseEnabled } from "./warehouse-backend.ts"; +import { resolveApiCommandFeatures } from "./api-command-features.ts"; const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); @@ -1481,7 +1481,7 @@ describe("generated warehouse commands", () => { const fixtureRoot = (entry: ApiCommandEntry) => Command.make("supabase").pipe( Command.withSubcommands([ - apiCommandGroup("fixture", { description: "Fixture commands", feature: "fixture" }, [ + apiCommandGroup("fixture", { description: "Fixture commands", feature: "warehouse" }, [ entry, ]), ]), @@ -1524,8 +1524,12 @@ describe("generated warehouse commands", () => { }); describe("feature gate", () => { - const resolve = (env: Record, cwd: string) => - withConfigEnv(env, resolveWarehouseEnabled({ args: ["warehouse"], cwd })).pipe( + const resolve = ( + env: Record, + cwd: string, + args: ReadonlyArray = ["warehouse"], + ) => + withConfigEnv(env, resolveApiCommandFeatures({ args, cwd })).pipe( Effect.provide(BunServices.layer), ); @@ -1539,7 +1543,7 @@ describe("generated warehouse commands", () => { it.effect("is off by default and absent from the tree and completion", () => Effect.gen(function* () { - expect(yield* resolve({}, tempRoot.current)).toBe(false); + expect(yield* resolve({}, tempRoot.current)).toEqual([]); expect(commandTreeFor(undefined).has("warehouse enable")).toBe(false); const completion = respondToComplete(rootCommandForFeatures(), ["__complete", "ware"]); expect(completion?.candidates ?? []).toHaveLength(0); @@ -1548,15 +1552,15 @@ describe("generated warehouse commands", () => { it.effect("is on with SUPABASE_EXPERIMENTAL_WAREHOUSE", () => Effect.gen(function* () { - expect(yield* resolve({ SUPABASE_EXPERIMENTAL_WAREHOUSE: "1" }, tempRoot.current)).toBe( - true, - ); - const root = rootCommandForFeatures({ warehouseEnabled: true }); + expect(yield* resolve({ SUPABASE_EXPERIMENTAL_WAREHOUSE: "1" }, tempRoot.current)).toEqual([ + "warehouse", + ]); + const root = rootCommandForFeatures({ apiFeatures: ["warehouse"] }); const completion = respondToComplete(root, ["__complete", "ware"]); expect(completion?.candidates).toContainEqual( expect.objectContaining({ name: "warehouse" }), ); - const tree = commandTreeFor({ warehouseEnabled: true }); + const tree = commandTreeFor({ apiFeatures: ["warehouse"] }); expect(tree.has("warehouse enable")).toBe(true); expect(tree.has("warehouse setups get")).toBe(false); expect(tree.has("warehouse status")).toBe(true); @@ -1564,7 +1568,7 @@ describe("generated warehouse commands", () => { ); it("marks each mounted leaf with its operation and experimental feature stage", () => { - const tree = commandTreeFor({ warehouseEnabled: true }); + const tree = commandTreeFor({ apiFeatures: ["warehouse"] }); for (const entry of apiCommands) { const command = tree.get(entry.command.join(" "))?.command; if (command === undefined) throw new Error(`${entry.command.join(" ")} is not mounted`); @@ -1580,7 +1584,31 @@ describe("generated warehouse commands", () => { it.effect("is on with experimental.warehouse in the project config", () => Effect.gen(function* () { yield* withConfig("[experimental]\nwarehouse = true\n"); - expect(yield* resolve({}, tempRoot.current)).toBe(true); + expect(yield* resolve({}, tempRoot.current)).toEqual(["warehouse"]); + }), + ); + + it.effect.each([ + { name: "root help", args: [], features: ["warehouse"] }, + { + name: "shell completion of the group", + args: ["__complete", "ware"], + features: ["warehouse"], + }, + { name: "a command of another group", args: ["projects", "list"], features: [] }, + { name: "completion of another group", args: ["__complete", "projects", ""], features: [] }, + { name: "the root version flag", args: ["--version"], features: [] }, + ])("resolves $name by whether it can reach the group", ({ args, features }) => + Effect.gen(function* () { + const env = { SUPABASE_EXPERIMENTAL_WAREHOUSE: "1" }; + expect(yield* resolve(env, tempRoot.current, args)).toEqual(features); + }), + ); + + it.effect("ignores an invalid value when the invocation cannot reach the group", () => + Effect.gen(function* () { + const env = { SUPABASE_EXPERIMENTAL_WAREHOUSE: "maybe" }; + expect(yield* resolve(env, tempRoot.current, ["projects", "list"])).toEqual([]); }), ); @@ -1596,7 +1624,9 @@ describe("generated warehouse commands", () => { }); }); -const consentCommand = commandTreeFor({ warehouseEnabled: true }).get("warehouse enable")?.command; +const consentCommand = commandTreeFor({ apiFeatures: ["warehouse"] }).get( + "warehouse enable", +)?.command; describeHostedConsent("warehouse enable", { ...(consentCommand === undefined ? {} : { command: consentCommand }), @@ -1612,7 +1642,7 @@ describeHostedConsent("warehouse enable", { }, }); -const disableConsentCommand = commandTreeFor({ warehouseEnabled: true }).get( +const disableConsentCommand = commandTreeFor({ apiFeatures: ["warehouse"] }).get( "warehouse disable", )?.command; describeHostedConsent("warehouse disable", { diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md new file mode 100644 index 0000000000..c125f91a7f --- /dev/null +++ b/apps/cli/src/commands/api/generated.md @@ -0,0 +1,101 @@ + + +# Generated API commands + +Reference for the commands generated from the Management API contract. The behavior every one of them shares (feature gates, consent, files, exit codes, output, `--wait`) is in [SIDE_EFFECTS.md](./SIDE_EFFECTS.md). + +## `supabase warehouse connection` + +Get Warehouse Flight SQL connection details + +Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@\:443?tls=enabled'. + +- Access: read-only, no consent. +- Feature: `warehouse`. +- Request: `GET /v2/projects/{ref}/warehouse/connection` (`v2-get-warehouse-connection`), success 200 json. + +## `supabase warehouse disable` + +Disable Warehouse replication and access + +Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures. + +- Access: mutation, consent defaults to No (`--yes` when it cannot prompt). +- Feature: `warehouse`. +- Request: `DELETE /v2/projects/{ref}/warehouse` (`v2-disable-warehouse`), success 202 json. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| --------------- | ------- | -------- | ---------- | ------------------- | +| `--delete-data` | boolean | no | no | query `delete_data` | + +### Wait + +- Polls: `GET /v2/projects/{ref}/warehouse/teardowns/current` (`v2-get-warehouse-teardown`). +- Read parameters from the change response: `operation_id` from `/data/id`. +- Status at `/data/attributes/lifecycle_status`; succeeded: `disabled`; failed: `deletion_failed`. +- Failure message from `/data/attributes/cleanup_error`. +- Failure hint names `supabase warehouse teardowns get --operation-id --remote=`. + +## `supabase warehouse enable` + +Enable Warehouse replication + +Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization. + +- Access: mutation, consent defaults to No (`--yes` when it cannot prompt). +- Feature: `warehouse`. +- Request: `POST /v2/projects/{ref}/warehouse/enable` (`v2-enable-warehouse`), success 202 json. +- Body: JSON envelope `data.type = warehouse_setup`, fields under `data.attributes`. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| ----------------------------------------------------- | ------- | -------- | ---------- | ----------------------------------------------- | +| `--warehouse-region ` | string | no | no | body `/data/attributes/warehouse_region` | +| `--destination-project-ref ` | string | no | no | body `/data/attributes/destination_project_ref` | +| `--install-fdw` | boolean | no | no | body `/data/attributes/install_fdw` | +| `--schema ` | string | yes | no | body `/data/attributes/schema` | +| `--table ` | string | no | yes | body `/data/attributes/tables` | + +### Wait + +- Polls: `GET /v2/projects/{ref}/warehouse/setups/current` (`v2-get-warehouse-setup`, hidden poll target). +- Read parameters from the change response: `selection_id` from `/data/attributes/selection_id`. +- Status at `/data/attributes/status`; succeeded: `succeeded`; failed: `failed`. +- Failure message from `/data/attributes/status_error`. +- Failure hint names `supabase warehouse status --remote=`. + +## `supabase warehouse status` + +Get consolidated Warehouse status and capabilities + +Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions. + +- Access: read-only, no consent. +- Feature: `warehouse`. +- Request: `GET /v2/projects/{ref}/warehouse/status` (`v2-get-warehouse-status`), success 200 json. + +## `supabase warehouse teardowns get` + +Get Warehouse cleanup status + +Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation. + +- Access: read-only, no consent. +- Feature: `warehouse`. +- Request: `GET /v2/projects/{ref}/warehouse/teardowns/current` (`v2-get-warehouse-teardown`), success 200 json. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| ------------------------------- | ------ | -------- | ---------- | -------------------- | +| `--operation-id ` | string | no | no | query `operation_id` | + +### Wait + +- Polls: `GET /v2/projects/{ref}/warehouse/teardowns/current` (`v2-get-warehouse-teardown`, the command's own read). +- Status at `/data/attributes/lifecycle_status`; succeeded: `disabled`; failed: `deletion_failed`. +- Failure message from `/data/attributes/cleanup_error`. +- Failure hint names `supabase warehouse teardowns get [--operation-id ] --remote=`. diff --git a/apps/cli/src/commands/api/warehouse-backend.ts b/apps/cli/src/commands/api/warehouse-backend.ts deleted file mode 100644 index 96868e80cb..0000000000 --- a/apps/cli/src/commands/api/warehouse-backend.ts +++ /dev/null @@ -1,35 +0,0 @@ -import { Effect, FileSystem, Path } from "effect"; - -import { extractCommandPath, hasRootVersionFlag } from "../../shared/cli/run.ts"; -import { - type ExperimentalFeatureFlagError, - readExperimentalFeatureConfig, - resolveExperimentalFeature, -} from "../../shared/config/experimental-feature.ts"; - -/** Resolves `experimental.warehouse` only for invocations that can reach the `warehouse` group. */ -export const resolveWarehouseEnabled = (input: { - readonly args: ReadonlyArray; - readonly cwd: string; -}): Effect.Effect => - Effect.gen(function* () { - const routingArgs = - input.args[0] === "__complete" || input.args[0] === "__completeNoDesc" - ? input.args.slice(0, -1) - : input.args; - if (hasRootVersionFlag(routingArgs)) return false; - const commandPath = extractCommandPath(routingArgs); - const completePath = - commandPath[0] === "__complete" || commandPath[0] === "__completeNoDesc" - ? commandPath.slice(1) - : commandPath; - if (completePath[0] !== undefined && completePath[0] !== "warehouse") return false; - return yield* resolveExperimentalFeature({ - feature: "warehouse", - configValue: readExperimentalFeatureConfig({ - feature: "warehouse", - ...input, - args: routingArgs, - }), - }); - }); diff --git a/apps/cli/src/commands/api/warehouse/connection/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/connection/SIDE_EFFECTS.md deleted file mode 100644 index 27d8bba8e6..0000000000 --- a/apps/cli/src/commands/api/warehouse/connection/SIDE_EFFECTS.md +++ /dev/null @@ -1,101 +0,0 @@ -# `supabase warehouse connection` - -Target: hosted, no consent, see [Command target](../../../../../docs/command-target.md) - -## Feature gate - -Registered only when `experimental.warehouse` is enabled: set `[experimental] warehouse = true` or -`SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. `--experimental` alone does not expose it. When disabled the -`warehouse` group is absent from help and completion and from the generated command documentation. -The command is generated from the Management API contract (`generated.ts`). - -## Files Read - -| Path | Format | When | -| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | -| `/supabase/config.json` | JSON | when present, to resolve `experimental.warehouse` before the command tree is built | -| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | -| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential | -| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | -| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | - -## Files Written - -| Path | Format | When | -| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | -| `/telemetry.json` | JSON | always, flushed on success and on failure | -| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref | - -## API Routes - -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | ----------------------------------------- | ------------ | ------------ | --------------------------------------------------------------- | -| `GET` | `/v2/projects/{ref}/warehouse/connection` | Bearer token | none | passed through unchanged | -| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | linked-project cache miss only (best-effort, after the command) | - -No operation-specific query parameters. The command never requests or prints a password, token or -catalog credential, and does not run a Flight SQL query: `query_connectivity` stays `not_checked`. -`--dry-run` prints `{method, path, query, headers, body}` and sends no command request (the linked-project cache read in the table above can still run). - -The response describes Arrow Flight SQL access only; DuckLake catalog access is a separate contract. -`endpoint`, `host` and `port` are present only while `status` is `available` or `pending`; a -disabled, unconfigured or unavailable Warehouse prints `-` for them instead of a connection string. - -## Connecting - -Log in as a role in the source Supabase database with that role's existing password; `postgres` -uses the project's database password. The role needs `supabase_warehouse_reader` membership in the -source database, which Management API access does not grant. With -[usql](https://github.com/xo/usql), using the `host` from the output: - -```sh -usql -W 'flightsql://postgres@:443?tls=enabled' -``` - -## Exit Codes - -| Code | Condition | -| ---- | ----------------------------------------------------------------------------- | -| `0` | successful read (including not configured, disabled or unavailable Warehouse) | -| `2` | `usage_error`: invalid flags | -| `1` | API error (non-2xx) | - -## Environment Variables - -| Variable | Purpose | Required? | -| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | -| `SUPABASE_EXPERIMENTAL_WAREHOUSE` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.warehouse`) | no | -| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | -| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | -| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to `supabase/.temp/project-ref`) | -| `SUPABASE_WORKDIR` | project directory the command acts on | no (falls back to `--workdir`, then the cwd) | -| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) | - -## Telemetry Events Fired - -| Event | When | Notable properties / groups | -| ---------------------- | ------------------------------------------ | ----------------------------------- | -| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | - -Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` -records `true`. - -## Output - -Text rendering applies on a terminal by default, with `--output-format text` (also when piped), and -with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the -API's JSON bytes. `-o` takes precedence over `--output-format`. - -| Mode | stdout | -| ------------------------------ | ----------------------------------------------------------------------------------- | -| text presentation | the response as labelled fields, with authentication guidance as a nested block | -| JSON presentation | the API's JSON response bytes, unchanged | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML | -| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | - -When the presentation is text and `--output-format` is `text`, the request runs under a task. On a terminal it -is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task -message prints as a step line on stdout before the response. JSON and YAML output show no progress. diff --git a/apps/cli/src/commands/api/warehouse/disable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/disable/SIDE_EFFECTS.md deleted file mode 100644 index 3078cc8b57..0000000000 --- a/apps/cli/src/commands/api/warehouse/disable/SIDE_EFFECTS.md +++ /dev/null @@ -1,58 +0,0 @@ -# `supabase warehouse disable` - -Target: hosted. Consent defaults to No; noninteractive mutations require `--yes` or shell -`SUPABASE_YES`. Registration requires `experimental.warehouse` in project config or -`SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - -## Requests and retention - -`DELETE /v2/projects/{ref}/warehouse` starts asynchronous cleanup. Omitted `--delete-data` retains -Warehouse data; `--delete-data` sends `delete_data=true` and permanently deletes the managed -catalog schema and dedicated Storage bucket. Source Postgres tables and legacy shared buckets -remain. The server checks source administrator/database permissions and entitlement, plus -destination SQL/Storage write permissions for data deletion. - -Both modes stop replication and remove the Warehouse publication, FDW and dependent foreign -tables, reader group, external catalog access and query routing. Acceptance does not mean these -effects have completed. Reader memberships must be granted again after re-enablement. - -The response contains the cleanup identity in `data.id`, with `lifecycle_status`, `delete_data`, -`updated_at` and nullable `cleanup_error` in `data.attributes`. Safe retries return the current -operation; the server rejects a changed in-progress data policy. Failed cleanup can be partial. - -`--wait` follows the response link to -`GET /v2/projects/{ref}/warehouse/teardowns/current?operation_id=`. -It uses the shared bounded poller: 1s exponential backoff, capped at 10s, honoring a longer -`Retry-After`. The default timeout is 10m. `disabled` succeeds and `deletion_failed` fails. -Polling uses durable metadata, without an ETL, FDW or source-health dependency. A replaced or -cleared operation returns a conflict. Timeout and cancellation stop local polling only. - -`warehouse teardowns get --remote=` reads current cleanup without an operation ID. -`warehouse teardowns get --operation-id --wait --remote=` resumes observation -of the accepted disable attempt; `disable --wait` always passes this ID through its response link. -That command is read-only and needs no mutation consent. It accepts the same `--timeout` and -output options and requires database-read permission. - -## Local effects and output - -The generated runtime uses the same config, auth/profile, target resolution, linked-project cache, -and telemetry reads/writes as [warehouse enable](../enable/SIDE_EFFECTS.md). Neither command -writes source configuration or executes SQL locally. Command telemetry records generated field -values as redacted; neither cleanup responses nor error contents become telemetry properties. - -Piped and agent runs, `--output-format json|stream-json`, and `-o json` write the raw API JSON -response to stdout, preserving unknown and null fields. An interactive terminal renders the -shared text view unless an output mode is selected; `-o pretty` also selects text. `-o yaml` writes the same document as YAML. With `--wait`, stdout contains the terminal read. -Errors use the standard stderr envelope. `wait_timeout` includes `timeout_ms`, nullable -`last_status`, and the command for resuming observation; terminal text includes the last status. -`operation_failed` includes the failed status and reported cleanup error. - -`--dry-run` prints only the local request in the selected text/JSON/YAML presentation, with the -chosen deletion query, before -consent and without a command request. The post-run best-effort linked-project cache read may -still run. This is not a resolved impact preview; server preview/apply and revision checks remain -follow-up work. Consent uses the operation summary; it does not render a deletion-specific impact -plan. Permanent deletion is described in command and flag help. - -Exit 0 means acceptance, completed waiting or dry-run. Standard API/wait errors exit 1, invalid -usage or missing noninteractive consent exits 2, and cancellation exits 130. diff --git a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md deleted file mode 100644 index fce91e4c38..0000000000 --- a/apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md +++ /dev/null @@ -1,104 +0,0 @@ -# `supabase warehouse enable` - -Target: hosted, consent default No (confirm unless `--yes`; a run that cannot prompt and has no `--yes` is a usage error), see [Command target](../../../../../docs/command-target.md) - -## Feature gate - -Registered only when `experimental.warehouse` is enabled: set `[experimental] warehouse = true` or -`SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. `--experimental` alone does not expose it. When disabled the -`warehouse` group is absent from help and completion and from the generated command documentation. -The command is generated from the Management API contract (`generated.ts`). - -## Files Read - -| Path | Format | When | -| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | -| `/supabase/config.json` | JSON | when present, to resolve `experimental.warehouse` before the command tree is built | -| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | -| `` | JSON | only with `--file `: the whole request body (`--file -` reads stdin) | -| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential | -| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | -| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | - -## Files Written - -| Path | Format | When | -| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | -| `/telemetry.json` | JSON | always, flushed on success and on failure | -| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref | - -## API Routes - -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | --------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `POST` | `/v2/projects/{ref}/warehouse/enable` | Bearer token | `{"data":{"type":"warehouse_setup","attributes":{…}}}`; only the flags that were given are present | passed through unchanged; `data.attributes.selection_id` feeds `--wait` | -| `GET` | `/v2/projects/{ref}/warehouse/setups/current` | Bearer token | none | `data.attributes.status`, `status_error`; polled with backoff from 1s doubling to a 10s cap (a longer `Retry-After` wins), only with `--wait` | -| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive (project picker) | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}`; linked-project cache miss only (best-effort, after the command) | - -`--body` or `--file` supply the whole body; a flag replaces its own field and nothing else. The -input is validated before consent and before any request, so a top-level body key outside the -declared request-body fields, an unknown nested field or a missing `--schema` fails with nothing sent. `--dry-run` prints `{method, path, query, headers, body}` and sends no command request (the linked-project cache read in the table above can still run), -before consent. - -## Exit Codes - -| Code | Condition | -| ----- | ------------------------------------------------------------------------ | -| `0` | success (the request was accepted, or with `--wait` the setup succeeded) | -| `2` | `usage_error`: invalid flags or body, or consent needed without `--yes` | -| `130` | consent declined at the prompt (`cancelled`) | -| `1` | API error (non-2xx) | -| `1` | with `--wait`: `operation_failed` (a failed status) or `wait_timeout` | - -A 4xx `entitlement_required` body (`{"error":{"code":"entitlement_required","feature","upgrade_url"}}`) adds `entitlement: {feature, upgrade_url}` to the stderr error document in place of the token-permission hint; a terminal run prints the upgrade hint, and `cli_upgrade_suggested` fires. Other statuses and bodies carry no `entitlement` key. - -## Environment Variables - -| Variable | Purpose | Required? | -| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | -| `SUPABASE_EXPERIMENTAL_WAREHOUSE` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.warehouse`) | no | -| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | -| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | -| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to `supabase/.temp/project-ref`) | -| `SUPABASE_WORKDIR` | project directory the command acts on | no (falls back to `--workdir`, then the cwd) | -| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) | - -## Telemetry Events Fired - -| Event | When | Notable properties / groups | -| ---------------------- | ------------------------------------------ | ----------------------------------- | -| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | - -Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` -and `--wait` record `true`. Generated field flags, `--body`, `--file` and `--timeout` are recorded as -``. - -## Output - -Text rendering applies on a terminal by default, with `--output-format text` (also when piped), and -with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the -API's JSON bytes. `-o` takes precedence over `--output-format`. - -| Mode | stdout | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | -| text presentation | the response as labelled fields and tables; with `--wait` the final status response; an empty response prints `Done.` | -| JSON presentation | the API's JSON response bytes, unchanged; with `--wait` the final status response | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | -| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | - -When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the -whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it -is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task -message prints as a step line on stdout before the response. JSON and YAML output show no progress. - -## Notes - -- `--wait` polls the setup endpoint internally; it does not expose a separate setup command, so a failed or timed-out wait carries the hint ``Check it with `supabase warehouse status --remote=`.`` - -- Repeating the same selection is safe; the API rejects a different existing selection. -- `--wait` fails only on a status in the failed set; `status_error` supplies the failure message and does not end the wait by itself. -- `data.attributes.selection_id` is required in the accepted response; a response without it is a defect and ends `--wait` with an internal error, never a silent success. -- `--wait` never resumes after a 409; any non-2xx while polling ends the command with the API error. diff --git a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md deleted file mode 100644 index 6a88659b56..0000000000 --- a/apps/cli/src/commands/api/warehouse/status/SIDE_EFFECTS.md +++ /dev/null @@ -1,93 +0,0 @@ -# `supabase warehouse status` - -Target: hosted, no consent, see [Command target](../../../../../docs/command-target.md) - -## Feature gate - -Registered only when `experimental.warehouse` is enabled: set `[experimental] warehouse = true` or -`SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. `--experimental` alone does not expose it. When disabled the -`warehouse` group is absent from help and completion and from the generated command documentation. -The command is generated from the Management API contract (`generated.ts`). - -## Files Read - -| Path | Format | When | -| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | -| `/supabase/config.json` | JSON | when present, to resolve `experimental.warehouse` before the command tree is built | -| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | -| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential | -| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | -| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | - -## Files Written - -| Path | Format | When | -| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | -| `/telemetry.json` | JSON | always, flushed on success and on failure | -| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref | - -## API Routes - -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | ------------------------------------- | ------------ | ------------ | --------------------------------------------------------------- | -| `GET` | `/v2/projects/{ref}/warehouse/status` | Bearer token | none | passed through unchanged | -| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | linked-project cache miss only (best-effort, after the command) | - -No operation-specific query parameters or FDW inspection. -`--dry-run` prints `{method, path, query, headers, body}` and sends no command request (the linked-project cache read in the table above can still run). - -The response preserves enabled state independently of selected table count, configured readiness, -query connectivity, lifecycle, per-observation availability and capabilities. `observed_at` is -retrieval time; it is separate from table sync lag, pipeline apply lag and feedback age. -This read has no waiter. `warehouse enable --wait` observes enablement; `warehouse teardowns get --wait` -observes cleanup. Their operation identities and bounded waiting remain separate. - -## Exit Codes - -| Code | Condition | -| ---- | ----------------------------------------------------------------------- | -| `0` | successful status read (including disabled or unavailable observations) | -| `2` | `usage_error`: invalid flags | -| `1` | API error (non-2xx, including 409) | - -A 4xx `entitlement_required` body (`{"error":{"code":"entitlement_required","feature","upgrade_url"}}`) adds `entitlement: {feature, upgrade_url}` to the stderr error document in place of the token-permission hint; a terminal run prints the upgrade hint, and `cli_upgrade_suggested` fires. Other statuses and bodies carry no `entitlement` key. - -## Environment Variables - -| Variable | Purpose | Required? | -| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | -| `SUPABASE_EXPERIMENTAL_WAREHOUSE` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.warehouse`) | no | -| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | -| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | -| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to `supabase/.temp/project-ref`) | -| `SUPABASE_WORKDIR` | project directory the command acts on | no (falls back to `--workdir`, then the cwd) | -| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) | - -## Telemetry Events Fired - -| Event | When | Notable properties / groups | -| ---------------------- | ------------------------------------------ | ----------------------------------- | -| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | - -Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` -records `true`. - -## Output - -Text rendering applies on a terminal by default, with `--output-format text` (also when piped), and -with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the -API's JSON bytes. `-o` takes precedence over `--output-format`. - -| Mode | stdout | -| ------------------------------ | ----------------------------------------------------------------------------------- | -| text presentation | the response as labelled fields and tables; an empty response prints `Done.` | -| JSON presentation | the API's JSON response bytes, unchanged | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML | -| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | - -When the presentation is text and `--output-format` is `text`, the request runs under a task. On a terminal it -is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task -message prints as a step line on stdout before the response. JSON and YAML output show no progress. diff --git a/apps/cli/src/commands/api/warehouse/teardowns/get/SIDE_EFFECTS.md b/apps/cli/src/commands/api/warehouse/teardowns/get/SIDE_EFFECTS.md deleted file mode 100644 index 95419cf7e4..0000000000 --- a/apps/cli/src/commands/api/warehouse/teardowns/get/SIDE_EFFECTS.md +++ /dev/null @@ -1,21 +0,0 @@ -# `supabase warehouse teardowns get` - -Target: hosted. This read-only command requires the Warehouse family feature gate and no mutation -consent. It calls `GET /v2/projects/{ref}/warehouse/teardowns/current` with bearer authentication. -Omit `--operation-id` to read current cleanup; supply it to pin the read to a specific disable -attempt through the `operation_id` query. The server checks database-read permission -and OAuth scope, then reads durable primary metadata without checking source health, ETL or FDW. - -Piped/agent output and explicit JSON modes preserve the raw JSON response; `-o yaml` encodes -the same document. Interactive terminals use the shared text renderer. Unknown and null -observations remain unchanged in machine output. `--wait` repeats this read until `disabled` or `deletion_failed`, -with the shared backoff and bounded timeout. Without an operation ID, each read observes current -cleanup. A supplied ID that no longer matches fails with a conflict. Missing cleanup state, -including after re-enablement clears it, fails with a conflict in either mode. -Polling does not modify Warehouse state. `--dry-run` prints only the local request, without a -status read. - -The local config/profile/auth reads, linked-project cache, telemetry writes, output, wait-error -context and exit codes are shared with [warehouse disable](../../disable/SIDE_EFFECTS.md). -It does not write project config or read stdin. Post-run best-effort cache requests and telemetry -flushes still run on success, dry-run or failure. diff --git a/apps/cli/src/config/cli-config-flag-ownership.unit.test.ts b/apps/cli/src/config/cli-config-flag-ownership.unit.test.ts index 3862db6796..c053a5e799 100644 --- a/apps/cli/src/config/cli-config-flag-ownership.unit.test.ts +++ b/apps/cli/src/config/cli-config-flag-ownership.unit.test.ts @@ -14,7 +14,11 @@ const declarations: ReadonlyArray<{ path: string; names: ReadonlyArray } const ownerOf = new Map(declarations.flatMap(({ path, names }) => names.map((n) => [n, path]))); const commands = walkCommandTree( - rootCommandForFeatures({ stackBackend: "stack", computeEnabled: true, warehouseEnabled: true }), + rootCommandForFeatures({ + stackBackend: "stack", + computeEnabled: true, + apiFeatures: ["warehouse"], + }), ); const ownedFlags = commands.flatMap((entry) => diff --git a/apps/cli/src/shared/config/experimental-feature.ts b/apps/cli/src/shared/config/experimental-feature.ts index a38a3b6264..13497985cb 100644 --- a/apps/cli/src/shared/config/experimental-feature.ts +++ b/apps/cli/src/shared/config/experimental-feature.ts @@ -45,7 +45,7 @@ const readEnv = (name: string) => /** Reads one experimental feature, treating unavailable or invalid configuration as unset. */ export const readExperimentalFeatureConfig = (input: { - readonly feature: keyof typeof featureSchemas; + readonly feature: ExperimentalFeature; readonly args: ReadonlyArray; readonly cwd: string; }): Effect.Effect => @@ -80,12 +80,15 @@ const featureKeys = { warehouse: CliConfigKeys.experimental.warehouse, } as const; +/** Name of an `experimental.` config key. */ +export type ExperimentalFeature = keyof typeof featureKeys; + /** * Resolves one experimental boolean: a shell boolean override, else the project * config. Remotes and project `.env*` files do not apply. */ export const resolveExperimentalFeature = (input: { - readonly feature: keyof typeof featureKeys; + readonly feature: ExperimentalFeature; readonly configValue: Effect.Effect; }): Effect.Effect => Effect.gen(function* () { diff --git a/apps/cli/tests/helpers/command-flags.unit.test.ts b/apps/cli/tests/helpers/command-flags.unit.test.ts index cf615f67de..904b2ffe24 100644 --- a/apps/cli/tests/helpers/command-flags.unit.test.ts +++ b/apps/cli/tests/helpers/command-flags.unit.test.ts @@ -54,6 +54,6 @@ describe("commandTreeFor", () => { expect(tree.has("compute list")).toBe(false); expect(commandTreeFor({ computeEnabled: true }).has("compute list")).toBe(true); expect(tree.has("warehouse enable")).toBe(false); - expect(commandTreeFor({ warehouseEnabled: true }).has("warehouse enable")).toBe(true); + expect(commandTreeFor({ apiFeatures: ["warehouse"] }).has("warehouse enable")).toBe(true); }); }); diff --git a/turbo.json b/turbo.json index 3bcd52e0e6..dd4a9f0ec9 100644 --- a/turbo.json +++ b/turbo.json @@ -90,13 +90,17 @@ "dependsOn": ["@supabase/api#generate"], "inputs": [ "$TURBO_DEFAULT$", - "!src/commands/api/generated*.ts", + "!src/commands/api/generated*", "$TURBO_ROOT$/mise.lock", "$TURBO_ROOT$/.oxfmtrc.json", "$TURBO_ROOT$/packages/api/src/generated/openapi.json", "$TURBO_ROOT$/packages/api/src/generated/contracts.ts" ], - "outputs": ["src/commands/api/generated.ts", "src/commands/api/generated.schemas.ts"] + "outputs": [ + "src/commands/api/generated.ts", + "src/commands/api/generated.schemas.ts", + "src/commands/api/generated.md" + ] }, "supabase#test:live": { "cache": false, From 80e09216c2c6d6849228c725769ced7d4fd2695c Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 14:41:13 +0100 Subject: [PATCH 13/45] chore(cli): declare poll-only reads in the API spec A read that a `--wait` polls without being a command now carries `x-operation: { poll: { ..., inspect } }` with no `group`/`method`. The generator finds it through the response links of the generated operations, and `poll.inspect` names the operation whose command the failure and timeout hint points to. This replaces the `pollTargets` map in the command policy. The runtime and the generated command files are unchanged. --- apps/cli/scripts/api-command-derive.ts | 230 +++++++++-------- .../scripts/api-command-derive.unit.test.ts | 231 ++++++++++++------ apps/cli/scripts/generate-api-commands.ts | 7 +- apps/cli/src/commands/api/SIDE_EFFECTS.md | 2 +- .../src/commands/api/api-command-policy.ts | 11 +- .../api-command-shapes.integration.test.ts | 1 - packages/api/scripts/openapi-overrides.json | 7 +- packages/api/src/generated/openapi.json | 5 +- 8 files changed, 294 insertions(+), 200 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index f7d1af08ef..311dbefd46 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -1,10 +1,6 @@ import type { OperationId } from "@supabase/api/effect"; import { Cause, Exit, Predicate, Schema } from "effect"; -import { - verbVocabulary, - type ApiCommandPoll, - type ApiNoun, -} from "../src/commands/api/api-command-policy.ts"; +import { verbVocabulary, type ApiNoun } from "../src/commands/api/api-command-policy.ts"; import type { ApiCommandBinding, ApiCommandEntry, @@ -65,29 +61,77 @@ const StatusMapping = { error: Schema.optionalKey(Schema.String), }; -interface XOperation { - readonly group: string; - readonly method: string; - readonly poll?: ApiCommandPoll; -} +/** How to tell that the resource a read operation returns has settled. */ +type ApiCommandPoll = Pick; -const XOperationSchema: Schema.Codec = Schema.Struct({ - group: Schema.String, - method: Schema.String, - poll: Schema.optionalKey(Schema.Struct(StatusMapping)), +const XOperationSchema = Schema.Struct({ + group: Schema.optionalKey(Schema.String), + method: Schema.optionalKey(Schema.String), + poll: Schema.optionalKey( + Schema.Struct({ ...StatusMapping, inspect: Schema.optionalKey(Schema.String) }), + ), }); const decodeXOperation = Schema.decodeUnknownExit(XOperationSchema, { onExcessProperty: "error", }); +/** A named command, or a poll-only read that never becomes a command. */ +type ParsedXOperation = + | { + readonly kind: "named"; + readonly group: string; + readonly method: string; + readonly poll?: ApiCommandPoll; + } + | { readonly kind: "pollOnly"; readonly poll: ApiCommandPoll; readonly inspect: string } + | { readonly kind: "invalid"; readonly reason: string }; + +const statusMapping = (poll: ApiCommandPoll): ApiCommandPoll => ({ + status: poll.status, + succeeded: poll.succeeded, + failed: poll.failed, + ...(poll.error === undefined ? {} : { error: poll.error }), +}); + +const parseXOperation = (block: unknown): ParsedXOperation => { + const decoded = decodeXOperation(block); + if (Exit.isFailure(decoded)) return { kind: "invalid", reason: Cause.pretty(decoded.cause) }; + const { group, method, poll } = decoded.value; + if (group === undefined && method === undefined) { + if (poll === undefined) { + return { kind: "invalid", reason: "set group and method, or a poll-only read's poll" }; + } + if (poll.inspect === undefined || poll.inspect === "") { + return { + kind: "invalid", + reason: "a poll-only read must set poll.inspect to the operation that inspects its state", + }; + } + return { kind: "pollOnly", poll: statusMapping(poll), inspect: poll.inspect }; + } + if (group === undefined || method === undefined) { + return { kind: "invalid", reason: "a command name needs both group and method" }; + } + if (poll?.inspect !== undefined) { + return { + kind: "invalid", + reason: "poll.inspect belongs on a poll-only read, not on a named operation", + }; + } + return { + kind: "named", + group, + method, + ...(poll === undefined ? {} : { poll: statusMapping(poll) }), + }; +}; + interface DeriveInput { /** The parsed OpenAPI document. */ readonly spec: JsonObject; - /** Operation ids that generate commands; `x-operation` on any other operation is ignored. */ + /** Operation ids that generate commands; the roots whose response `links` are followed. */ readonly generated: ReadonlyArray; - /** Hidden polling operation id to the generated operation whose command inspects its state. */ - readonly pollTargets: Readonly>; readonly nouns: Readonly>; /** Kebab-case operation id to the camelCase key of the typed client's `operationDefinitions`. */ readonly operationIdMap: Readonly>; @@ -522,12 +566,18 @@ const readMetadata = ( problems.push(`${operationId}: no command name; set x-operation group and method`); continue; } - const decoded = decodeXOperation(block); - if (Exit.isFailure(decoded)) { - problems.push(`${operationId}: invalid x-operation: ${Cause.pretty(decoded.cause)}`); + const parsed = parseXOperation(block); + if (parsed.kind === "invalid") { + problems.push(`${operationId}: invalid x-operation: ${parsed.reason}`); + continue; + } + if (parsed.kind === "pollOnly") { + problems.push( + `${operationId}: a poll-only read cannot be generated; give it group and method or remove it from the generated operations`, + ); continue; } - const { group, method, poll } = decoded.value; + const { group, method, poll } = parsed; metadata.set(operationId, { group, method, ...(poll === undefined ? {} : { poll }) }); if (poll !== undefined && operation.method !== "GET") { problems.push(`${operationId}: poll belongs on a read operation, not ${operation.method}`); @@ -536,44 +586,6 @@ const readMetadata = ( return metadata; }; -/** Reads each internal polling target's `poll` and checks its map entry against the generated operations. */ -const readPollTargets = ( - operations: ReadonlyMap, - generated: ReadonlyArray, - targets: Readonly>, - problems: Array, -): ReadonlyMap => { - const polls = new Map(); - for (const [targetId, inspectId] of Object.entries(targets)) { - const fail = (reason: string) => problems.push(`${targetId}: ${reason}`); - const target = operations.get(targetId); - if (target === undefined) { - fail("polling target has no operation in the spec"); - continue; - } - if (generated.includes(targetId)) { - fail("polling target is also a generated operation; remove it from pollTargets"); - } - if (!generated.includes(inspectId)) { - fail(`inspect operation "${inspectId}" is not a generated operation`); - } - const block = target.node["x-operation"]; - if (block === undefined) { - fail("polling target has no x-operation poll"); - continue; - } - const decoded = decodeXOperation(block); - if (Exit.isFailure(decoded)) { - fail(`invalid x-operation: ${Cause.pretty(decoded.cause)}`); - } else if (decoded.value.poll === undefined) { - fail("polling target declares no poll"); - } else { - polls.set(targetId, decoded.value.poll); - } - } - return polls; -}; - const requireExperimental = (operation: Operation, fail: (reason: string) => void): void => { if (asString(operation.node["x-scalar-stability"]) !== "experimental") { fail("only operations marked experimental can be generated (x-scalar-stability)"); @@ -582,12 +594,31 @@ const requireExperimental = (operation: Operation, fail: (reason: string) => voi const requireOneWait = ( ownPoll: ApiCommandPoll | undefined, - linked: ApiCommandWait | undefined, + linkedRead: string | undefined, fail: (reason: string) => void, ): void => { - if (ownPoll !== undefined && linked !== undefined) { - fail(`declares poll and also links to the polled operation "${linked.read}"; use one`); + if (ownPoll !== undefined && linkedRead !== undefined) { + fail(`declares poll and also links to the polled operation "${linkedRead}"; use one`); + } +}; + +/** The first operation declaring `poll` that an operation's 2xx response `links` target. */ +const polledLinkTarget = ( + spec: JsonObject, + operations: ReadonlyMap, + operation: Operation, +): string | undefined => { + const responses = asRecord(operation.node.responses) ?? {}; + for (const code of Object.keys(responses).sort()) { + if (!code.startsWith("2")) continue; + const links = asRecord(asRecord(resolve(spec, responses[code]))?.links) ?? {}; + for (const rawLink of Object.values(links)) { + const targetId = asString(asRecord(resolve(spec, rawLink))?.operationId); + const target = targetId === undefined ? undefined : operations.get(targetId); + if (asRecord(target?.node["x-operation"])?.poll !== undefined) return targetId; + } } + return undefined; }; const pollWait = ( @@ -606,16 +637,23 @@ const pollWait = ( const RESPONSE_POINTER = /^\$response\.body#(\/.*)$/u; const REQUEST_PATH = /^\$request\.path\.(.+)$/u; +/** A poll-only read reached through a response link, with the operation that inspects its state. */ +interface HiddenRead { + readonly poll: ApiCommandPoll; + readonly inspect: string; +} + /** * The wait a command's 2xx response `links` declare: the one link whose target operation has - * `poll`. The target is a generated operation or a listed polling target; links without `poll` - * are ignored. + * `poll`. The target is a generated operation or a poll-only read, which is recorded in `hidden`; + * links without `poll` are ignored. */ const linkedWait = ( spec: JsonObject, operations: ReadonlyMap, - polls: ReadonlyMap, + metadata: ReadonlyMap, generated: ReadonlyArray, + hidden: Map, operation: Operation, fail: (reason: string) => void, ): ApiCommandWait | undefined => { @@ -636,18 +674,27 @@ const linkedWait = ( fail(`link "${linkName}" targets unknown operation "${targetId}"`); continue; } - const poll = polls.get(targetId); - if (poll === undefined) { - if ( - !generated.includes(targetId) && - asRecord(target.node["x-operation"])?.poll !== undefined - ) { + let poll: ApiCommandPoll | undefined; + if (generated.includes(targetId)) { + poll = metadata.get(targetId)?.poll; + } else { + const block = target.node["x-operation"]; + if (block === undefined) continue; + const parsed = parseXOperation(block); + if (parsed.kind === "invalid") { fail( - `link "${linkName}" targets polled operation "${targetId}", which is neither generated nor listed in pollTargets`, + `link "${linkName}" targets "${targetId}", whose x-operation is invalid: ${parsed.reason}`, + ); + } else if (parsed.kind === "pollOnly") { + poll = parsed.poll; + hidden.set(targetId, { poll, inspect: parsed.inspect }); + } else if (parsed.poll !== undefined) { + fail( + `link "${linkName}" targets polled operation "${targetId}", which is neither a generated command nor a poll-only read`, ); } - continue; } + if (poll === undefined) continue; const params: Record = {}; for (const [parameter, expression] of Object.entries(asRecord(link.parameters) ?? {})) { @@ -689,23 +736,11 @@ const linkedWait = ( /** Derives the generated commands from each operation's `x-operation` and collects every lint failure. */ export function deriveApiCommands(input: DeriveInput): DeriveResult { - const { - spec, - generated, - pollTargets: pollTargetMap, - nouns, - operationIdMap, - handWrittenTopLevel, - } = input; + const { spec, generated, nouns, operationIdMap, handWrittenTopLevel } = input; const operations = collectOperations(spec); const problems: Array = []; const metadata = readMetadata(operations, generated, problems); - const polls = new Map(); - for (const [operationId, name] of metadata) { - if (name.poll !== undefined) polls.set(operationId, name.poll); - } - const hiddenPolls = readPollTargets(operations, generated, pollTargetMap, problems); - for (const [operationId, poll] of hiddenPolls) polls.set(operationId, poll); + const hidden = new Map(); const entries: Array = []; const schemas: Record = {}; const commandOwners = new Map(); @@ -1009,9 +1044,9 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { }); } - const linked = linkedWait(spec, operations, polls, generated, operation, fail); + const linked = linkedWait(spec, operations, metadata, generated, hidden, operation, fail); const ownPoll = name.poll; - requireOneWait(ownPoll, linked, fail); + requireOneWait(ownPoll, linked?.read, fail); const wait = linked ?? (ownPoll === undefined ? undefined : pollWait(operationId, {}, ownPoll)); if (wait !== undefined) { lintWait({ spec, operations, operation, wait, fail }); @@ -1074,27 +1109,22 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { left.command.join(" ").localeCompare(right.command.join(" "), "en"), ); const pollTargets: Array = []; - const reached = new Set( - entries.flatMap((entry) => (entry.wait === undefined ? [] : [entry.wait.read])), - ); - for (const [operationId, inspectId] of Object.entries(pollTargetMap).toSorted(([a], [b]) => + for (const [operationId, { poll, inspect: inspectId }] of [...hidden].toSorted(([a], [b]) => a.localeCompare(b, "en"), )) { const operation = operations.get(operationId); - const poll = hiddenPolls.get(operationId); - if (operation === undefined || poll === undefined) continue; + if (operation === undefined) continue; const fail = (reason: string) => problems.push(`${operationId}: ${reason}`); - if (!reached.has(operationId)) { - fail("polling target is not linked from any generated operation; remove it from pollTargets"); - continue; - } const definition = operationIdMap[operationId]; if (definition === undefined) { fail("polling target is missing from the typed client; regenerate @supabase/api"); continue; } requireExperimental(operation, fail); - requireOneWait(poll, linkedWait(spec, operations, polls, generated, operation, fail), fail); + requireOneWait(poll, polledLinkTarget(spec, operations, operation), fail); + if (!generated.includes(inspectId)) { + fail(`inspect operation "${inspectId}" is not a generated operation`); + } const inspect = entries.find((entry) => entry.operationId === inspectId); if ( inspect !== undefined && diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index d6498ee5e1..4df7577b0e 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -77,7 +77,6 @@ const derive = ( }, }, generated, - pollTargets: {}, nouns: { thing: thingNoun }, operationIdMap: Object.fromEntries( Object.keys(operations).map((id) => [id, "v2EnableWarehouse" as const]), @@ -532,16 +531,21 @@ describe("deriveApiCommands", () => { }, }, }; - const readWith = (readPoll: unknown, responses: unknown = jsonResponse(readSchema)) => + const readOf = (xOperation: unknown, responses: unknown = jsonResponse(readSchema)) => operation({ - "x-operation": { group: "thing", method: "get", poll: readPoll }, + "x-operation": xOperation, parameters: [ { name: "ref", in: "path", required: true, schema: { type: "string" } }, { name: "thing_id", in: "query", schema: { type: "string" } }, ], responses, }); + const readWith = (readPoll: unknown, responses?: unknown) => + readOf({ group: "thing", method: "get", poll: readPoll }, responses); + const hiddenWith = (readPoll: object, responses?: unknown, inspect = "get-inspect") => + readOf({ poll: { ...readPoll, inspect } }, responses); const readThing = readWith(poll); + const hiddenThing = hiddenWith(poll); const link = (parameters: Record, operationId = "get-thing") => ({ setup: { operationId, parameters }, }); @@ -550,15 +554,9 @@ describe("deriveApiCommands", () => { const waitOf = (result: ReturnType) => result.entries.find((entry) => entry.operationId === "create-thing")?.wait; const inspectThing = operation(named("status")); - /** `create-thing` and an inspect command are generated; each listed polling target stays hidden. */ - const deriveHidden = ( - operations: Record, - targets: Record = { "get-thing": "get-inspect" }, - inspect: unknown = inspectThing, - ) => - derive({ ...operations, "get-inspect": inspect }, ["create-thing", "get-inspect"], { - overrides: { pollTargets: targets }, - }); + /** `create-thing` and an inspect command are generated; poll-only reads stay hidden. */ + const deriveHidden = (operations: Record, inspect: unknown = inspectThing) => + derive({ ...operations, "get-inspect": inspect }, ["create-thing", "get-inspect"]); it("builds the wait from the polled target and leaves the shared path parameter to the runtime", () => { const result = derive({ @@ -643,12 +641,12 @@ describe("deriveApiCommands", () => { expect(waitOf(result)).toBeUndefined(); }); - it("keeps a listed polling target internal and records the command that inspects it", () => { + it("keeps a poll-only read internal and records the command that inspects it", () => { const result = deriveHidden({ "create-thing": changeThing( link({ ref: "$request.path.ref", thing_id: "$response.body#/data/id" }), ), - "get-thing": readThing, + "get-thing": hiddenThing, }); expect(result.problems).toEqual([]); @@ -673,44 +671,122 @@ describe("deriveApiCommands", () => { expect(result.schemas["get-thing"]?.result).toEqual({ $schema: DIALECT, ...readSchema }); }); - it("rejects a link to a polled operation that is neither generated nor listed", () => { + it("records a poll-only read once when several mutations link to it", () => { + const result = derive( + { + "create-thing": changeThing(link({ thing_id: "$response.body#/data/id" })), + "update-thing": operation({ + ...named("update"), + responses: changeResponse(link({ thing_id: "$response.body#/data/id" })), + }), + "get-thing": hiddenThing, + "get-inspect": inspectThing, + }, + ["create-thing", "update-thing", "get-inspect"], + ); + + expect(result.problems).toEqual([]); + expect(result.entries.map((entry) => [entry.operationId, entry.wait?.read])).toEqual([ + ["create-thing", "get-thing"], + ["get-inspect", undefined], + ["update-thing", "get-thing"], + ]); + expect(result.pollTargets.map((target) => target.operationId)).toEqual(["get-thing"]); + }); + + it("ignores a poll-only read that no generated operation links to", () => { + const result = deriveHidden({ + "create-thing": operation(create), + "get-thing": hiddenThing, + }); + + expect(result.problems).toEqual([]); + expect(result.pollTargets).toEqual([]); + expect(result.schemas["get-thing"]).toBeUndefined(); + }); + + it("rejects a link to a named polled operation that is not generated", () => { const result = derive({ "create-thing": changeThing(link({})), "get-thing": readThing }, [ "create-thing", ]); - expect(result.problems.join("\n")).toContain( - 'targets polled operation "get-thing", which is neither generated nor listed in pollTargets', - ); + expect(result.problems).toEqual([ + 'create-thing: link "setup" targets polled operation "get-thing", which is neither a generated command nor a poll-only read', + ]); expect(result.pollTargets).toEqual([]); }); - it("rejects a listed polling target that no generated operation links to", () => { + it("rejects a poll-only read without an inspect operation", () => { const result = deriveHidden({ - "create-thing": operation(create), - "get-thing": readThing, + "create-thing": changeThing(link({})), + "get-thing": readOf({ poll }), + }); + + expect(result.problems).toEqual([ + 'create-thing: link "setup" targets "get-thing", whose x-operation is invalid: a poll-only read must set poll.inspect to the operation that inspects its state', + ]); + }); + + it.each([ + ["a misspelled poll key", { pool: { ...poll, inspect: "get-inspect" } }, "pool"], + ["a partial command name", { group: "thing" }, "a command name needs both group and method"], + ])("rejects a linked read whose x-operation has %s", (_label, xOperation, reason) => { + const result = deriveHidden({ + "create-thing": changeThing(link({})), + "get-thing": readOf(xOperation), }); + expect(result.problems).toHaveLength(1); + expect(result.problems[0]).toContain( + 'create-thing: link "setup" targets "get-thing", whose x-operation is invalid', + ); + expect(result.problems[0]).toContain(reason); + expect(waitOf(result)).toBeUndefined(); + }); + + it("rejects inspect on a named operation", () => { + const result = derive({ + "get-thing": readOf({ + group: "thing", + method: "get", + poll: { ...poll, inspect: "get-inspect" }, + }), + }); + + expect(result.problems).toEqual([ + "get-thing: invalid x-operation: poll.inspect belongs on a poll-only read, not on a named operation", + ]); + }); + + it.each([ + ["group without method", { group: "thing" }], + ["method without group", { method: "create" }], + ])("rejects a command name with %s", (_label, xOperation) => { + const result = derive({ "create-thing": operation({ "x-operation": xOperation }) }); + expect(result.problems).toEqual([ - "get-thing: polling target is not linked from any generated operation; remove it from pollTargets", + "create-thing: invalid x-operation: a command name needs both group and method", ]); }); - it("rejects a listed polling target that is also generated", () => { + it("rejects a poll-only read listed as a generated operation", () => { const result = derive( - { "create-thing": changeThing(link({})), "get-thing": readThing }, + { + "create-thing": changeThing(link({})), + "get-thing": hiddenThing, + "get-inspect": inspectThing, + }, ["create-thing", "get-thing", "get-inspect"], - { overrides: { pollTargets: { "get-thing": "get-inspect" } } }, ); - expect(result.problems.join("\n")).toContain( - "get-thing: polling target is also a generated operation", - ); + expect(result.problems).toEqual([ + "get-thing: a poll-only read cannot be generated; give it group and method or remove it from the generated operations", + ]); }); it("rejects an inspect command that needs input beyond the project ref", () => { const result = deriveHidden( - { "create-thing": changeThing(link({})), "get-thing": readThing }, - { "get-thing": "get-inspect" }, + { "create-thing": changeThing(link({})), "get-thing": hiddenThing }, operation({ ...named("status"), parameters: [ @@ -729,11 +805,10 @@ describe("deriveApiCommands", () => { const result = derive( { "create-thing": changeThing(link({})), - "get-thing": readThing, + "get-thing": hiddenWith(poll, undefined, "reset-thing"), "reset-thing": operation(named("delete")), }, ["create-thing", "reset-thing"], - { overrides: { pollTargets: { "get-thing": "reset-thing" } } }, ); expect(result.problems).toEqual([ @@ -742,40 +817,53 @@ describe("deriveApiCommands", () => { }); it("rejects an inspect operation that is not generated", () => { - const result = deriveHidden( - { "create-thing": changeThing(link({})), "get-thing": readThing }, - { "get-thing": "get-missing" }, - ); + const result = deriveHidden({ + "create-thing": changeThing(link({})), + "get-thing": hiddenWith(poll, undefined, "get-missing"), + }); - expect(result.problems.join("\n")).toContain( - 'inspect operation "get-missing" is not a generated operation', - ); + expect(result.problems).toEqual([ + 'get-thing: inspect operation "get-missing" is not a generated operation', + ]); }); - it("rejects a listed polling target that declares poll and also links to a polled operation", () => { - const result = deriveHidden( - { - "create-thing": changeThing(link({})), - "get-thing": operation({ - ...readThing, - responses: { - "200": { ...jsonResponse(readSchema)["200"], links: link({}, "get-other") }, - }, - }), - "get-other": readThing, - }, - { "get-thing": "get-inspect", "get-other": "get-inspect" }, - ); + it("rejects a poll-only read that declares poll and also links to a polled operation", () => { + const result = deriveHidden({ + "create-thing": changeThing(link({})), + "get-thing": operation({ + ...hiddenThing, + responses: { + "200": { ...jsonResponse(readSchema)["200"], links: link({}, "get-other") }, + }, + }), + "get-other": hiddenThing, + }); expect(result.problems.join("\n")).toContain( 'get-thing: declares poll and also links to the polled operation "get-other"; use one', ); }); - it("rejects a listed polling target that is not experimental", () => { + it("ignores an invalid x-operation on an operation only a poll-only read links to", () => { const result = deriveHidden({ "create-thing": changeThing(link({})), - "get-thing": { ...readThing, "x-scalar-stability": "stable" }, + "get-thing": operation({ + ...hiddenThing, + responses: { + "200": { ...jsonResponse(readSchema)["200"], links: link({}, "get-other") }, + }, + }), + "get-other": readOf({ group: "thing" }), + }); + + expect(result.problems).toEqual([]); + expect(result.pollTargets.map((target) => target.operationId)).toEqual(["get-thing"]); + }); + + it("rejects a poll-only read that is not experimental", () => { + const result = deriveHidden({ + "create-thing": changeThing(link({})), + "get-thing": { ...hiddenThing, "x-scalar-stability": "stable" }, }); expect(result.problems).toEqual([ @@ -784,48 +872,41 @@ describe("deriveApiCommands", () => { }); it.each([ - ["a mutation", "update-thing", readThing, "must use GET"], + ["a mutation", "update-thing", hiddenThing, "must use GET"], [ "a request body", "get-thing", - { ...readThing, requestBody: envelope({}) }, + { ...hiddenThing, requestBody: envelope({}) }, "must not require a request body", ], [ "no project scope", "get-thing", - { ...readThing, parameters: [] }, + { ...hiddenThing, parameters: [] }, "must be scoped by a project ref path parameter", ], [ "invalid poll metadata", "get-thing", - readWith({ ...poll, succeeded: "done" }), - "invalid x-operation", + hiddenWith({ ...poll, succeeded: "done" }), + "whose x-operation is invalid", ], - ] as const)("rejects a listed polling target with %s", (_label, id, read, message) => { - const result = deriveHidden( - { "create-thing": changeThing(link({}, id)), [id]: read }, - { - [id]: "get-inspect", - }, - ); + ] as const)("rejects a poll-only read with %s", (_label, id, read, message) => { + const result = deriveHidden({ "create-thing": changeThing(link({}, id)), [id]: read }); expect(result.problems.join("\n")).toContain(message); - expect(result.pollTargets).toEqual([]); }); - it("rejects a listed polling target missing from the typed client", () => { + it("rejects a poll-only read missing from the typed client", () => { const result = derive( { "create-thing": changeThing(link({})), - "get-thing": readThing, + "get-thing": hiddenThing, "get-inspect": inspectThing, }, ["create-thing", "get-inspect"], { overrides: { - pollTargets: { "get-thing": "get-inspect" }, operationIdMap: { "create-thing": "v2EnableWarehouse", "get-inspect": "v2EnableWarehouse", @@ -880,23 +961,23 @@ describe("deriveApiCommands", () => { it.each([ [ "an error pointer the read response does not have", - readWith({ ...poll, error: "/data/attributes/nope" }), + hiddenWith({ ...poll, error: "/data/attributes/nope" }), 'wait.error pointer "/data/attributes/nope" does not resolve in the get-thing response', ], [ "an empty succeeded list", - readWith({ ...poll, succeeded: [] }), + hiddenWith({ ...poll, succeeded: [] }), "wait.succeeded must list at least one status", ], [ "a status outside the status enum", - readWith({ ...poll, failed: ["bogus"] }), + hiddenWith({ ...poll, failed: ["bogus"] }), 'wait status "bogus" is not in the status enum of get-thing', ], [ "a required read parameter the link does not supply", operation({ - ...readThing, + ...hiddenThing, parameters: [ { name: "ref", in: "path", required: true, schema: { type: "string" } }, { name: "thing_id", in: "query", required: true, schema: { type: "string" } }, diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index a21f506e0b..1b95cdf472 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -1,11 +1,7 @@ import { BunRuntime, BunServices } from "@effect/platform-bun"; import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; -import { - generatedOperations, - nouns, - pollTargets as pollTargetMap, -} from "../src/commands/api/api-command-policy.ts"; +import { generatedOperations, nouns } from "../src/commands/api/api-command-policy.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { renderApiCommandReference } from "./api-command-reference.ts"; import { @@ -97,7 +93,6 @@ const main = Effect.gen(function* () { const { entries, pollTargets, schemas, problems } = deriveApiCommands({ spec, generated: generatedOperations, - pollTargets: pollTargetMap, nouns, operationIdMap: openApiOperationIdMap, handWrittenTopLevel: yield* handWrittenTopLevel(cliRoot), diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index d7d3e66d20..1f5e6ed575 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -85,7 +85,7 @@ error). - The failure and timeout hint names the command that re-reads the state. When the polled read is a generated command, the hint names it with the identity the wait polled with, for example `supabase -- --remote=`. When the polled read is a hidden - poll target, the hint names its inspect command from `pollTargets` with only `--remote=`. + read, the hint names the command its `poll.inspect` operation generates, with only `--remote=`. - With `--wait`, stdout carries the final read response instead of the change response. ## Exit Codes diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index b9e12e11c0..84ac2640a1 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -1,6 +1,5 @@ import type { OpenApiOperationId } from "@supabase/api/effect"; import type { ExperimentalFeature } from "../../shared/config/experimental-feature.ts"; -import type { ApiCommandWait } from "./api-command.model.ts"; /** Verbs every generated command may use. */ export const verbVocabulary = [ @@ -26,10 +25,7 @@ export interface ApiNoun { readonly groups?: Readonly>; } -/** How to tell that the resource a read operation returns has settled. */ -export type ApiCommandPoll = Pick; - -/** Only these operations generate commands; `x-operation` on any other operation is ignored, except on a `pollTargets` key. */ +/** Only these operations generate commands, and their response `links` lead to the reads a `--wait` polls. */ export const generatedOperations: ReadonlyArray = [ "v2-get-warehouse-status", "v2-get-warehouse-connection", @@ -38,11 +34,6 @@ export const generatedOperations: ReadonlyArray = [ "v2-get-warehouse-teardown", ]; -/** Hidden polling operations a generated link may target, each with the generated operation whose command inspects its state. */ -export const pollTargets: Readonly>> = { - "v2-get-warehouse-setup": "v2-get-warehouse-status", -}; - export const nouns = { warehouse: { description: "Manage the data warehouse for a project", diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts index 74d9c30327..c0f562caf4 100644 --- a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts @@ -73,7 +73,6 @@ const fixtureSpec = () => { const derived = deriveApiCommands({ spec: fixtureSpec(), generated: Object.keys(FIXTURE_OPERATIONS), - pollTargets: {}, nouns: { fixture: fixtureNoun }, operationIdMap: openApiOperationIdMap, handWrittenTopLevel: new Set(), diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 6f954c365e..ac0e3f4552 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -1294,19 +1294,18 @@ "error": "/data/attributes/status_error" } }, - "$comment": "The deployed specification still gives the setup read the `warehouse status` command identity, which the consolidated status operation now owns." + "$comment": "The setup read is polled by `warehouse enable --wait` and has no command of its own; `inspect` names the consolidated status read." }, { "op": "replace", "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1setups~1current/get/x-operation", "value": { - "group": "warehouse.setups", - "method": "get", "poll": { "status": "/data/attributes/status", "succeeded": ["succeeded"], "failed": ["failed"], - "error": "/data/attributes/status_error" + "error": "/data/attributes/status_error", + "inspect": "v2-get-warehouse-status" } } } diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index 1c1b8a687b..29527d25ac 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -12262,13 +12262,12 @@ "x-fga-permissions": [["database_read"]], "x-oauth-scope": "database:read", "x-operation": { - "group": "warehouse.setups", - "method": "get", "poll": { "status": "/data/attributes/status", "succeeded": ["succeeded"], "failed": ["failed"], - "error": "/data/attributes/status_error" + "error": "/data/attributes/status_error", + "inspect": "v2-get-warehouse-status" } }, "x-scalar-stability": "experimental" From e59a46915440ae7716d7e5e53f8ee97c8803d7f7 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 14:50:03 +0100 Subject: [PATCH 14/45] chore(api): drop Warehouse overrides the deployed spec now ships The deployed Management API spec now includes the Warehouse disable route, the teardown read and its response schema, so the overrides that added them collided and spec regeneration failed. The regenerated files differ only in ordering. --- .../cli/src/commands/api/generated.schemas.ts | 104 +- packages/api/scripts/openapi-overrides.json | 338 ------- packages/api/src/generated/contracts.ts | 100 +- packages/api/src/generated/openapi.json | 944 +++++++++--------- packages/api/src/generated/permissions.ts | 10 +- 5 files changed, 579 insertions(+), 917 deletions(-) diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index ea2a56d29d..2da968df4a 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -5,53 +5,53 @@ export const apiCommandSchemas = { "v2-disable-warehouse": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", + type: "object", properties: { data: { + type: "object", properties: { + type: { + type: "string", + description: "Resource type.", + enum: ["warehouse_teardown"], + }, + id: { + type: "string", + format: "uuid", + pattern: + "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + }, attributes: { + type: "object", properties: { - cleanup_error: { - description: - "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", - type: ["string", "null"], + lifecycle_status: { + type: "string", + enum: ["disabling", "disabled", "deletion_failed"], }, delete_data: { + type: "boolean", description: "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", - type: "boolean", - }, - lifecycle_status: { - enum: ["deletion_failed", "disabled", "disabling"], - type: "string", }, updated_at: { + type: "string", format: "date-time", pattern: "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", - type: "string", + }, + cleanup_error: { + description: + "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + type: ["string", "null"], }, }, - required: ["cleanup_error", "delete_data", "lifecycle_status", "updated_at"], - type: "object", - }, - id: { - format: "uuid", - pattern: - "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", - type: "string", - }, - type: { - description: "Resource type.", - enum: ["warehouse_teardown"], - type: "string", + required: ["lifecycle_status", "delete_data", "updated_at", "cleanup_error"], }, }, - required: ["attributes", "id", "type"], - type: "object", + required: ["type", "id", "attributes"], }, }, required: ["data"], - type: "object", }, }, "v2-enable-warehouse": { @@ -1065,53 +1065,53 @@ export const apiCommandSchemas = { "v2-get-warehouse-teardown": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", + type: "object", properties: { data: { + type: "object", properties: { + type: { + type: "string", + description: "Resource type.", + enum: ["warehouse_teardown"], + }, + id: { + type: "string", + format: "uuid", + pattern: + "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + }, attributes: { + type: "object", properties: { - cleanup_error: { - description: - "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", - type: ["string", "null"], + lifecycle_status: { + type: "string", + enum: ["disabling", "disabled", "deletion_failed"], }, delete_data: { + type: "boolean", description: "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", - type: "boolean", - }, - lifecycle_status: { - enum: ["deletion_failed", "disabled", "disabling"], - type: "string", }, updated_at: { + type: "string", format: "date-time", pattern: "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", - type: "string", + }, + cleanup_error: { + description: + "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + type: ["string", "null"], }, }, - required: ["cleanup_error", "delete_data", "lifecycle_status", "updated_at"], - type: "object", - }, - id: { - format: "uuid", - pattern: - "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", - type: "string", - }, - type: { - description: "Resource type.", - enum: ["warehouse_teardown"], - type: "string", + required: ["lifecycle_status", "delete_data", "updated_at", "cleanup_error"], }, }, - required: ["attributes", "id", "type"], - type: "object", + required: ["type", "id", "attributes"], }, }, required: ["data"], - type: "object", }, }, } as const satisfies Readonly>; diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index ac0e3f4552..af1f8546bb 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -153,344 +153,6 @@ "value": true, "$comment": "The platform returns a null `content` for a snippet that has no stored content." }, - { - "op": "add", - "path": "/paths/~1v2~1projects~1{ref}~1warehouse", - "value": { - "delete": { - "description": "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.\n\nThis endpoint is currently in its **Alpha** stage.", - "operationId": "v2-disable-warehouse", - "parameters": [ - { - "description": "Permanently delete managed Warehouse data. Defaults to false (retain data). Source Postgres tables and legacy shared buckets are preserved.", - "in": "query", - "name": "delete_data", - "required": false, - "schema": { - "default": false, - "type": "boolean" - } - }, - { - "description": "Project ref", - "in": "path", - "name": "ref", - "required": true, - "schema": { - "example": "abcdefghijklmnopqrst", - "maxLength": 20, - "minLength": 20, - "pattern": "^[a-z]+$", - "type": "string" - } - } - ], - "responses": { - "202": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" - } - } - }, - "description": "", - "links": { - "teardown": { - "operationId": "v2-get-warehouse-teardown", - "parameters": { - "operation_id": "$response.body#/data/id", - "ref": "$request.path.ref" - } - } - } - }, - "400": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Invalid deletion option or unmanaged destination" - }, - "401": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Unauthorized" - }, - "402": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "This feature requires the Pro, Team, or Enterprise organization plan." - }, - "403": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Forbidden action" - }, - "409": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Warehouse mutation or cleanup policy conflict" - }, - "429": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Rate limit exceeded" - }, - "503": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Warehouse cleanup unavailable" - } - }, - "security": [ - { - "bearer": [] - } - ], - "summary": "Disable Warehouse replication and access", - "tags": ["Projects Warehouse"], - "x-allowed-plans": ["Enterprise", "Pro", "Team"], - "x-badges": [ - { - "name": "OAuth scope: database:write", - "position": "after" - }, - { - "name": "Only available on Pro, Team, Enterprise", - "position": "before" - }, - { - "name": "Alpha", - "position": "before" - } - ], - "x-endpoint-owners": ["pipelines"], - "x-fga-permissions": [["database_write", "project_admin_write"]], - "x-oauth-scope": "database:write", - "x-operation": { - "group": "warehouse", - "method": "disable" - }, - "x-scalar-stability": "experimental" - } - }, - "$comment": "The public Warehouse disablement and teardown contracts are not yet in the deployed Management API specification." - }, - { - "op": "add", - "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1teardowns~1current", - "value": { - "get": { - "description": "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.\n\nThis endpoint is currently in its **Alpha** stage.", - "operationId": "v2-get-warehouse-teardown", - "parameters": [ - { - "description": "Optional cleanup operation identity returned by disable. Omit to read the current cleanup; when supplied, a different current operation returns a conflict.", - "in": "query", - "name": "operation_id", - "required": false, - "schema": { - "format": "uuid", - "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", - "type": "string" - } - }, - { - "description": "Project ref", - "in": "path", - "name": "ref", - "required": true, - "schema": { - "example": "abcdefghijklmnopqrst", - "maxLength": 20, - "minLength": 20, - "pattern": "^[a-z]+$", - "type": "string" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" - } - } - }, - "description": "" - }, - "401": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Unauthorized" - }, - "403": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Forbidden action" - }, - "409": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Cleanup state is unavailable or the supplied operation identity is no longer current" - }, - "429": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Rate limit exceeded" - }, - "503": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Warehouse cleanup state unavailable" - } - }, - "security": [ - { - "bearer": [] - } - ], - "summary": "Get Warehouse cleanup status", - "tags": ["Projects Warehouse"], - "x-badges": [ - { - "name": "OAuth scope: database:read", - "position": "after" - }, - { - "name": "Alpha", - "position": "before" - } - ], - "x-endpoint-owners": ["pipelines"], - "x-fga-permissions": [["database_read"]], - "x-oauth-scope": "database:read", - "x-operation": { - "group": "warehouse.teardowns", - "method": "get", - "poll": { - "error": "/data/attributes/cleanup_error", - "failed": ["deletion_failed"], - "status": "/data/attributes/lifecycle_status", - "succeeded": ["disabled"] - } - }, - "x-scalar-stability": "experimental" - } - }, - "$comment": "The public Warehouse disablement and teardown contracts are not yet in the deployed Management API specification." - }, - { - "op": "add", - "path": "/components/schemas/V2WarehouseTeardownResponse_Output", - "value": { - "properties": { - "data": { - "properties": { - "attributes": { - "properties": { - "cleanup_error": { - "description": "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", - "nullable": true, - "type": "string" - }, - "delete_data": { - "description": "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", - "type": "boolean" - }, - "lifecycle_status": { - "enum": ["deletion_failed", "disabled", "disabling"], - "type": "string" - }, - "updated_at": { - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", - "type": "string" - } - }, - "required": ["cleanup_error", "delete_data", "lifecycle_status", "updated_at"], - "type": "object" - }, - "id": { - "format": "uuid", - "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", - "type": "string" - }, - "type": { - "description": "Resource type.", - "enum": ["warehouse_teardown"], - "type": "string" - } - }, - "required": ["attributes", "id", "type"], - "type": "object" - } - }, - "required": ["data"], - "type": "object" - }, - "$comment": "The public Warehouse disablement and teardown contracts are not yet in the deployed Management API specification." - }, { "op": "add", "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1status", diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index a4e29e64f0..d010fc3ebf 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -13099,7 +13099,6 @@ export const V2DeployAComputeInstanceOutput = Schema.Struct({ }), }); export const V2DisableWarehouseInput = Schema.Struct({ - delete_data: Schema.optionalKey(Schema.Boolean), ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), ) @@ -13111,27 +13110,11 @@ export const V2DisableWarehouseInput = Schema.Struct({ expected: "a string matching the RegExp ^[a-z]+$", }), ), + delete_data: Schema.optionalKey(Schema.Boolean), }); export const V2DisableWarehouseOutput = Schema.Struct({ data: Schema.Struct({ - attributes: Schema.Struct({ - cleanup_error: Schema.Union([ - Schema.String.annotate({ - description: - "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", - }), - Schema.Null, - ]), - delete_data: Schema.Boolean.annotate({ - description: - "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", - }), - lifecycle_status: Schema.Union([ - Schema.Literals(["deletion_failed", "disabled", "disabling"]), - OpenString, - ]), - updated_at: Schema.String.annotate({ format: "date-time" }), - }), + type: Schema.Literal("warehouse_teardown").annotate({ description: "Resource type." }), id: Schema.String.annotate({ format: "uuid" }).check( Schema.isPattern( new RegExp( @@ -13143,7 +13126,24 @@ export const V2DisableWarehouseOutput = Schema.Struct({ "a string matching the RegExp ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", }), ), - type: Schema.Literal("warehouse_teardown").annotate({ description: "Resource type." }), + attributes: Schema.Struct({ + lifecycle_status: Schema.Union([ + Schema.Literals(["disabling", "disabled", "deletion_failed"]), + OpenString, + ]), + delete_data: Schema.Boolean.annotate({ + description: + "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", + }), + updated_at: Schema.String.annotate({ format: "date-time" }), + cleanup_error: Schema.Union([ + Schema.String.annotate({ + description: + "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + }), + Schema.Null, + ]), + }), }), }); export const V2DownloadProjectBackupInput = Schema.Struct({ @@ -15022,6 +15022,17 @@ export const V2GetWarehouseStatusOutput = Schema.Struct({ }), }); export const V2GetWarehouseTeardownInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), operation_id: Schema.optionalKey( Schema.String.annotate({ format: "uuid" }).check( Schema.isPattern( @@ -15035,38 +15046,10 @@ export const V2GetWarehouseTeardownInput = Schema.Struct({ }), ), ), - ref: Schema.String.check( - Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), - ) - .check( - Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), - ) - .check( - Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ - expected: "a string matching the RegExp ^[a-z]+$", - }), - ), }); export const V2GetWarehouseTeardownOutput = Schema.Struct({ data: Schema.Struct({ - attributes: Schema.Struct({ - cleanup_error: Schema.Union([ - Schema.String.annotate({ - description: - "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", - }), - Schema.Null, - ]), - delete_data: Schema.Boolean.annotate({ - description: - "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", - }), - lifecycle_status: Schema.Union([ - Schema.Literals(["deletion_failed", "disabled", "disabling"]), - OpenString, - ]), - updated_at: Schema.String.annotate({ format: "date-time" }), - }), + type: Schema.Literal("warehouse_teardown").annotate({ description: "Resource type." }), id: Schema.String.annotate({ format: "uuid" }).check( Schema.isPattern( new RegExp( @@ -15078,7 +15061,24 @@ export const V2GetWarehouseTeardownOutput = Schema.Struct({ "a string matching the RegExp ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", }), ), - type: Schema.Literal("warehouse_teardown").annotate({ description: "Resource type." }), + attributes: Schema.Struct({ + lifecycle_status: Schema.Union([ + Schema.Literals(["disabling", "disabled", "deletion_failed"]), + OpenString, + ]), + delete_data: Schema.Boolean.annotate({ + description: + "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", + }), + updated_at: Schema.String.annotate({ format: "date-time" }), + cleanup_error: Schema.Union([ + Schema.String.annotate({ + description: + "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", + }), + Schema.Null, + ]), + }), }), }); export const V2ListAllComputeInstancesInput = Schema.Struct({ diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index 29527d25ac..a3bdb0aece 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -11845,6 +11845,283 @@ "x-oauth-scope": "projects:read" } }, + "/v2/projects/{ref}/warehouse": { + "delete": { + "description": "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-disable-warehouse", + "parameters": [ + { + "name": "ref", + "required": true, + "in": "path", + "description": "Project ref", + "schema": { + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$", + "example": "abcdefghijklmnopqrst", + "type": "string" + } + }, + { + "name": "delete_data", + "required": false, + "in": "query", + "description": "Permanently delete managed Warehouse data. Defaults to false (retain data). Source Postgres tables and legacy shared buckets are preserved.", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "202": { + "links": { + "teardown": { + "operationId": "v2-get-warehouse-teardown", + "parameters": { + "ref": "$request.path.ref", + "operation_id": "$response.body#/data/id" + } + } + }, + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" + } + } + } + }, + "400": { + "description": "Invalid deletion option or unmanaged destination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "402": { + "description": "This feature requires the Pro, Team, or Enterprise organization plan.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "403": { + "description": "Forbidden action", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "409": { + "description": "Warehouse mutation or cleanup policy conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "503": { + "description": "Warehouse cleanup unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Disable Warehouse replication and access", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Pro", "Team", "Enterprise"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["project_admin_write", "database_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse", + "method": "disable" + }, + "x-scalar-stability": "experimental" + } + }, + "/v2/projects/{ref}/warehouse/teardowns/current": { + "get": { + "description": "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-teardown", + "parameters": [ + { + "name": "ref", + "required": true, + "in": "path", + "description": "Project ref", + "schema": { + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$", + "example": "abcdefghijklmnopqrst", + "type": "string" + } + }, + { + "name": "operation_id", + "required": false, + "in": "query", + "description": "Optional cleanup operation identity returned by disable. Omit to read the current cleanup; when supplied, a different current operation returns a conflict.", + "schema": { + "format": "uuid", + "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "403": { + "description": "Forbidden action", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "409": { + "description": "Cleanup state is unavailable or the supplied operation identity is no longer current", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + }, + "503": { + "description": "Warehouse cleanup state unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + } + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get Warehouse cleanup status", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.teardowns", + "method": "get", + "poll": { + "status": "/data/attributes/lifecycle_status", + "succeeded": ["disabled"], + "failed": ["deletion_failed"], + "error": "/data/attributes/cleanup_error" + } + }, + "x-scalar-stability": "experimental" + } + }, "/v2/projects/{ref}/warehouse/enable": { "post": { "description": "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.\n\nThis endpoint is currently in its **Alpha** stage.", @@ -32384,283 +32661,6 @@ "description": "Retry delivering the same event again.\n\nAutomatic retries are not applicable to manual retries - if the delivery fails, there won't be any automatic retries attempted.\n\nThis endpoint is heavy rate-limited to allow for 10 request within 60 seconds." } }, - "/v2/projects/{ref}/warehouse": { - "delete": { - "description": "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.\n\nThis endpoint is currently in its **Alpha** stage.", - "operationId": "v2-disable-warehouse", - "parameters": [ - { - "description": "Permanently delete managed Warehouse data. Defaults to false (retain data). Source Postgres tables and legacy shared buckets are preserved.", - "in": "query", - "name": "delete_data", - "required": false, - "schema": { - "default": false, - "type": "boolean" - } - }, - { - "description": "Project ref", - "in": "path", - "name": "ref", - "required": true, - "schema": { - "example": "abcdefghijklmnopqrst", - "maxLength": 20, - "minLength": 20, - "pattern": "^[a-z]+$", - "type": "string" - } - } - ], - "responses": { - "202": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" - } - } - }, - "description": "", - "links": { - "teardown": { - "operationId": "v2-get-warehouse-teardown", - "parameters": { - "operation_id": "$response.body#/data/id", - "ref": "$request.path.ref" - } - } - } - }, - "400": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Invalid deletion option or unmanaged destination" - }, - "401": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Unauthorized" - }, - "402": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "This feature requires the Pro, Team, or Enterprise organization plan." - }, - "403": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Forbidden action" - }, - "409": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Warehouse mutation or cleanup policy conflict" - }, - "429": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Rate limit exceeded" - }, - "503": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Warehouse cleanup unavailable" - } - }, - "security": [ - { - "bearer": [] - } - ], - "summary": "Disable Warehouse replication and access", - "tags": ["Projects Warehouse"], - "x-allowed-plans": ["Enterprise", "Pro", "Team"], - "x-badges": [ - { - "name": "OAuth scope: database:write", - "position": "after" - }, - { - "name": "Only available on Pro, Team, Enterprise", - "position": "before" - }, - { - "name": "Alpha", - "position": "before" - } - ], - "x-endpoint-owners": ["pipelines"], - "x-fga-permissions": [["database_write", "project_admin_write"]], - "x-oauth-scope": "database:write", - "x-operation": { - "group": "warehouse", - "method": "disable" - }, - "x-scalar-stability": "experimental" - } - }, - "/v2/projects/{ref}/warehouse/teardowns/current": { - "get": { - "description": "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.\n\nThis endpoint is currently in its **Alpha** stage.", - "operationId": "v2-get-warehouse-teardown", - "parameters": [ - { - "description": "Optional cleanup operation identity returned by disable. Omit to read the current cleanup; when supplied, a different current operation returns a conflict.", - "in": "query", - "name": "operation_id", - "required": false, - "schema": { - "format": "uuid", - "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", - "type": "string" - } - }, - { - "description": "Project ref", - "in": "path", - "name": "ref", - "required": true, - "schema": { - "example": "abcdefghijklmnopqrst", - "maxLength": 20, - "minLength": 20, - "pattern": "^[a-z]+$", - "type": "string" - } - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/V2WarehouseTeardownResponse_Output" - } - } - }, - "description": "" - }, - "401": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Unauthorized" - }, - "403": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Forbidden action" - }, - "409": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Cleanup state is unavailable or the supplied operation identity is no longer current" - }, - "429": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Rate limit exceeded" - }, - "503": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponseBody" - } - } - }, - "description": "Warehouse cleanup state unavailable" - } - }, - "security": [ - { - "bearer": [] - } - ], - "summary": "Get Warehouse cleanup status", - "tags": ["Projects Warehouse"], - "x-badges": [ - { - "name": "OAuth scope: database:read", - "position": "after" - }, - { - "name": "Alpha", - "position": "before" - } - ], - "x-endpoint-owners": ["pipelines"], - "x-fga-permissions": [["database_read"]], - "x-oauth-scope": "database:read", - "x-operation": { - "group": "warehouse.teardowns", - "method": "get", - "poll": { - "error": "/data/attributes/cleanup_error", - "failed": ["deletion_failed"], - "status": "/data/attributes/lifecycle_status", - "succeeded": ["disabled"] - } - }, - "x-scalar-stability": "experimental" - } - }, "/v2/projects/{ref}/warehouse/status": { "get": { "description": "Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions.\n\nThis endpoint is currently in its **Alpha** stage.", @@ -42762,66 +42762,7 @@ }, "required": ["projects", "pagination"] }, - "V2WarehouseEnableRequest": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Resource type.", - "enum": ["warehouse_setup"] - }, - "attributes": { - "type": "object", - "properties": { - "warehouse_region": { - "description": "Optional Warehouse compute region, independent of the source and catalog regions. Defaults to the existing assignment, or ap-southeast-1 in staging and eu-west-1 in production for a new assignment. DNS routing requires a registered cluster in that environment. Unsupported regions and changes to an existing assignment are rejected. Ignored when targets is empty.", - "example": "ap-southeast-1", - "type": "string", - "minLength": 1 - }, - "destination_project_ref": { - "description": "Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. Defaults to this project on first setup and to the configured destination on later requests. The destination must be active and healthy, and another project requires SQL and Storage admin write permissions. An existing destination cannot be changed through setup. Ignored when targets is empty.", - "example": "zyxwvutsrqponmlkjihg", - "type": "string", - "minLength": 20, - "maxLength": 20, - "pattern": "^[a-z]+$" - }, - "install_fdw": { - "description": "Whether to configure and install the Warehouse FDW in the project database. Defaults to false. Ignored when targets is empty.", - "example": false, - "type": "boolean" - }, - "schema": { - "type": "string", - "minLength": 1, - "description": "Source PostgreSQL schema. Without tables, selects its currently eligible tables only.", - "example": "public" - }, - "tables": { - "description": "Table names in schema. Omit to select the currently eligible tables in that schema.", - "x-ignore-array-items-must-be-objects": true, - "minItems": 1, - "type": "array", - "items": { - "type": "string", - "minLength": 1 - } - } - }, - "required": ["schema"], - "additionalProperties": false - } - }, - "required": ["type", "attributes"] - } - }, - "required": ["data"] - }, - "V2WarehouseEnableAcceptedResponse_Output": { + "V2WarehouseTeardownResponse_Output": { "type": "object", "properties": { "data": { @@ -42830,109 +42771,36 @@ "type": { "type": "string", "description": "Resource type.", - "enum": ["warehouse_setup"] + "enum": ["warehouse_teardown"] }, "id": { - "type": "string" + "type": "string", + "format": "uuid", + "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attributes": { "type": "object", "properties": { - "tables": { - "type": "array", - "items": { - "type": "object", - "properties": { - "schema": { - "type": "string", - "minLength": 1, - "description": "Postgres schema name", - "example": "public" - }, - "name": { - "type": "string", - "minLength": 1, - "description": "Postgres table name", - "example": "orders" - }, - "state": { - "type": "string", - "enum": ["syncing", "live", "error"], - "description": "Warehouse copy sync state derived from replication status", - "example": "live" - }, - "lag_ms": { - "description": "Replication lag in milliseconds, when available", - "example": 12000, - "type": "integer", - "minimum": 0, - "maximum": 9007199254740991 - }, - "last_synced_at": { - "description": "Last sync timestamp, when available", - "example": "2026-06-23T17:48:00Z", - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" - }, - "copy_name": { - "type": "string", - "description": "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", - "example": "\"abcjuqabhgwjjutfvtpa\".\"public\".\"orders\"" - }, - "warehouse_size_bytes": { - "description": "Warehouse table size in bytes, when available", - "example": 197912092672, - "type": "integer", - "minimum": 0, - "maximum": 9007199254740991 - } - }, - "required": ["schema", "name", "state", "copy_name"] - }, - "description": "Tables with Warehouse copies" - }, - "pipeline_id": { + "lifecycle_status": { "type": "string", - "minLength": 1, - "description": "Warehouse replication pipeline ID, or null when Warehouse disable has been requested", - "example": "03dg2o5teb2eucxr9ggh3uie6", - "nullable": true + "enum": ["disabling", "disabled", "deletion_failed"] }, - "accepted": { + "delete_data": { "type": "boolean", - "enum": [true] + "description": "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes." }, - "selected_tables": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "exclusiveMinimum": true, - "maximum": 4294967295, - "minimum": 0 - }, - "schema": { - "type": "string", - "minLength": 1 - }, - "name": { - "type": "string", - "minLength": 1 - } - }, - "required": ["id", "schema", "name"] - } + "updated_at": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, - "selection_id": { + "cleanup_error": { + "description": "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", "type": "string", - "pattern": "^[a-f0-9]{64}$", - "description": "Identity of the accepted selection. Pass to the current setup read to reject a changed selection while waiting." + "nullable": true } }, - "required": ["tables", "pipeline_id", "accepted", "selected_tables", "selection_id"] + "required": ["lifecycle_status", "delete_data", "updated_at", "cleanup_error"] } }, "required": ["type", "id", "attributes"] @@ -43104,6 +42972,184 @@ }, "required": ["error"] }, + "V2WarehouseEnableRequest": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Resource type.", + "enum": ["warehouse_setup"] + }, + "attributes": { + "type": "object", + "properties": { + "warehouse_region": { + "description": "Optional Warehouse compute region, independent of the source and catalog regions. Defaults to the existing assignment, or ap-southeast-1 in staging and eu-west-1 in production for a new assignment. DNS routing requires a registered cluster in that environment. Unsupported regions and changes to an existing assignment are rejected. Ignored when targets is empty.", + "example": "ap-southeast-1", + "type": "string", + "minLength": 1 + }, + "destination_project_ref": { + "description": "Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. Defaults to this project on first setup and to the configured destination on later requests. The destination must be active and healthy, and another project requires SQL and Storage admin write permissions. An existing destination cannot be changed through setup. Ignored when targets is empty.", + "example": "zyxwvutsrqponmlkjihg", + "type": "string", + "minLength": 20, + "maxLength": 20, + "pattern": "^[a-z]+$" + }, + "install_fdw": { + "description": "Whether to configure and install the Warehouse FDW in the project database. Defaults to false. Ignored when targets is empty.", + "example": false, + "type": "boolean" + }, + "schema": { + "type": "string", + "minLength": 1, + "description": "Source PostgreSQL schema. Without tables, selects its currently eligible tables only.", + "example": "public" + }, + "tables": { + "description": "Table names in schema. Omit to select the currently eligible tables in that schema.", + "x-ignore-array-items-must-be-objects": true, + "minItems": 1, + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + } + }, + "required": ["schema"], + "additionalProperties": false + } + }, + "required": ["type", "attributes"] + } + }, + "required": ["data"] + }, + "V2WarehouseEnableAcceptedResponse_Output": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Resource type.", + "enum": ["warehouse_setup"] + }, + "id": { + "type": "string" + }, + "attributes": { + "type": "object", + "properties": { + "tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "schema": { + "type": "string", + "minLength": 1, + "description": "Postgres schema name", + "example": "public" + }, + "name": { + "type": "string", + "minLength": 1, + "description": "Postgres table name", + "example": "orders" + }, + "state": { + "type": "string", + "enum": ["syncing", "live", "error"], + "description": "Warehouse copy sync state derived from replication status", + "example": "live" + }, + "lag_ms": { + "description": "Replication lag in milliseconds, when available", + "example": 12000, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "last_synced_at": { + "description": "Last sync timestamp, when available", + "example": "2026-06-23T17:48:00Z", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "copy_name": { + "type": "string", + "description": "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", + "example": "\"abcjuqabhgwjjutfvtpa\".\"public\".\"orders\"" + }, + "warehouse_size_bytes": { + "description": "Warehouse table size in bytes, when available", + "example": 197912092672, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "required": ["schema", "name", "state", "copy_name"] + }, + "description": "Tables with Warehouse copies" + }, + "pipeline_id": { + "type": "string", + "minLength": 1, + "description": "Warehouse replication pipeline ID, or null when Warehouse disable has been requested", + "example": "03dg2o5teb2eucxr9ggh3uie6", + "nullable": true + }, + "accepted": { + "type": "boolean", + "enum": [true] + }, + "selected_tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0 + }, + "schema": { + "type": "string", + "minLength": 1 + }, + "name": { + "type": "string", + "minLength": 1 + } + }, + "required": ["id", "schema", "name"] + } + }, + "selection_id": { + "type": "string", + "pattern": "^[a-f0-9]{64}$", + "description": "Identity of the accepted selection. Pass to the current setup read to reject a changed selection while waiting." + } + }, + "required": ["tables", "pipeline_id", "accepted", "selected_tables", "selection_id"] + } + }, + "required": ["type", "id", "attributes"] + } + }, + "required": ["data"] + }, "V2WarehouseSetupRequest": { "type": "object", "properties": { @@ -48160,52 +48206,6 @@ }, "required": ["data"] }, - "V2WarehouseTeardownResponse_Output": { - "properties": { - "data": { - "properties": { - "attributes": { - "properties": { - "cleanup_error": { - "description": "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", - "nullable": true, - "type": "string" - }, - "delete_data": { - "description": "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", - "type": "boolean" - }, - "lifecycle_status": { - "enum": ["deletion_failed", "disabled", "disabling"], - "type": "string" - }, - "updated_at": { - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", - "type": "string" - } - }, - "required": ["cleanup_error", "delete_data", "lifecycle_status", "updated_at"], - "type": "object" - }, - "id": { - "format": "uuid", - "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", - "type": "string" - }, - "type": { - "description": "Resource type.", - "enum": ["warehouse_teardown"], - "type": "string" - } - }, - "required": ["attributes", "id", "type"], - "type": "object" - } - }, - "required": ["data"], - "type": "object" - }, "V2WarehouseContextResponse_Output": { "properties": { "data": { diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index 18dd282fe0..413ac5c910 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -332,6 +332,11 @@ export const operationPermissions: Readonly fga: [["organization_projects_read"]], oauthScope: "projects:read", }, + "v2-disable-warehouse": { + fga: [["project_admin_write", "database_write"]], + oauthScope: "database:write", + }, + "v2-get-warehouse-teardown": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-enable-warehouse": { fga: [["project_admin_write", "database_write"]], oauthScope: "database:write", @@ -443,11 +448,6 @@ export const operationPermissions: Readonly "v2-organizations-slug-webhooks-endpoints-id-test-post": { fga: [] }, "v2-organizations-slug-webhooks-deliveries-id-get": { fga: [] }, "v2-organizations-slug-webhooks-deliveries-id-retry-post": { fga: [] }, - "v2-disable-warehouse": { - fga: [["database_write", "project_admin_write"]], - oauthScope: "database:write", - }, - "v2-get-warehouse-teardown": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-get-warehouse-status": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-get-warehouse-connection": { fga: [["database_read"]], oauthScope: "database:read" }, }; From 96738e48814282d8aa99e86a7f23739ba8a877a3 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 15:15:34 +0100 Subject: [PATCH 15/45] chore(cli): label poll-only reads in the generated command reference --- apps/cli/scripts/api-command-reference.ts | 2 +- apps/cli/src/commands/api/api-command-execute.ts | 2 +- apps/cli/src/commands/api/generated.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts index afecca4434..58e6beee2b 100644 --- a/apps/cli/scripts/api-command-reference.ts +++ b/apps/cli/scripts/api-command-reference.ts @@ -102,7 +102,7 @@ const waitSection = ( return [ "### Wait", "", - `- Polls: ${polledRoute} (${code(wait.read)}${publicRead === undefined ? ", hidden poll target" : publicRead.operationId === entry.operationId ? ", the command's own read" : ""}).`, + `- Polls: ${polledRoute} (${code(wait.read)}${publicRead === undefined ? ", poll-only read" : publicRead.operationId === entry.operationId ? ", the command's own read" : ""}).`, ...(params.length === 0 ? [] : [ diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index 4baa490e3c..f724f0111f 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -198,7 +198,7 @@ interface WaitInput { readonly wait: ApiCommandWait; /** The operation the wait polls; its decoded input is `readInput`. */ readonly readEntry: ApiPollRead; - /** The command to name in a failure hint: the read's own, or the one that inspects a hidden read. */ + /** The command to name in a failure hint: the read's own, or the one that inspects a poll-only read. */ readonly statusEntry: ApiCommandEntry; /** The flat input of the read operation, as assembled from flags or the change response. */ readonly readInput: Readonly>; diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index c125f91a7f..d01f5b9494 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -61,7 +61,7 @@ Enables replication for the currently eligible tables in a schema, or the named ### Wait -- Polls: `GET /v2/projects/{ref}/warehouse/setups/current` (`v2-get-warehouse-setup`, hidden poll target). +- Polls: `GET /v2/projects/{ref}/warehouse/setups/current` (`v2-get-warehouse-setup`, poll-only read). - Read parameters from the change response: `selection_id` from `/data/attributes/selection_id`. - Status at `/data/attributes/status`; succeeded: `succeeded`; failed: `failed`. - Failure message from `/data/attributes/status_error`. From e79eb5880b7ae88231bcdf551bc9dfd608ba4a92 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 15:15:36 +0100 Subject: [PATCH 16/45] chore(cli): gate generated commands on the allowlist alone Only the generated operations list decides whether an operation becomes a command, and a generated name still goes through every collision check. A polled read the CLI does not generate may keep its own name next to poll and inspect, so the spec can name every operation for other consumers. The setup read's override now names it warehouse.setups get. --- apps/cli/scripts/api-command-derive.ts | 68 ++++++++---------- .../scripts/api-command-derive.unit.test.ts | 70 +++++++++---------- packages/api/scripts/openapi-overrides.json | 4 +- packages/api/src/generated/openapi.json | 2 + 4 files changed, 67 insertions(+), 77 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 311dbefd46..35c225271d 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -76,15 +76,17 @@ const decodeXOperation = Schema.decodeUnknownExit(XOperationSchema, { onExcessProperty: "error", }); -/** A named command, or a poll-only read that never becomes a command. */ +/** + * An `x-operation` block: an optional command name and an optional poll mapping. A name generates + * a command only for operations in the generated list. + */ type ParsedXOperation = | { - readonly kind: "named"; - readonly group: string; - readonly method: string; + readonly kind: "valid"; + readonly name?: { readonly group: string; readonly method: string }; readonly poll?: ApiCommandPoll; + readonly inspect?: string; } - | { readonly kind: "pollOnly"; readonly poll: ApiCommandPoll; readonly inspect: string } | { readonly kind: "invalid"; readonly reason: string }; const statusMapping = (poll: ApiCommandPoll): ApiCommandPoll => ({ @@ -98,32 +100,20 @@ const parseXOperation = (block: unknown): ParsedXOperation => { const decoded = decodeXOperation(block); if (Exit.isFailure(decoded)) return { kind: "invalid", reason: Cause.pretty(decoded.cause) }; const { group, method, poll } = decoded.value; - if (group === undefined && method === undefined) { - if (poll === undefined) { - return { kind: "invalid", reason: "set group and method, or a poll-only read's poll" }; - } - if (poll.inspect === undefined || poll.inspect === "") { - return { - kind: "invalid", - reason: "a poll-only read must set poll.inspect to the operation that inspects its state", - }; - } - return { kind: "pollOnly", poll: statusMapping(poll), inspect: poll.inspect }; - } - if (group === undefined || method === undefined) { + if ((group === undefined) !== (method === undefined)) { return { kind: "invalid", reason: "a command name needs both group and method" }; } - if (poll?.inspect !== undefined) { - return { - kind: "invalid", - reason: "poll.inspect belongs on a poll-only read, not on a named operation", - }; + if (group === undefined && poll === undefined) { + return { kind: "invalid", reason: "set group and method, poll, or both" }; + } + if (poll?.inspect === "") { + return { kind: "invalid", reason: "poll.inspect must name an operation" }; } return { - kind: "named", - group, - method, + kind: "valid", + ...(group === undefined || method === undefined ? {} : { name: { group, method } }), ...(poll === undefined ? {} : { poll: statusMapping(poll) }), + ...(poll?.inspect === undefined ? {} : { inspect: poll.inspect }), }; }; @@ -571,14 +561,12 @@ const readMetadata = ( problems.push(`${operationId}: invalid x-operation: ${parsed.reason}`); continue; } - if (parsed.kind === "pollOnly") { - problems.push( - `${operationId}: a poll-only read cannot be generated; give it group and method or remove it from the generated operations`, - ); + const { name, poll } = parsed; + if (name === undefined) { + problems.push(`${operationId}: no command name; set x-operation group and method`); continue; } - const { group, method, poll } = parsed; - metadata.set(operationId, { group, method, ...(poll === undefined ? {} : { poll }) }); + metadata.set(operationId, { ...name, ...(poll === undefined ? {} : { poll }) }); if (poll !== undefined && operation.method !== "GET") { problems.push(`${operationId}: poll belongs on a read operation, not ${operation.method}`); } @@ -637,7 +625,7 @@ const pollWait = ( const RESPONSE_POINTER = /^\$response\.body#(\/.*)$/u; const REQUEST_PATH = /^\$request\.path\.(.+)$/u; -/** A poll-only read reached through a response link, with the operation that inspects its state. */ +/** A polled read that is not a generated command, reached through a response link, with the operation that inspects its state. */ interface HiddenRead { readonly poll: ApiCommandPoll; readonly inspect: string; @@ -645,8 +633,8 @@ interface HiddenRead { /** * The wait a command's 2xx response `links` declare: the one link whose target operation has - * `poll`. The target is a generated operation or a poll-only read, which is recorded in `hidden`; - * links without `poll` are ignored. + * `poll`. A target that is not a generated operation needs `poll.inspect` and is recorded in + * `hidden`; links without `poll` are ignored. */ const linkedWait = ( spec: JsonObject, @@ -685,13 +673,13 @@ const linkedWait = ( fail( `link "${linkName}" targets "${targetId}", whose x-operation is invalid: ${parsed.reason}`, ); - } else if (parsed.kind === "pollOnly") { - poll = parsed.poll; - hidden.set(targetId, { poll, inspect: parsed.inspect }); - } else if (parsed.poll !== undefined) { + } else if (parsed.poll !== undefined && parsed.inspect === undefined) { fail( - `link "${linkName}" targets polled operation "${targetId}", which is neither a generated command nor a poll-only read`, + `link "${linkName}" targets polled operation "${targetId}", which is not a generated command and sets no poll.inspect`, ); + } else if (parsed.poll !== undefined && parsed.inspect !== undefined) { + poll = parsed.poll; + hidden.set(targetId, { poll, inspect: parsed.inspect }); } } if (poll === undefined) continue; diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 4df7577b0e..fc390fb6e3 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -641,12 +641,15 @@ describe("deriveApiCommands", () => { expect(waitOf(result)).toBeUndefined(); }); - it("keeps a poll-only read internal and records the command that inspects it", () => { + it.each([ + ["without a command name", hiddenThing], + ["with a command name", readWith({ ...poll, inspect: "get-inspect" })], + ])("keeps a polled read %s internal when it is not generated", (_label, read) => { const result = deriveHidden({ "create-thing": changeThing( link({ ref: "$request.path.ref", thing_id: "$response.body#/data/id" }), ), - "get-thing": hiddenThing, + "get-thing": read, }); expect(result.problems).toEqual([]); @@ -705,27 +708,21 @@ describe("deriveApiCommands", () => { expect(result.schemas["get-thing"]).toBeUndefined(); }); - it("rejects a link to a named polled operation that is not generated", () => { - const result = derive({ "create-thing": changeThing(link({})), "get-thing": readThing }, [ - "create-thing", - ]); - - expect(result.problems).toEqual([ - 'create-thing: link "setup" targets polled operation "get-thing", which is neither a generated command nor a poll-only read', - ]); - expect(result.pollTargets).toEqual([]); - }); - - it("rejects a poll-only read without an inspect operation", () => { - const result = deriveHidden({ - "create-thing": changeThing(link({})), - "get-thing": readOf({ poll }), - }); - - expect(result.problems).toEqual([ - 'create-thing: link "setup" targets "get-thing", whose x-operation is invalid: a poll-only read must set poll.inspect to the operation that inspects its state', - ]); - }); + it.each([ + ["without a command name", readOf({ poll })], + ["with a command name", readThing], + ])( + "rejects a linked polled read %s that is not generated and sets no inspect", + (_label, read) => { + const result = deriveHidden({ "create-thing": changeThing(link({})), "get-thing": read }); + + expect(result.problems).toEqual([ + 'create-thing: link "setup" targets polled operation "get-thing", which is not a generated command and sets no poll.inspect', + ]); + expect(waitOf(result)).toBeUndefined(); + expect(result.pollTargets).toEqual([]); + }, + ); it.each([ ["a misspelled poll key", { pool: { ...poll, inspect: "get-inspect" } }, "pool"], @@ -744,18 +741,19 @@ describe("deriveApiCommands", () => { expect(waitOf(result)).toBeUndefined(); }); - it("rejects inspect on a named operation", () => { - const result = derive({ - "get-thing": readOf({ - group: "thing", - method: "get", - poll: { ...poll, inspect: "get-inspect" }, - }), - }); + it("polls a generated read as its own command even when it sets inspect", () => { + const result = derive( + { + "create-thing": changeThing(link({ thing_id: "$response.body#/data/id" })), + "get-thing": readWith({ ...poll, inspect: "get-inspect" }), + "get-inspect": inspectThing, + }, + ["create-thing", "get-thing", "get-inspect"], + ); - expect(result.problems).toEqual([ - "get-thing: invalid x-operation: poll.inspect belongs on a poll-only read, not on a named operation", - ]); + expect(result.problems).toEqual([]); + expect(waitOf(result)?.read).toBe("get-thing"); + expect(result.pollTargets).toEqual([]); }); it.each([ @@ -769,7 +767,7 @@ describe("deriveApiCommands", () => { ]); }); - it("rejects a poll-only read listed as a generated operation", () => { + it("rejects a generated operation whose x-operation has no command name", () => { const result = derive( { "create-thing": changeThing(link({})), @@ -780,7 +778,7 @@ describe("deriveApiCommands", () => { ); expect(result.problems).toEqual([ - "get-thing: a poll-only read cannot be generated; give it group and method or remove it from the generated operations", + "get-thing: no command name; set x-operation group and method", ]); }); diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index af1f8546bb..8626bc69ab 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -956,12 +956,14 @@ "error": "/data/attributes/status_error" } }, - "$comment": "The setup read is polled by `warehouse enable --wait` and has no command of its own; `inspect` names the consolidated status read." + "$comment": "The setup read is polled by `warehouse enable --wait`; its name must not claim the status read's `warehouse status`, and `inspect` names that consolidated status read." }, { "op": "replace", "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1setups~1current/get/x-operation", "value": { + "group": "warehouse.setups", + "method": "get", "poll": { "status": "/data/attributes/status", "succeeded": ["succeeded"], diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index a3bdb0aece..e9dd2b2d2a 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -12539,6 +12539,8 @@ "x-fga-permissions": [["database_read"]], "x-oauth-scope": "database:read", "x-operation": { + "group": "warehouse.setups", + "method": "get", "poll": { "status": "/data/attributes/status", "succeeded": ["succeeded"], From b87bfdd82c9b3c20bf5957448f482aefca5009c6 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 15:49:55 +0100 Subject: [PATCH 17/45] chore(cli): let generated commands join hand-written groups --- apps/cli/scripts/api-command-derive.ts | 63 +++++- .../scripts/api-command-derive.unit.test.ts | 113 +++++++++- apps/cli/scripts/generate-api-commands.ts | 55 +++-- apps/cli/src/cli/root.ts | 98 +++++---- apps/cli/src/commands/api/SIDE_EFFECTS.md | 9 + .../api-command-bindings.integration.test.ts | 4 +- .../api/api-command-join.integration.test.ts | 207 ++++++++++++++++++ .../src/commands/api/api-command-policy.ts | 14 +- .../api-command-shapes.integration.test.ts | 11 +- .../api/api-commands.integration.test.ts | 15 +- apps/cli/src/commands/api/runtime.ts | 131 +++++++---- 11 files changed, 586 insertions(+), 134 deletions(-) create mode 100644 apps/cli/src/commands/api/api-command-join.integration.test.ts diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 35c225271d..df40307273 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -117,6 +117,16 @@ const parseXOperation = (block: unknown): ParsedXOperation => { }; }; +/** The hand-written command tree, as space-joined command paths. */ +export interface HandWrittenCommands { + /** Paths of the commands that have subcommands. */ + readonly groups: ReadonlySet; + /** Paths of the commands that have none. */ + readonly leaves: ReadonlySet; + /** Groups a generated command cannot join. */ + readonly sealed: ReadonlySet; +} + interface DeriveInput { /** The parsed OpenAPI document. */ readonly spec: JsonObject; @@ -125,8 +135,8 @@ interface DeriveInput { readonly nouns: Readonly>; /** Kebab-case operation id to the camelCase key of the typed client's `operationDefinitions`. */ readonly operationIdMap: Readonly>; - /** Top-level command names owned by hand-written commands. */ - readonly handWrittenTopLevel: ReadonlySet; + /** Generated commands join hand-written groups; only an actual path collision fails. */ + readonly handWritten: HandWrittenCommands; } interface DeriveResult { @@ -724,7 +734,7 @@ const linkedWait = ( /** Derives the generated commands from each operation's `x-operation` and collects every lint failure. */ export function deriveApiCommands(input: DeriveInput): DeriveResult { - const { spec, generated, nouns, operationIdMap, handWrittenTopLevel } = input; + const { spec, generated, nouns, operationIdMap, handWritten } = input; const operations = collectOperations(spec); const problems: Array = []; const metadata = readMetadata(operations, generated, problems); @@ -733,6 +743,23 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const schemas: Record = {}; const commandOwners = new Map(); const groupPaths = new Set(); + const describedNouns = new Set(); + + for (const [noun, definition] of Object.entries(nouns)) { + if (handWritten.groups.has(noun) && definition.description !== undefined) { + problems.push( + `noun "${noun}" describes the hand-written group "${noun}"; drop its description`, + ); + } + for (const subGroup of Object.keys(definition.groups ?? {})) { + const groupKey = [noun, ...subGroup.split(".")].join(" "); + if (handWritten.groups.has(groupKey)) { + problems.push( + `noun "${noun}" describes the hand-written group "${groupKey}"; drop its description`, + ); + } + } + } for (const [operationId, name] of metadata) { const { group, method } = name; @@ -766,18 +793,38 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { if (owner !== undefined) fail(`command "${commandKey}" is already generated by ${owner}`); commandOwners.set(commandKey, operationId); if (groupPaths.has(commandKey)) fail(`command "${commandKey}" is both a command and a group`); - for (let depth = 2; depth < command.length; depth += 1) { + if (handWritten.leaves.has(commandKey)) { + fail(`command "${commandKey}" is already a hand-written command`); + } + if (handWritten.groups.has(commandKey)) { + fail(`command "${commandKey}" is already a hand-written group`); + } + if (!describedNouns.has(command[0] ?? "")) { + describedNouns.add(command[0] ?? ""); + if (noun.description === undefined && !handWritten.groups.has(command[0] ?? "")) { + fail(`noun "${command[0]}" has no description in the nouns table`); + } + } + for (let depth = 1; depth < command.length; depth += 1) { const groupKey = command.slice(0, depth).join(" "); + if (handWritten.leaves.has(groupKey)) { + fail( + `command "${commandKey}" needs "${groupKey}" as a group, but it is a hand-written command`, + ); + } + if (handWritten.sealed.has(groupKey)) { + fail( + `command "${commandKey}" cannot join the hand-written group "${groupKey}", which wraps its own subcommands`, + ); + } + if (depth < 2) continue; if (commandOwners.has(groupKey)) fail(`command "${groupKey}" is both a command and a group`); groupPaths.add(groupKey); const subGroup = command.slice(1, depth).join("."); - if (noun.groups?.[subGroup] === undefined) { + if (noun.groups?.[subGroup] === undefined && !handWritten.groups.has(groupKey)) { fail(`group "${subGroup}" has no description in the nouns table`); } } - if (handWrittenTopLevel.has(command[0] ?? "")) { - fail(`command "${commandKey}" collides with the hand-written "${command[0]}" command`); - } requireExperimental(operation, fail); const summary = asString(operation.node.summary); diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index fc390fb6e3..b9c045c9f4 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -56,6 +56,18 @@ const pathOf = (id: string, node: unknown): string => { return `/v1/projects/{ref}/${id}${extra.join("")}`; }; +const handWritten = ( + tree: { + groups?: ReadonlyArray; + leaves?: ReadonlyArray; + sealed?: ReadonlyArray; + } = {}, +) => ({ + groups: new Set(tree.groups ?? ["db"]), + leaves: new Set(tree.leaves), + sealed: new Set(tree.sealed), +}); + const derive = ( operations: Record, generated: ReadonlyArray = Object.keys(operations), @@ -81,7 +93,7 @@ const derive = ( operationIdMap: Object.fromEntries( Object.keys(operations).map((id) => [id, "v2EnableWarehouse" as const]), ), - handWrittenTopLevel: new Set(["db"]), + handWritten: handWritten(), ...options.overrides, }); @@ -1513,15 +1525,102 @@ describe("deriveApiCommands", () => { "create-thing: operation is missing from the typed client; regenerate @supabase/api", ]); }); + }); - it("rejects a command whose first word belongs to a hand-written command", () => { - const result = derive({ "create-thing": operation(create) }, undefined, { - overrides: { handWrittenTopLevel: new Set(["thing"]) }, + describe("hand-written commands", () => { + const shallow = { "create-thing": operation(create) }; + const deep = { + "create-thing": operation({ "x-operation": { group: "thing.sub", method: "create" } }), + }; + + it("joins a hand-written group without describing it", () => { + const result = derive(shallow, undefined, { + overrides: { + handWritten: handWritten({ groups: ["thing"], leaves: ["thing list"] }), + nouns: { thing: { feature: "warehouse" } }, + }, }); - expect(result.problems).toEqual([ - 'create-thing: command "thing create" collides with the hand-written "thing" command', - ]); + expect(result.problems).toEqual([]); + expect(result.entries.map((entry) => entry.command)).toEqual([["thing", "create"]]); + }); + + it("joins a hand-written sub-group without describing it", () => { + const result = derive(deep, undefined, { + overrides: { + handWritten: handWritten({ groups: ["thing", "thing sub"] }), + nouns: { thing: { feature: "warehouse" } }, + }, + }); + + expect(result.problems).toEqual([]); + expect(result.entries.map((entry) => entry.command)).toEqual([["thing", "sub", "create"]]); + }); + + it.each([ + [ + "a hand-written command of the same path", + shallow, + { leaves: ["thing create"] }, + 'create-thing: command "thing create" is already a hand-written command', + ], + [ + "a hand-written group of the same path", + shallow, + { groups: ["thing create"] }, + 'create-thing: command "thing create" is already a hand-written group', + ], + [ + "a group path that is a hand-written command", + deep, + { leaves: ["thing sub"] }, + 'create-thing: command "thing sub create" needs "thing sub" as a group, but it is a hand-written command', + ], + [ + "a group path that is a sealed hand-written group", + deep, + { groups: ["thing", "thing sub"], sealed: ["thing sub"] }, + 'create-thing: command "thing sub create" cannot join the hand-written group "thing sub", which wraps its own subcommands', + ], + ])("rejects %s", (_label, operations, tree, problem) => { + const result = derive(operations, undefined, { + overrides: { handWritten: handWritten(tree) }, + }); + + expect(result.problems).toContain(problem); + }); + + it.each([ + [ + "a noun without a description when no hand-written group exists", + { groups: [] }, + { feature: "warehouse" as const }, + 'create-thing: noun "thing" has no description in the nouns table', + ], + [ + "a sub-group without a description when no hand-written group exists", + { groups: ["thing"] }, + { feature: "warehouse" as const }, + 'create-thing: group "sub" has no description in the nouns table', + ], + [ + "a description on a hand-written noun group", + { groups: ["thing"] }, + thingNoun, + 'noun "thing" describes the hand-written group "thing"; drop its description', + ], + [ + "a description on a hand-written sub-group", + { groups: ["thing", "thing sub"] }, + { feature: "warehouse" as const, groups: { sub: "Manage sub things" } }, + 'noun "thing" describes the hand-written group "thing sub"; drop its description', + ], + ])("requires descriptions only for generated groups: %s", (_label, tree, noun, problem) => { + const result = derive(deep, undefined, { + overrides: { handWritten: handWritten(tree), nouns: { thing: noun } }, + }); + + expect(result.problems).toContain(problem); }); }); diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index 1b95cdf472..4edc50c646 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -1,13 +1,20 @@ import { BunRuntime, BunServices } from "@effect/platform-bun"; import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; +import type { Command } from "effect/cli"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; -import { generatedOperations, nouns } from "../src/commands/api/api-command-policy.ts"; +import { rootCommandForFeatures } from "../src/cli/root.ts"; +import { + generatedOperations, + nouns, + sealedGroups, +} from "../src/commands/api/api-command-policy.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { renderApiCommandReference } from "./api-command-reference.ts"; import { ApiCommandGenerationError, collectOperations, deriveApiCommands, + type HandWrittenCommands, } from "./api-command-derive.ts"; class ApiCommandFormatError extends Data.TaggedError("ApiCommandFormatError")<{ @@ -25,25 +32,37 @@ class ApiCommandDriftError extends Data.TaggedError("ApiCommandDriftError")<{ const HEADER = "// Generated by scripts/generate-api-commands.ts. Do not edit.\n"; const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown, { space: 2 })); const decodeJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown)); -const COMMAND_NAME = /Command\.make\(\s*"([^"]+)"/u; +const ROOT_OPTIONS: ReadonlyArray[0]> = [ + { stackBackend: "legacy", computeEnabled: false }, + { stackBackend: "legacy", computeEnabled: true }, + { stackBackend: "stack", computeEnabled: false }, + { stackBackend: "stack", computeEnabled: true }, +]; -/** Top-level names of the hand-written commands, read from their `.command.ts` files. */ -const handWrittenTopLevel = Effect.fn("ApiCommands.scanHandWritten")(function* (cliRoot: string) { - const fs = yield* FileSystem.FileSystem; - const path = yield* Path.Path; - const names = new Set(); - for (const base of ["src/commands", "src/commands/experimental"]) { - const root = path.join(cliRoot, base); - for (const entry of yield* fs.readDirectory(root)) { - if (entry === "api") continue; - const file = path.join(root, entry, `${entry}.command.ts`); - if (!(yield* fs.exists(file))) continue; - const match = COMMAND_NAME.exec(yield* fs.readFileString(file)); - if (match?.[1] !== undefined) names.add(match[1]); +const walkHandWritten = ( + command: Command.Command.Any, + prefix: ReadonlyArray, + into: { readonly groups: Set; readonly leaves: Set }, +): void => { + for (const { commands } of command.subcommands) { + for (const child of commands) { + const path = [...prefix, child.name]; + const isGroup = child.subcommands.length > 0; + (isGroup ? into.groups : into.leaves).add(path.join(" ")); + if (isGroup) walkHandWritten(child, path, into); } } - yield* Effect.annotateCurrentSpan("handWritten.count", names.size); - return names; +}; + +/** The hand-written command tree: the union of the trees every backend and feature option builds. */ +const handWrittenCommands = Effect.fn("ApiCommands.walkHandWritten")(function* () { + const found = { groups: new Set(), leaves: new Set() }; + for (const options of ROOT_OPTIONS) walkHandWritten(rootCommandForFeatures(options), [], found); + yield* Effect.annotateCurrentSpan({ + "handWritten.groups": found.groups.size, + "handWritten.leaves": found.leaves.size, + }); + return { ...found, sealed: sealedGroups } satisfies HandWrittenCommands; }); /** Formats in memory with the repo's oxfmt config so the committed files match `pnpm fmt`. */ @@ -95,7 +114,7 @@ const main = Effect.gen(function* () { generated: generatedOperations, nouns, operationIdMap: openApiOperationIdMap, - handWrittenTopLevel: yield* handWrittenTopLevel(cliRoot), + handWritten: yield* handWrittenCommands(), }); if (problems.length > 0) return yield* new ApiCommandGenerationError({ problems }); diff --git a/apps/cli/src/cli/root.ts b/apps/cli/src/cli/root.ts index d8f3132c1f..a8a9c27c31 100644 --- a/apps/cli/src/cli/root.ts +++ b/apps/cli/src/cli/root.ts @@ -26,7 +26,7 @@ import { type ProjectStateMode, projectStateModeLayer, } from "../shared/config/project-state-mode.ts"; -import { apiCommandGroups } from "../commands/api/runtime.ts"; +import { withApiCommands } from "../commands/api/runtime.ts"; import { computeCommand } from "../commands/experimental/compute/compute.command.ts"; import { feedbackCommand } from "../commands/feedback/feedback.command.ts"; import { functionsCommand } from "../commands/functions/functions.command.ts"; @@ -166,52 +166,56 @@ const agentDefaultOutputFormatFor = ( export const rootCommandForFeatures = (options: RootCommandFeatures = {}) => Command.make("supabase").pipe( Command.withDescription(rootDescription(CLI_VERSION)), - Command.withSubcommands([ - backupsCommand, - bootstrapCommand, - branchesCommand, - completionCommand, - ...(options.computeEnabled ? [computeCommand] : []), - configCommand, - dbCommand, - domainsCommand, - encryptionCommand, - feedbackCommand, - functionsCommand, - genCommand, - initCommand, - inspectCommand, - issueCommand, - linkCommand, - loginCommand, - logoutCommand, - logsCommandFor(), - migrationCommand, - networkBansCommand, - networkRestrictionsCommand, - notebooksCommand, - orgsCommand, - postgresConfigCommand, - projectsCommand, - pullCommand, - secretsCommand, - seedCommand, - servicesCommand, - snippetsCommand, - sslEnforcementCommand, - ssoCommand, - ...(options.stackBackend === "stack" ? [stackCommand] : []), - options.stackBackend === "stack" ? stackStartAliasCommand : startCommand, - options.stackBackend === "stack" ? stackStatusAliasCommand : statusCommand, - options.stackBackend === "stack" ? stackStopAliasCommand : stopCommand, - storageCommand, - telemetryCommand, - testCommand, - unlinkCommand, - vanitySubdomainsCommand, - ...apiCommandGroups(options.apiFeatures ?? []), - whoamiCommand, - ]), + Command.withSubcommands( + withApiCommands( + [ + backupsCommand, + bootstrapCommand, + branchesCommand, + completionCommand, + ...(options.computeEnabled ? [computeCommand] : []), + configCommand, + dbCommand, + domainsCommand, + encryptionCommand, + feedbackCommand, + functionsCommand, + genCommand, + initCommand, + inspectCommand, + issueCommand, + linkCommand, + loginCommand, + logoutCommand, + logsCommandFor(), + migrationCommand, + networkBansCommand, + networkRestrictionsCommand, + notebooksCommand, + orgsCommand, + postgresConfigCommand, + projectsCommand, + pullCommand, + secretsCommand, + seedCommand, + servicesCommand, + snippetsCommand, + sslEnforcementCommand, + ssoCommand, + ...(options.stackBackend === "stack" ? [stackCommand] : []), + options.stackBackend === "stack" ? stackStartAliasCommand : startCommand, + options.stackBackend === "stack" ? stackStatusAliasCommand : statusCommand, + options.stackBackend === "stack" ? stackStopAliasCommand : stopCommand, + storageCommand, + telemetryCommand, + testCommand, + unlinkCommand, + vanitySubdomainsCommand, + whoamiCommand, + ], + options.apiFeatures ?? [], + ), + ), Command.provide( Layer.unwrap( Effect.gen(function* () { diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index 1f5e6ed575..e1e3a47b22 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -19,6 +19,15 @@ is resolved before the command tree is built, so `--experimental` alone does not commands. When the feature is disabled the noun is absent from help, completion and the generated command documentation. +## Joining hand-written groups + +A generated command joins the hand-written group of the same name, at any depth, so a noun such as +`warehouse` can sit beside hand-written `warehouse` commands. The generator fails only when a +generated command path equals a hand-written command or group, or when a group on its path is a +hand-written command. A hand-written group is described by its own code, so the nouns table gives a +description only to groups the generator creates. A group that wraps its own subcommands after +`Command.withSubcommands` (listed in `sealedGroups`) cannot be joined. + ## Files Read | Path | Format | When | diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 0436c50641..801c357967 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -26,7 +26,7 @@ import { import type { ApiCommandEntry } from "./api-command.model.ts"; import { apiCommands } from "./generated.ts"; import { apiCommandSchemas } from "./generated.schemas.ts"; -import { apiCommandGroups } from "./runtime.ts"; +import { withApiCommands } from "./runtime.ts"; type Json = Readonly>; @@ -272,7 +272,7 @@ const withApi = (status: number, sent: Array) => { }; const warehouseRoot = Command.make("supabase").pipe( - Command.withSubcommands(apiCommandGroups(["warehouse"])), + Command.withSubcommands(withApiCommands([], ["warehouse"])), Command.withGlobalFlags(GLOBAL_FLAGS), ); diff --git a/apps/cli/src/commands/api/api-command-join.integration.test.ts b/apps/cli/src/commands/api/api-command-join.integration.test.ts new file mode 100644 index 0000000000..42b8b9df03 --- /dev/null +++ b/apps/cli/src/commands/api/api-command-join.integration.test.ts @@ -0,0 +1,207 @@ +import { BunServices } from "@effect/platform-bun"; +import { describe, expect, it } from "@effect/vitest"; +import { openApiOperationIdMap } from "@supabase/api/effect"; +import openApiSpec from "@supabase/api/openapi.json"; +import { Console, Effect, Layer, Predicate, Schema, Stdio } from "effect"; +import { CliOutput, Command } from "effect/cli"; + +import { deriveApiCommands } from "../../../scripts/api-command-derive.ts"; +import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; +import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; +import { + VALID_REF, + VALID_TOKEN, + buildTestRuntime, + mockCommandPlatformApi, + mockCommandSettings, + useTempWorkdir, + withConfigEnv, +} from "../../../tests/helpers/command-mocks.ts"; +import { + fakeConsole, + mockOutput, + mockRuntimeInfo, + mockStdin, + mockTelemetryRuntime, + mockTty, +} from "../../../tests/helpers/mocks.ts"; +import type { ApiNoun } from "./api-command-policy.ts"; +import { withApiCommands } from "./runtime.ts"; + +const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); + +const isRecord = (value: unknown): value is Record => + Predicate.isObject(value) && !Array.isArray(value); + +const OPERATIONS = { + "v1-list-migration-history": { group: "fixture", method: "list" }, + "v1-get-a-migration": { group: "fixture.inner", method: "get" }, + "v1-apply-a-migration": { group: "fixture.fresh", method: "create" }, +}; + +const fixtureSpec = () => { + const spec: Record = structuredClone(openApiSpec); + for (const item of Object.values(isRecord(spec["paths"]) ? spec["paths"] : {})) { + for (const operation of Object.values(isRecord(item) ? item : {})) { + if (!isRecord(operation)) continue; + const operationId = String(operation["operationId"]); + if (!Object.hasOwn(OPERATIONS, operationId)) continue; + operation["x-operation"] = Reflect.get(OPERATIONS, operationId); + operation["x-scalar-stability"] = "experimental"; + } + } + return spec; +}; + +/** `fixture` and `fixture inner` are hand-written; only `fixture fresh` needs a description. */ +const fixtureNoun: ApiNoun = { + feature: "warehouse", + groups: { fresh: "Fresh fixtures" }, +}; + +const derived = deriveApiCommands({ + spec: fixtureSpec(), + generated: Object.keys(OPERATIONS), + nouns: { fixture: fixtureNoun }, + operationIdMap: openApiOperationIdMap, + handWritten: { + groups: new Set(["fixture", "fixture inner"]), + leaves: new Set(["fixture ping", "fixture inner pong"]), + sealed: new Set(), + }, +}); + +const pong = Command.make("pong", {}, () => Console.log("handwritten pong")).pipe( + Command.withDescription("Answer from the inner group"), +); +const inner = Command.make("inner").pipe( + Command.withDescription("Hand-written inner group"), + Command.withSubcommands([pong]), +); +const ping = Command.make("ping", {}, () => Console.log("handwritten ping")).pipe( + Command.withDescription("Answer from the group"), +); +const fixtureGroup = Command.make("fixture").pipe( + Command.withDescription("Hand-written fixture group"), + Command.withSubcommands([ping, { group: "Nested", commands: [inner] }]), +); + +const MIGRATION_VERSION = "20250312000000"; +const MIGRATIONS_PATH = `/v1/projects/${VALID_REF}/database/migrations`; +const tempRoot = useTempWorkdir("supabase-api-join-int-"); + +const run = ( + args: ReadonlyArray, + enabledFeatures: ReadonlyArray = ["warehouse"], +) => { + const root = Command.make("supabase").pipe( + Command.withSubcommands( + withApiCommands([fixtureGroup], enabledFeatures, { + nouns: { fixture: fixtureNoun }, + entries: derived.entries, + }), + ), + Command.withGlobalFlags(GLOBAL_FLAGS), + ); + const out = mockOutput({ format: "text" }); + const { console, calls } = fakeConsole(); + const layer = Layer.mergeAll( + buildTestRuntime({ + out, + api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), + cliSettings: mockCommandSettings({ workdir: tempRoot.current }), + tty: mockTty({ stdinIsTty: false, stdoutIsTty: false }), + stdin: mockStdin(false), + cliArgs: args, + }), + BunServices.layer, + CliOutput.layer(textCliOutputFormatter()), + Layer.succeed(ExperimentalFlag, false), + mockTelemetryRuntime({ configDir: tempRoot.current }), + mockRuntimeInfo({ cwd: tempRoot.current, homeDir: tempRoot.current }), + Stdio.layerTest({ args: Effect.succeed(args) }), + ); + const effect = withConfigEnv( + { SUPABASE_ACCESS_TOKEN: VALID_TOKEN, SUPABASE_NO_KEYRING: "1" }, + Command.runWith(root, { version: "0.0.0-test" })(args), + ).pipe(Effect.provideService(Console.Console, console), Effect.provide(layer)); + return { out, output: () => calls.join("\n"), effect }; +}; + +describe("generated commands joining hand-written groups", () => { + it("derives the fixture commands without problems", () => { + expect(derived.problems).toEqual([]); + expect(derived.entries.map((entry) => entry.command.join(" "))).toEqual([ + "fixture fresh create", + "fixture inner get", + "fixture list", + ]); + }); + + it.effect.each([ + { argv: ["fixture", "ping"], expected: "handwritten ping" }, + { argv: ["fixture", "inner", "pong"], expected: "handwritten pong" }, + ])("still runs the hand-written command $argv", ({ argv, expected }) => { + const { output, effect } = run(argv); + return Effect.gen(function* () { + yield* effect; + expect(output()).toContain(expected); + }); + }); + + it.effect.each([ + { argv: ["fixture", "list"], method: "GET", path: MIGRATIONS_PATH }, + { + argv: ["fixture", "inner", "get", MIGRATION_VERSION], + method: "GET", + path: `${MIGRATIONS_PATH}/${MIGRATION_VERSION}`, + }, + { + argv: ["fixture", "fresh", "create", "--query", "select 1"], + method: "POST", + path: MIGRATIONS_PATH, + }, + ])("runs the generated command $argv beside the hand-written ones", ({ argv, method, path }) => { + const { out, effect } = run([...argv, `--remote=${VALID_REF}`, "--yes", "--dry-run"]); + return Effect.gen(function* () { + yield* effect; + expect(decodeJson(out.stdoutText)).toMatchObject({ method, path }); + }); + }); + + it.effect("lists generated and hand-written commands together in the group help", () => { + const { output, effect } = run(["fixture", "--help"]); + return Effect.gen(function* () { + yield* effect; + const help = output(); + expect(help).toContain("Hand-written fixture group"); + expect(help).toContain("ping"); + expect(help).toContain("list"); + expect(help).toContain("fresh"); + expect(help).toContain("Nested"); + expect(help).toContain("inner"); + }); + }); + + it.effect("lists generated and hand-written commands together in the nested group help", () => { + const { output, effect } = run(["fixture", "inner", "--help"]); + return Effect.gen(function* () { + yield* effect; + const help = output(); + expect(help).toContain("Hand-written inner group"); + expect(help).toContain("pong"); + expect(help).toContain("get"); + }); + }); + + it.effect("leaves the hand-written group alone while the feature is off", () => { + const { output, effect } = run(["fixture", "--help"], []); + return Effect.gen(function* () { + yield* effect; + const help = output(); + expect(help).toContain("ping"); + expect(help).not.toContain("list"); + expect(help).not.toContain("fresh"); + }); + }); +}); diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 84ac2640a1..776369850b 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -18,13 +18,23 @@ export const verbVocabulary = [ ] as const; export interface ApiNoun { - readonly description: string; + /** Help text of the noun's group; set only when no hand-written group of that name exists. */ + readonly description?: string; /** Feature that gates every command under the noun. */ readonly feature: ExperimentalFeature; - /** Help text of each sub-group, keyed by its dotted path below the noun, e.g. `"tables.layout"`. */ + /** + * Help text of each sub-group the generator creates, keyed by its dotted path below the noun, + * e.g. `"tables.layout"`; a sub-group that exists in a hand-written group has no entry. + */ readonly groups?: Readonly>; } +/** + * Hand-written groups that wrap their own subcommands after `Command.withSubcommands`, which a + * generated command cannot join; each entry is a space-joined group path. + */ +export const sealedGroups: ReadonlySet = new Set(["stack"]); + /** Only these operations generate commands, and their response `links` lead to the reads a `--wait` polls. */ export const generatedOperations: ReadonlyArray = [ "v2-get-warehouse-status", diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts index c0f562caf4..7b6c7c2cf1 100644 --- a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts @@ -27,7 +27,7 @@ import { mockTty, } from "../../../tests/helpers/mocks.ts"; import type { ApiNoun } from "./api-command-policy.ts"; -import { apiCommandGroup } from "./runtime.ts"; +import { withApiCommands } from "./runtime.ts"; const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); @@ -75,11 +75,16 @@ const derived = deriveApiCommands({ generated: Object.keys(FIXTURE_OPERATIONS), nouns: { fixture: fixtureNoun }, operationIdMap: openApiOperationIdMap, - handWrittenTopLevel: new Set(), + handWritten: { groups: new Set(), leaves: new Set(), sealed: new Set() }, }); const fixtureRoot = Command.make("supabase").pipe( - Command.withSubcommands([apiCommandGroup("fixture", fixtureNoun, derived.entries)]), + Command.withSubcommands( + withApiCommands([], [fixtureNoun.feature], { + nouns: { fixture: fixtureNoun }, + entries: derived.entries, + }), + ), Command.withGlobalFlags(GLOBAL_FLAGS), ); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 43ee32e503..59d24812f1 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -56,7 +56,7 @@ import { assembleInput, decodeInput, previewRequest } from "./api-command-reques import { apiCommands } from "./generated.ts"; import { readApiCommand } from "./api-command.annotation.ts"; import { readCommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; -import { apiCommandGroup, apiCommandGroups } from "./runtime.ts"; +import { withApiCommands } from "./runtime.ts"; import { standardFailureFor } from "../../shared/cli/standard-errors.ts"; import { EventUpgradeSuggested } from "../../shared/telemetry/event-catalog.ts"; import { resolveApiCommandFeatures } from "./api-command-features.ts"; @@ -236,7 +236,7 @@ const withApi = (route: Route, sent: Array) => { }; const warehouseRoot = Command.make("supabase").pipe( - Command.withSubcommands(apiCommandGroups(["warehouse"])), + Command.withSubcommands(withApiCommands([], ["warehouse"])), Command.withGlobalFlags(ROOT_GLOBAL_FLAGS), ); @@ -1480,11 +1480,12 @@ describe("generated warehouse commands", () => { }; const fixtureRoot = (entry: ApiCommandEntry) => Command.make("supabase").pipe( - Command.withSubcommands([ - apiCommandGroup("fixture", { description: "Fixture commands", feature: "warehouse" }, [ - entry, - ]), - ]), + Command.withSubcommands( + withApiCommands([], ["warehouse"], { + nouns: { fixture: { description: "Fixture commands", feature: "warehouse" } }, + entries: [entry], + }), + ), Command.withGlobalFlags(ROOT_GLOBAL_FLAGS), ); diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index aa40f68f1a..91fa50c5c8 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -1,4 +1,4 @@ -import { Cause, Effect, Exit, Layer, Option } from "effect"; +import { Array as Arr, Cause, Effect, Exit, Layer, Option } from "effect"; import { Argument, Command, Flag } from "effect/cli"; import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; @@ -361,55 +361,106 @@ const leafOf = (entry: ApiCommandEntry, entries: ReadonlyArray) }; type ApiLeaf = ReturnType; -type ApiGroup = Command.Command, Command.Services>; + +/** A command with generated commands merged in: it fails and requires what `C` and the generated leaves do. */ +type WithApi = Command.Command< + string, + {}, + {}, + Command.Error | Command.Error, + Command.Services | Command.Services +>; + +type Subcommands = ReadonlyArray; + +/** The noun definitions and entries the generated commands are built from. */ +interface ApiCommandSource { + readonly nouns: Readonly>; + readonly entries: ReadonlyArray; +} const startsWith = (command: ReadonlyArray, prefix: ReadonlyArray): boolean => prefix.every((word, index) => command[index] === word); -const groupOf = ( +const leafCache = new WeakMap(); + +const cachedLeaf = (entry: ApiCommandEntry, entries: ReadonlyArray): ApiLeaf => { + const cached = leafCache.get(entry); + if (cached !== undefined) return cached; + const leaf = leafOf(entry, entries); + leafCache.set(entry, leaf); + return leaf; +}; + +const groupDescription = (path: ReadonlyArray, noun: ApiNoun): string | undefined => + path.length === 1 ? noun.description : noun.groups?.[path.slice(1).join(".")]; + +/** The group at `path`, taking the generated commands below it; `existing` is the hand-written group it joins. */ +const groupAt = ( + existing: Command.Command.Any | undefined, path: ReadonlyArray, - description: string, - definition: ApiNoun, + noun: ApiNoun, entries: ReadonlyArray, -): ApiGroup => { +): Command.Command.Any => { + const name = path[path.length - 1] ?? ""; const under = entries.filter((entry) => startsWith(entry.command, path)); + const childNames = new Set( + under.flatMap((entry) => + entry.command.length > path.length + 1 + ? entry.command.slice(path.length, path.length + 1) + : [], + ), + ); + const existingChildren = existing?.subcommands ?? []; + const existingNames = new Set( + existingChildren.flatMap(({ commands }) => commands.map((child) => child.name)), + ); + const joined = existingChildren.flatMap(({ group, commands }): Subcommands => { + const children = Arr.map(commands, (child) => + childNames.has(child.name) ? groupAt(child, [...path, child.name], noun, entries) : child, + ); + return group === undefined ? children : [{ group, commands: children }]; + }); const leaves = under .filter((entry) => entry.command.length === path.length + 1) - .map((entry) => leafOf(entry, entries)); - const children = Object.entries(definition.groups ?? {}).flatMap(([key, childDescription]) => { - const childPath = [...path.slice(0, 1), ...key.split(".")]; - const isChild = childPath.length === path.length + 1 && startsWith(childPath, path); - const hasCommands = under.some((entry) => startsWith(entry.command, childPath)); - return isChild && hasCommands - ? [groupOf(childPath, childDescription, definition, entries)] - : []; - }); - return Command.make(path[path.length - 1] ?? "").pipe( - Command.withDescription(`${description} (experimental)`), - Command.withShortDescription(`${description} (experimental)`), - Command.withSubcommands([...leaves, ...children]), - ); + .map((entry) => cachedLeaf(entry, entries)); + const created = [...childNames] + .filter((child) => !existingNames.has(child)) + .map((child) => groupAt(undefined, [...path, child], noun, entries)); + const description = `${groupDescription(path, noun) ?? name} (experimental)`; + const base = + existing ?? + Command.make(name).pipe( + Command.withDescription(description), + Command.withShortDescription(description), + ); + return Command.withSubcommands(base, [...joined, ...leaves, ...created]); }; -/** The command group of `noun`, with its sub-groups and one leaf per entry whose command sits under it. */ -export const apiCommandGroup = ( - noun: string, - definition: ApiNoun, - entries: ReadonlyArray, -) => groupOf([noun], definition.description, definition, entries); - -const groupCache = new Map>(); - /** - * The noun groups of the generated Management API commands, one per noun whose feature is - * enabled; a group is built on first use. + * `handWritten` with the generated Management API commands of every enabled noun merged in: a + * noun named like a hand-written command adds its commands and sub-groups to that command at any + * depth, and any other noun becomes a new group in alphabetical position. */ -export const apiCommandGroups = (enabledFeatures: ReadonlyArray) => - Object.entries(nouns).flatMap(([noun, definition]) => { - if (!enabledFeatures.includes(definition.feature)) return []; - const cached = groupCache.get(noun); - if (cached !== undefined) return [cached]; - const group = apiCommandGroup(noun, definition, apiCommands); - groupCache.set(noun, group); - return [group]; - }); +export const withApiCommands = >( + handWritten: C, + enabledFeatures: ReadonlyArray, + source: ApiCommandSource = { nouns, entries: apiCommands }, +): ReadonlyArray> => { + const merged: Array = [...handWritten]; + for (const [name, noun] of Object.entries(source.nouns)) { + if (!enabledFeatures.includes(noun.feature)) continue; + const index = merged.findIndex((command) => command.name === name); + if (index >= 0) { + merged[index] = groupAt(merged[index], [name], noun, source.entries); + } else { + const position = merged.findIndex((command) => command.name > name); + merged.splice( + position < 0 ? merged.length : position, + 0, + groupAt(undefined, [name], noun, source.entries), + ); + } + } + return merged; +}; From d8edf25ad416a68af64729cc93413e806ec3c3c2 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 16:28:14 +0100 Subject: [PATCH 18/45] chore(cli): provide stack layers per subcommand so any group can be joined Generated commands rebuild the group they join, which bypassed the stack group's own Command.provide. Each stack subcommand now provides the stack runtime layer itself, so the sealed-group list and its generator check go. --- apps/cli/scripts/api-command-derive.ts | 7 ------- apps/cli/scripts/api-command-derive.unit.test.ts | 8 -------- apps/cli/scripts/generate-api-commands.ts | 8 ++------ apps/cli/src/commands/api/SIDE_EFFECTS.md | 5 +++-- .../api/api-command-join.integration.test.ts | 1 - apps/cli/src/commands/api/api-command-policy.ts | 6 ------ .../api/api-command-shapes.integration.test.ts | 2 +- .../commands/experimental/stack/stack.command.ts | 14 +++++++++++++- 8 files changed, 19 insertions(+), 32 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index df40307273..afdf6032c5 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -123,8 +123,6 @@ export interface HandWrittenCommands { readonly groups: ReadonlySet; /** Paths of the commands that have none. */ readonly leaves: ReadonlySet; - /** Groups a generated command cannot join. */ - readonly sealed: ReadonlySet; } interface DeriveInput { @@ -812,11 +810,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { `command "${commandKey}" needs "${groupKey}" as a group, but it is a hand-written command`, ); } - if (handWritten.sealed.has(groupKey)) { - fail( - `command "${commandKey}" cannot join the hand-written group "${groupKey}", which wraps its own subcommands`, - ); - } if (depth < 2) continue; if (commandOwners.has(groupKey)) fail(`command "${groupKey}" is both a command and a group`); groupPaths.add(groupKey); diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index b9c045c9f4..0338f959a1 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -60,12 +60,10 @@ const handWritten = ( tree: { groups?: ReadonlyArray; leaves?: ReadonlyArray; - sealed?: ReadonlyArray; } = {}, ) => ({ groups: new Set(tree.groups ?? ["db"]), leaves: new Set(tree.leaves), - sealed: new Set(tree.sealed), }); const derive = ( @@ -1576,12 +1574,6 @@ describe("deriveApiCommands", () => { { leaves: ["thing sub"] }, 'create-thing: command "thing sub create" needs "thing sub" as a group, but it is a hand-written command', ], - [ - "a group path that is a sealed hand-written group", - deep, - { groups: ["thing", "thing sub"], sealed: ["thing sub"] }, - 'create-thing: command "thing sub create" cannot join the hand-written group "thing sub", which wraps its own subcommands', - ], ])("rejects %s", (_label, operations, tree, problem) => { const result = derive(operations, undefined, { overrides: { handWritten: handWritten(tree) }, diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index 4edc50c646..faf7bc252d 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -3,11 +3,7 @@ import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } fr import type { Command } from "effect/cli"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; import { rootCommandForFeatures } from "../src/cli/root.ts"; -import { - generatedOperations, - nouns, - sealedGroups, -} from "../src/commands/api/api-command-policy.ts"; +import { generatedOperations, nouns } from "../src/commands/api/api-command-policy.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { renderApiCommandReference } from "./api-command-reference.ts"; import { @@ -62,7 +58,7 @@ const handWrittenCommands = Effect.fn("ApiCommands.walkHandWritten")(function* ( "handWritten.groups": found.groups.size, "handWritten.leaves": found.leaves.size, }); - return { ...found, sealed: sealedGroups } satisfies HandWrittenCommands; + return found satisfies HandWrittenCommands; }); /** Formats in memory with the repo's oxfmt config so the committed files match `pnpm fmt`. */ diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index e1e3a47b22..2f6f9892e0 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -25,8 +25,9 @@ A generated command joins the hand-written group of the same name, at any depth, `warehouse` can sit beside hand-written `warehouse` commands. The generator fails only when a generated command path equals a hand-written command or group, or when a group on its path is a hand-written command. A hand-written group is described by its own code, so the nouns table gives a -description only to groups the generator creates. A group that wraps its own subcommands after -`Command.withSubcommands` (listed in `sealedGroups`) cannot be joined. +description only to groups the generator creates. Joining rebuilds the group, so a hand-written +group carries only metadata (descriptions, flags, subcommands) and provides layers on each +subcommand: a `Command.provide` on the group itself would be bypassed for every subcommand. ## Files Read diff --git a/apps/cli/src/commands/api/api-command-join.integration.test.ts b/apps/cli/src/commands/api/api-command-join.integration.test.ts index 42b8b9df03..9a7230ab63 100644 --- a/apps/cli/src/commands/api/api-command-join.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-join.integration.test.ts @@ -67,7 +67,6 @@ const derived = deriveApiCommands({ handWritten: { groups: new Set(["fixture", "fixture inner"]), leaves: new Set(["fixture ping", "fixture inner pong"]), - sealed: new Set(), }, }); diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 776369850b..70f9ff3cb0 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -29,12 +29,6 @@ export interface ApiNoun { readonly groups?: Readonly>; } -/** - * Hand-written groups that wrap their own subcommands after `Command.withSubcommands`, which a - * generated command cannot join; each entry is a space-joined group path. - */ -export const sealedGroups: ReadonlySet = new Set(["stack"]); - /** Only these operations generate commands, and their response `links` lead to the reads a `--wait` polls. */ export const generatedOperations: ReadonlyArray = [ "v2-get-warehouse-status", diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts index 7b6c7c2cf1..afa3b79499 100644 --- a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts @@ -75,7 +75,7 @@ const derived = deriveApiCommands({ generated: Object.keys(FIXTURE_OPERATIONS), nouns: { fixture: fixtureNoun }, operationIdMap: openApiOperationIdMap, - handWritten: { groups: new Set(), leaves: new Set(), sealed: new Set() }, + handWritten: { groups: new Set(), leaves: new Set() }, }); const fixtureRoot = Command.make("supabase").pipe( diff --git a/apps/cli/src/commands/experimental/stack/stack.command.ts b/apps/cli/src/commands/experimental/stack/stack.command.ts index ea8a90dc79..0f8aa7ddc2 100644 --- a/apps/cli/src/commands/experimental/stack/stack.command.ts +++ b/apps/cli/src/commands/experimental/stack/stack.command.ts @@ -59,40 +59,53 @@ export const stackStartRuntimeLayer = Layer.mergeAll( identityStitchLayer, ); +// Layers sit on each subcommand: a generated command joining this group would bypass a group-level +// `Command.provide` (see src/commands/api/SIDE_EFFECTS.md). const stackStartCommand = stackStartCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "start"])), Command.provide(stackStartRuntimeLayer), + Command.provide(stackRuntimeLayer), ); const stackStopCommand = stackStopCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "stop"])), + Command.provide(stackRuntimeLayer), ); const stackStatusCommand = stackStatusCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "status"])), + Command.provide(stackRuntimeLayer), ); const stackDestroyCommand = stackDestroyCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "destroy"])), + Command.provide(stackRuntimeLayer), ); const stackLogsCommand = stackLogsCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "logs"])), + Command.provide(stackRuntimeLayer), ); const stackListCommand = stackListCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "list"])), + Command.provide(stackRuntimeLayer), ); const stackPruneCommand = stackPruneCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "prune"])), + Command.provide(stackRuntimeLayer), ); const stackRestartCommand = stackRestartCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "restart"])), + Command.provide(stackRuntimeLayer), ); const stackInstallCommand = stackInstallCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "install"])), + Command.provide(stackRuntimeLayer), ); const stackOutdatedCommand = stackOutdatedCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "outdated"])), + Command.provide(stackRuntimeLayer), ); const stackUpdateCommand = stackUpdateCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "update"])), Command.provide(stackStartRuntimeLayer), + Command.provide(stackRuntimeLayer), ); export const stackCommand = Command.make("stack").pipe( @@ -113,5 +126,4 @@ export const stackCommand = Command.make("stack").pipe( stackStopCommand, stackUpdateCommand, ]), - Command.provide(stackRuntimeLayer), ); From 9609fa286198bc6f2a8246eb69f8fcedbdd932cc Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Wed, 18 Nov 2026 16:54:56 +0100 Subject: [PATCH 19/45] feat(cli): add warehouse tables list and get (#7689) Generate `warehouse tables list` from `GET /v2/projects/{ref}/warehouse/tables`. It lists the tables selected for Warehouse replication with their freshness: - `status`: `syncing`, `live`, `error`, `stopped` or `unknown`; - the raw replication state; - when the state was observed; - `lag_ms`, the flush lag of the replication slot that carries the table. Text output shows one row per table. `-o json` and `-o yaml` also include the full replication feedback. That feedback includes `flush_lag_bytes`, which reads 0 for a caught-up slot whose lag time Postgres no longer reports. Also generate `warehouse tables get ` from `GET /v2/projects/{ref}/warehouse/tables/{table_id}`. It reads one of those tables by the source OID that `warehouse tables list` shows as its ID, with the same attributes. Its text output also shows the nested replication feedback, and a table that isn't replicated is an API error. This is the first generated command with a positional argument on a real operation, so the generic bindings test now supplies positional path parameters. Two generic changes to the text output of generated commands: - an empty collection prints `No results` instead of `Data -`; - a column that holds a nested object in any row is left out of the table. Before, rows with a nested object printed it as compact JSON while rows with `null` printed `-`. The tables contracts, and `flush_lag_bytes` in the status contract, come from OpenAPI overrides until they ship in the deployed Management API specification. Stacked on #7640. Depends on https://github.com/supabase/platform/pull/42055 and https://github.com/supabase/platform/pull/42108. Implements PIPE-1451 and PIPE-1453. --------- Co-authored-by: Julien Goux --- .../command-surface.integration.test.ts | 3 + apps/cli/src/commands/api/SIDE_EFFECTS.md | 16 +- .../api-command-bindings.integration.test.ts | 39 +- .../src/commands/api/api-command-policy.ts | 3 + .../src/commands/api/api-command.format.ts | 8 +- .../api/api-command.format.unit.test.ts | 4 + .../api/api-commands.integration.test.ts | 111 ++++ apps/cli/src/commands/api/generated.md | 21 + .../cli/src/commands/api/generated.schemas.ts | 281 ++++++++- apps/cli/src/commands/api/generated.ts | 58 ++ packages/api/scripts/openapi-overrides.json | 533 +++++++++++++++++- packages/api/src/generated/contracts.ts | 347 +++++++++++- packages/api/src/generated/effect-client.ts | 32 ++ packages/api/src/generated/openapi.json | 513 ++++++++++++++++- packages/api/src/generated/permissions.ts | 2 + 15 files changed, 1948 insertions(+), 23 deletions(-) diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 332a77030b..052b2a00c3 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -58,6 +58,9 @@ describe("command surface", () => { "warehouse disable", "warehouse enable", "warehouse status", + "warehouse tables", + "warehouse tables get", + "warehouse tables list", "warehouse teardowns", "warehouse teardowns get", ]); diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index 2f6f9892e0..a97891d061 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -145,14 +145,14 @@ Text rendering applies on a terminal by default, with `--output-format text` (al with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the API's JSON bytes. `-o` takes precedence over `--output-format`. -| Mode | stdout | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| text presentation | the response as labelled fields and tables, nested objects as indented blocks, `-` for null or empty values; with `--wait` the final read response; an empty response prints `Done.` | -| JSON presentation | the API's JSON response bytes, unchanged, preserving unknown and null fields; with `--wait` the final read response | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | -| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | +| Mode | stdout | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| text presentation | the response as labelled fields and tables, nested objects as indented blocks (a collection table omits a column holding nested values; `-o json` shows them), `-` for null or empty values; with `--wait` the final read response; an empty response prints `Done.` and an empty collection `No results` | +| JSON presentation | the API's JSON response bytes, unchanged, preserving unknown and null fields; with `--wait` the final read response | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | +| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | +| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 801c357967..40165faa4b 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -111,6 +111,7 @@ const shapeOf = (schema: unknown): unknown => { const PATTERN_SAMPLES: Readonly> = { "^[a-f0-9]{64}$": "ab".repeat(32), "^[a-z]+$": "zyxwvutsrqponmlkjihg", + "^[1-9]\\d*$": "16385", "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$": "7579647f-2cdc-466c-982e-425958a2f985", }; @@ -198,6 +199,15 @@ const inputsOf = ( return [...queries, ...fields]; }; +/** The path parameters besides `ref`, each supplied as a positional argument. */ +const positionalsOf = (operation: SpecOperation) => + operation.parameters + .filter((parameter) => parameter["in"] === "path" && parameter["name"] !== "ref") + .map((parameter) => ({ + name: String(parameter["name"]), + sample: String(sampleOf(parameter["schema"])), + })); + const argvOf = (inputs: ReadonlyArray): ReadonlyArray => inputs.flatMap((input) => Array.isArray(input.sample) @@ -330,13 +340,26 @@ describe("generated command bindings", () => { const { operationId } = row.api; const operation = operationOf(operationId); const inputs = inputsOf(operation, row.api.bindings); - const expectedPath = operation.template.replace("{ref}", VALID_REF); + const positionals = positionalsOf(operation); + const expectedPath = positionals.reduce( + (path, { name, sample }) => path.replace(`{${name}}`, sample), + operation.template.replace("{ref}", VALID_REF), + ); describe(row.path.join(" "), () => { it("binds the path reference and every other input to the spec's location", () => { - expect(operation.template.match(/\{[^}]+\}/g)).toEqual(["{ref}"]); + expect(operation.template.match(/\{[^}]+\}/g)).toEqual([ + "{ref}", + ...positionals.map(({ name }) => `{${name}}`), + ]); const expected = [ { location: "path", name: "ref", source: "target" }, + ...positionals.map(({ name }) => ({ + location: "path", + name, + source: "argument", + argument: generated.find((entry) => entry.operationId === operationId)?.argument?.name, + })), ...inputs.map((input) => input.location === "query" ? { location: "query", name: input.field, source: "flag", flag: input.flag } @@ -356,7 +379,11 @@ describe("generated command bindings", () => { it.effect("sends every input at its binding", () => Effect.gen(function* () { - const requests = yield* send(row.path, argvOf(inputs), operation.responseStatus); + const requests = yield* send( + row.path, + [...positionals.map(({ sample }) => sample), ...argvOf(inputs)], + operation.responseStatus, + ); expect(requests).toHaveLength(1); const [request] = requests; expect(request?.method).toBe(operation.method); @@ -371,7 +398,11 @@ describe("generated command bindings", () => { it.effect("sends only the inputs the spec requires when no other flag is given", () => Effect.gen(function* () { const required = inputs.filter((input) => input.required); - const requests = yield* send(row.path, argvOf(required), operation.responseStatus); + const requests = yield* send( + row.path, + [...positionals.map(({ sample }) => sample), ...argvOf(required)], + operation.responseStatus, + ); expect(requests).toHaveLength(1); const [request] = requests; expect(Object.fromEntries(new URLSearchParams(request?.search))).toEqual( diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 70f9ff3cb0..9d00ea8806 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -36,6 +36,8 @@ export const generatedOperations: ReadonlyArray = [ "v2-enable-warehouse", "v2-disable-warehouse", "v2-get-warehouse-teardown", + "v2-list-warehouse-tables", + "v2-get-warehouse-table", ]; export const nouns = { @@ -43,6 +45,7 @@ export const nouns = { description: "Manage the data warehouse for a project", feature: "warehouse", groups: { + tables: "Inspect tables replicated to Warehouse", teardowns: "Inspect Warehouse cleanup operations", }, }, diff --git a/apps/cli/src/commands/api/api-command.format.ts b/apps/cli/src/commands/api/api-command.format.ts index b4d08c4c41..32c33f7ca1 100644 --- a/apps/cli/src/commands/api/api-command.format.ts +++ b/apps/cli/src/commands/api/api-command.format.ts @@ -132,13 +132,15 @@ const resourceLines = (document: JsonObject): ReadonlyArray | undefined const keys = Object.keys(document); const data = document["data"]; if (keys.length !== 1 || keys[0] !== "data") return undefined; + if (Array.isArray(data) && data.length === 0) return ["No results"]; if (isResource(data)) { return [humanize(String(data["type"])), ...blockLines(resourceEntries(data), INDENT)]; } - if (Array.isArray(data) && data.length > 0 && data.every(isResource)) { + if (Array.isArray(data) && data.every(isResource)) { const rows = data.map((resource) => Object.fromEntries(resourceEntries(resource))); - const columns = unionKeys(rows).filter((column) => - rows.some((row) => isScalar(row[column]) && row[column] !== undefined), + const columns = unionKeys(rows).filter( + (column) => + rows.every((row) => isScalar(row[column])) && rows.some((row) => row[column] !== undefined), ); return [humanize(String(data[0]?.["type"])), ...objectTable(rows, columns, "")]; } diff --git a/apps/cli/src/commands/api/api-command.format.unit.test.ts b/apps/cli/src/commands/api/api-command.format.unit.test.ts index 60621a4a4e..c8fb7997b5 100644 --- a/apps/cli/src/commands/api/api-command.format.unit.test.ts +++ b/apps/cli/src/commands/api/api-command.format.unit.test.ts @@ -33,4 +33,8 @@ describe("renderResponseText", () => { ["Name n", "Limits", " Max 1", " Nested", " Deep yes", ""].join("\n"), ); }); + + it("prints a clear line for an empty resource collection", () => { + expect(renderResponseText({ data: [] })).toBe("No results\n"); + }); }); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 59d24812f1..2386d39f88 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -369,6 +369,117 @@ describe("generated warehouse commands", () => { }); }); }); + describe("warehouse tables list", () => { + const tablesPath = `/v2/projects/${VALID_REF}/warehouse/tables`; + const table = (attributes: Readonly>) => ({ + type: "warehouse_table", + attributes: { schema: "public", ...attributes, observed_at: "2026-11-17T10:00:00Z" }, + }); + const body = { + data: [ + { + id: "16385", + ...table({ + name: "orders", + warehouse_name: '"public"."orders"', + status: "live", + replication_state: "following_wal", + lag_ms: 120, + replication_feedback: { + source: "pipeline_apply", + active: true, + wal_status: "reserved", + write_lag_ms: 80, + flush_lag_ms: 120, + flush_lag_bytes: 2048, + feedback_age_ms: 5, + }, + }), + }, + { + id: "16402", + ...table({ + name: "events", + warehouse_name: '"public"."events"', + status: "syncing", + replication_state: "copying_table", + lag_ms: null, + replication_feedback: null, + }), + }, + ], + }; + + it.effect("renders one row per table without the nested replication feedback", () => { + const { out, sent, run } = setup(["warehouse", "tables", "list"], { + route: ok(body), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([{ method: "GET", path: tablesPath, search: "", body: undefined }]); + expect(out.stdoutText).toMatch(/16385\s.*orders.*live.*following_wal.*120/); + expect(out.stdoutText).toMatch(/16402\s.*events.*syncing.*copying_table/); + expect(out.stdoutText).not.toMatch(/pipeline_apply|feedback_age|FEEDBACK/i); + }); + }); + + it.effect("passes the document, including replication feedback, through as JSON", () => { + const { out, run } = setup(["warehouse", "tables", "list", "-o", "json"], { + route: ok(body), + }); + return Effect.gen(function* () { + yield* run; + expect(decodeJson(out.stdoutText)).toEqual(body); + }); + }); + }); + describe("warehouse tables get", () => { + const tablePath = `/v2/projects/${VALID_REF}/warehouse/tables/16385`; + const body = { + data: { + id: "16385", + type: "warehouse_table", + attributes: { + schema: "public", + name: "orders", + warehouse_name: '"public"."orders"', + status: "live", + replication_state: "following_wal", + lag_ms: 120, + observed_at: "2026-11-17T10:00:00Z", + replication_feedback: { + source: "pipeline_apply", + active: true, + wal_status: "reserved", + write_lag_ms: 80, + flush_lag_ms: 120, + flush_lag_bytes: 2048, + feedback_age_ms: 5, + }, + }, + }, + }; + + it.effect( + "requests the table by OID and renders its attributes and replication feedback", + () => { + const { out, sent, run } = setup(["warehouse", "tables", "get", "16385"], { + route: ok(body), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([{ method: "GET", path: tablePath, search: "", body: undefined }]); + expect(out.stdoutText).toMatch(/Warehouse table/); + expect(out.stdoutText).toMatch(/Name\s+orders/); + expect(out.stdoutText).toMatch(/Replication state\s+following_wal/); + expect(out.stdoutText).toMatch(/Replication feedback\n\s+Source\s+pipeline_apply/); + expect(out.stdoutText).toMatch(/Flush lag bytes\s+2048/); + }); + }, + ); + }); describe("warehouse connection", () => { const connectionPath = `/v2/projects/${VALID_REF}/warehouse/connection`; const host = `${VALID_REF}.warehouse.example.invalid`; diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index d01f5b9494..9a1bb54ab3 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -77,6 +77,27 @@ Returns provisioning, configured compute, replication, cleanup lifecycle and sup - Feature: `warehouse`. - Request: `GET /v2/projects/{ref}/warehouse/status` (`v2-get-warehouse-status`), success 200 json. +## `supabase warehouse tables get` + +Get a table replicated to Warehouse + +Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled. + +- Access: read-only, no consent. +- Feature: `warehouse`. +- Request: `GET /v2/projects/{ref}/warehouse/tables/{table_id}` (`v2-get-warehouse-table`), success 200 json. +- Positional argument ``, bound to path parameter `table_id`. + +## `supabase warehouse tables list` + +List tables replicated to Warehouse + +Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up. + +- Access: read-only, no consent. +- Feature: `warehouse`. +- Request: `GET /v2/projects/{ref}/warehouse/tables` (`v2-list-warehouse-tables`), success 200 json. + ## `supabase warehouse teardowns get` Get Warehouse cleanup status diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index 2da968df4a..4cbcade337 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -843,7 +843,7 @@ export const apiCommandSchemas = { properties: { apply_lag: { description: - "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", properties: { active: { type: "boolean", @@ -852,6 +852,11 @@ export const apiCommandSchemas = { minimum: 0, type: ["number", "null"], }, + flush_lag_bytes: { + maximum: 9007199254740991, + minimum: 0, + type: ["integer", "null"], + }, flush_lag_ms: { minimum: 0, type: ["number", "null"], @@ -868,6 +873,7 @@ export const apiCommandSchemas = { required: [ "active", "feedback_age_ms", + "flush_lag_bytes", "flush_lag_ms", "wal_status", "write_lag_ms", @@ -952,7 +958,7 @@ export const apiCommandSchemas = { }, sync_lag: { description: - "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", properties: { active: { type: "boolean", @@ -961,6 +967,11 @@ export const apiCommandSchemas = { minimum: 0, type: ["number", "null"], }, + flush_lag_bytes: { + maximum: 9007199254740991, + minimum: 0, + type: ["integer", "null"], + }, flush_lag_ms: { minimum: 0, type: ["number", "null"], @@ -984,6 +995,7 @@ export const apiCommandSchemas = { required: [ "active", "feedback_age_ms", + "flush_lag_bytes", "flush_lag_ms", "wal_status", "write_lag_ms", @@ -1062,6 +1074,133 @@ export const apiCommandSchemas = { type: "object", }, }, + "v2-get-warehouse-table": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + lag_ms: { + description: + "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", + minimum: 0, + type: ["number", "null"], + }, + name: { + description: "Source PostgreSQL table name.", + type: "string", + }, + observed_at: { + description: + "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: ["string", "null"], + }, + replication_feedback: { + description: + "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", + properties: { + active: { + type: "boolean", + }, + feedback_age_ms: { + minimum: 0, + type: ["number", "null"], + }, + flush_lag_bytes: { + maximum: 9007199254740991, + minimum: 0, + type: ["integer", "null"], + }, + flush_lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + source: { + description: + "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", + enum: ["pipeline_apply", "table_sync"], + type: "string", + }, + wal_status: { + enum: ["extended", "lost", null, "reserved", "unknown", "unreserved"], + type: ["string", "null"], + }, + write_lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + }, + required: [ + "active", + "feedback_age_ms", + "flush_lag_bytes", + "flush_lag_ms", + "source", + "wal_status", + "write_lag_ms", + ], + type: ["object", "null"], + }, + replication_state: { + description: + "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", + enum: ["copied_table", "copying_table", "error", "following_wal", null, "queued"], + type: ["string", "null"], + }, + schema: { + description: "Source PostgreSQL schema of the table.", + type: "string", + }, + status: { + description: + "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", + enum: ["error", "live", "stopped", "syncing", "unknown"], + type: "string", + }, + warehouse_name: { + description: + "Quoted, fully qualified name of the replicated table in the Warehouse.", + type: "string", + }, + }, + required: [ + "lag_ms", + "name", + "observed_at", + "replication_feedback", + "replication_state", + "schema", + "status", + "warehouse_name", + ], + type: "object", + }, + id: { + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + maxLength: 10, + pattern: "^[1-9]\\d*$", + type: "string", + examples: ["16385"], + }, + type: { + description: "Resource type.", + enum: ["warehouse_table"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-get-warehouse-teardown": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", @@ -1114,4 +1253,142 @@ export const apiCommandSchemas = { required: ["data"], }, }, + "v2-list-warehouse-tables": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + items: { + properties: { + attributes: { + properties: { + lag_ms: { + description: + "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", + minimum: 0, + type: ["number", "null"], + }, + name: { + description: "Source PostgreSQL table name.", + type: "string", + }, + observed_at: { + description: + "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: ["string", "null"], + }, + replication_feedback: { + description: + "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", + properties: { + active: { + type: "boolean", + }, + feedback_age_ms: { + minimum: 0, + type: ["number", "null"], + }, + flush_lag_bytes: { + maximum: 9007199254740991, + minimum: 0, + type: ["integer", "null"], + }, + flush_lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + source: { + description: + "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", + enum: ["pipeline_apply", "table_sync"], + type: "string", + }, + wal_status: { + enum: ["extended", "lost", null, "reserved", "unknown", "unreserved"], + type: ["string", "null"], + }, + write_lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + }, + required: [ + "active", + "feedback_age_ms", + "flush_lag_bytes", + "flush_lag_ms", + "source", + "wal_status", + "write_lag_ms", + ], + type: ["object", "null"], + }, + replication_state: { + description: + "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", + enum: [ + "copied_table", + "copying_table", + "error", + "following_wal", + null, + "queued", + ], + type: ["string", "null"], + }, + schema: { + description: "Source PostgreSQL schema of the table.", + type: "string", + }, + status: { + description: + "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", + enum: ["error", "live", "stopped", "syncing", "unknown"], + type: "string", + }, + warehouse_name: { + description: + "Quoted, fully qualified name of the replicated table in the Warehouse.", + type: "string", + }, + }, + required: [ + "lag_ms", + "name", + "observed_at", + "replication_feedback", + "replication_state", + "schema", + "status", + "warehouse_name", + ], + type: "object", + }, + id: { + description: + "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + maxLength: 10, + pattern: "^[1-9]\\d*$", + type: "string", + examples: ["16385"], + }, + type: { + description: "Resource type.", + enum: ["warehouse_table"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + type: "array", + }, + }, + required: ["data"], + type: "object", + }, + }, } as const satisfies Readonly>; diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index dd7c0ea679..d6b37b1b13 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -214,6 +214,64 @@ export const apiCommands = [ }, ], }, + { + command: ["warehouse", "tables", "get"], + operationId: "v2-get-warehouse-table", + definition: "v2GetWarehouseTable", + method: "GET", + apiPath: "/v2/projects/{ref}/warehouse/tables/{table_id}", + summary: "Get a table replicated to Warehouse", + description: + "Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled.", + readOnly: true, + feature: "warehouse", + response: { + status: 200, + kind: "json", + }, + argument: { + name: "table-id", + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + }, + flags: [], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "path", + name: "table_id", + source: "argument", + argument: "table-id", + }, + ], + }, + { + command: ["warehouse", "tables", "list"], + operationId: "v2-list-warehouse-tables", + definition: "v2ListWarehouseTables", + method: "GET", + apiPath: "/v2/projects/{ref}/warehouse/tables", + summary: "List tables replicated to Warehouse", + description: + "Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up.", + readOnly: true, + feature: "warehouse", + response: { + status: 200, + kind: "json", + }, + flags: [], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + ], + }, { command: ["warehouse", "teardowns", "get"], operationId: "v2-get-warehouse-teardown", diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 8626bc69ab..d36f9c98c3 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -441,7 +441,7 @@ "replication": { "properties": { "apply_lag": { - "description": "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "description": "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", "nullable": true, "properties": { "active": { @@ -452,6 +452,12 @@ "nullable": true, "type": "number" }, + "flush_lag_bytes": { + "maximum": 9007199254740991, + "minimum": 0, + "nullable": true, + "type": "integer" + }, "flush_lag_ms": { "minimum": 0, "nullable": true, @@ -471,6 +477,7 @@ "required": [ "active", "feedback_age_ms", + "flush_lag_bytes", "flush_lag_ms", "wal_status", "write_lag_ms" @@ -555,7 +562,7 @@ "type": "string" }, "sync_lag": { - "description": "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "description": "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", "nullable": true, "properties": { "active": { @@ -566,6 +573,12 @@ "nullable": true, "type": "number" }, + "flush_lag_bytes": { + "maximum": 9007199254740991, + "minimum": 0, + "nullable": true, + "type": "integer" + }, "flush_lag_ms": { "minimum": 0, "nullable": true, @@ -592,6 +605,7 @@ "required": [ "active", "feedback_age_ms", + "flush_lag_bytes", "flush_lag_ms", "wal_status", "write_lag_ms" @@ -943,6 +957,521 @@ }, "$comment": "The Warehouse Flight SQL connection contract is not yet in the deployed Management API specification." }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1tables", + "value": { + "get": { + "description": "Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-list-warehouse-tables", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTablesResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse DuckLake destination not found" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature, project metadata or table selection unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "List tables replicated to Warehouse", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.tables", + "method": "list" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The Warehouse tables listing contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseTablesResponse_Output", + "value": { + "properties": { + "data": { + "items": { + "properties": { + "attributes": { + "properties": { + "lag_ms": { + "description": "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", + "minimum": 0, + "nullable": true, + "type": "number" + }, + "name": { + "description": "Source PostgreSQL table name.", + "type": "string" + }, + "observed_at": { + "description": "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "replication_feedback": { + "description": "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", + "nullable": true, + "properties": { + "active": { + "type": "boolean" + }, + "feedback_age_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "flush_lag_bytes": { + "maximum": 9007199254740991, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "flush_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "source": { + "description": "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", + "enum": ["pipeline_apply", "table_sync"], + "type": "string" + }, + "wal_status": { + "enum": ["extended", "lost", null, "reserved", "unknown", "unreserved"], + "nullable": true, + "type": "string" + }, + "write_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + } + }, + "required": [ + "active", + "feedback_age_ms", + "flush_lag_bytes", + "flush_lag_ms", + "source", + "wal_status", + "write_lag_ms" + ], + "type": "object" + }, + "replication_state": { + "description": "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", + "enum": [ + "copied_table", + "copying_table", + "error", + "following_wal", + null, + "queued" + ], + "nullable": true, + "type": "string" + }, + "schema": { + "description": "Source PostgreSQL schema of the table.", + "type": "string" + }, + "status": { + "description": "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", + "enum": ["error", "live", "stopped", "syncing", "unknown"], + "type": "string" + }, + "warehouse_name": { + "description": "Quoted, fully qualified name of the replicated table in the Warehouse.", + "type": "string" + } + }, + "required": [ + "lag_ms", + "name", + "observed_at", + "replication_feedback", + "replication_state", + "schema", + "status", + "warehouse_name" + ], + "type": "object" + }, + "id": { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse tables listing contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1tables~1{table_id}", + "value": { + "get": { + "description": "Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-table", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "in": "path", + "name": "table_id", + "required": true, + "schema": { + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTableResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Table not replicated to Warehouse, or Warehouse DuckLake destination not found" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature, project metadata or table selection unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get a table replicated to Warehouse", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.tables", + "method": "get" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The Warehouse table inspection contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseTableResponse_Output", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "lag_ms": { + "description": "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", + "minimum": 0, + "nullable": true, + "type": "number" + }, + "name": { + "description": "Source PostgreSQL table name.", + "type": "string" + }, + "observed_at": { + "description": "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "replication_feedback": { + "description": "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", + "nullable": true, + "properties": { + "active": { + "type": "boolean" + }, + "feedback_age_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "flush_lag_bytes": { + "maximum": 9007199254740991, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "flush_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "source": { + "description": "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", + "enum": ["pipeline_apply", "table_sync"], + "type": "string" + }, + "wal_status": { + "enum": ["extended", "lost", null, "reserved", "unknown", "unreserved"], + "nullable": true, + "type": "string" + }, + "write_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + } + }, + "required": [ + "active", + "feedback_age_ms", + "flush_lag_bytes", + "flush_lag_ms", + "source", + "wal_status", + "write_lag_ms" + ], + "type": "object" + }, + "replication_state": { + "description": "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", + "enum": [ + "copied_table", + "copying_table", + "error", + "following_wal", + null, + "queued" + ], + "nullable": true, + "type": "string" + }, + "schema": { + "description": "Source PostgreSQL schema of the table.", + "type": "string" + }, + "status": { + "description": "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", + "enum": ["error", "live", "stopped", "syncing", "unknown"], + "type": "string" + }, + "warehouse_name": { + "description": "Quoted, fully qualified name of the replicated table in the Warehouse.", + "type": "string" + } + }, + "required": [ + "lag_ms", + "name", + "observed_at", + "replication_feedback", + "replication_state", + "schema", + "status", + "warehouse_name" + ], + "type": "object" + }, + "id": { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse table inspection contract is not yet in the deployed Management API specification." + }, { "op": "test", "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1setups~1current/get/x-operation", diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index d010fc3ebf..b5a6a4c5c8 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -14824,6 +14824,20 @@ export const V2GetWarehouseStatusOutput = Schema.Struct({ ), Schema.Null, ]), + flush_lag_bytes: Schema.Union([ + Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + Schema.Null, + ]), flush_lag_ms: Schema.Union([ Schema.Number.check( Schema.isFinite().annotate({ expected: "a finite number" }), @@ -14853,7 +14867,7 @@ export const V2GetWarehouseStatusOutput = Schema.Struct({ ]), }).annotate({ description: - "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", }), Schema.Null, ]), @@ -14944,6 +14958,20 @@ export const V2GetWarehouseStatusOutput = Schema.Struct({ ), Schema.Null, ]), + flush_lag_bytes: Schema.Union([ + Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + Schema.Null, + ]), flush_lag_ms: Schema.Union([ Schema.Number.check( Schema.isFinite().annotate({ expected: "a finite number" }), @@ -14973,7 +15001,7 @@ export const V2GetWarehouseStatusOutput = Schema.Struct({ ]), }).annotate({ description: - "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", }), Schema.Null, ]), @@ -15021,6 +15049,148 @@ export const V2GetWarehouseStatusOutput = Schema.Struct({ type: Schema.Literal("warehouse_context").annotate({ description: "Resource type." }), }), }); +export const V2GetWarehouseTableInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + table_id: Schema.String.check( + Schema.isMaxCodePoints(10).annotate({ expected: "a string with at most 10 code points" }), + ).check( + Schema.isPattern(new RegExp("^[1-9]\\d*$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*$", + }), + ), +}); +export const V2GetWarehouseTableOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + lag_ms: Schema.Union([ + Schema.Number.annotate({ + description: + "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", + }) + .check(Schema.isFinite().annotate({ expected: "a finite number" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + name: Schema.String.annotate({ description: "Source PostgreSQL table name." }), + observed_at: Schema.Union([ + Schema.String.annotate({ + description: + "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", + format: "date-time", + }), + Schema.Null, + ]), + replication_feedback: Schema.Union([ + Schema.Struct({ + active: Schema.Boolean, + feedback_age_ms: Schema.Union([ + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + flush_lag_bytes: Schema.Union([ + Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + Schema.Null, + ]), + flush_lag_ms: Schema.Union([ + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + source: Schema.Union([ + Schema.Literals(["pipeline_apply", "table_sync"]).annotate({ + description: + "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", + }), + OpenString, + ]), + wal_status: Schema.Union([ + Schema.Union([ + Schema.Literals(["extended", "lost", "reserved", "unknown", "unreserved"]), + Schema.Null, + ]), + OpenString, + ]), + write_lag_ms: Schema.Union([ + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + }).annotate({ + description: + "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", + }), + Schema.Null, + ]), + replication_state: Schema.Union([ + Schema.Union([ + Schema.Literals(["copied_table", "copying_table", "error", "following_wal", "queued"]), + Schema.Null, + ]).annotate({ + description: + "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", + }), + OpenString, + ]), + schema: Schema.String.annotate({ description: "Source PostgreSQL schema of the table." }), + status: Schema.Union([ + Schema.Literals(["error", "live", "stopped", "syncing", "unknown"]).annotate({ + description: + "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", + }), + OpenString, + ]), + warehouse_name: Schema.String.annotate({ + description: "Quoted, fully qualified name of the replicated table in the Warehouse.", + }), + }), + id: Schema.String.annotate({ + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + }) + .check( + Schema.isMaxCodePoints(10).annotate({ expected: "a string with at most 10 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[1-9]\\d*$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*$", + }), + ), + type: Schema.Literal("warehouse_table").annotate({ description: "Resource type." }), + }), +}); export const V2GetWarehouseTeardownInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -16072,6 +16242,149 @@ export const V2ListPrivateLinkAssociationsOutput = Schema.Struct({ }), ), }); +export const V2ListWarehouseTablesInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), +}); +export const V2ListWarehouseTablesOutput = Schema.Struct({ + data: Schema.Array( + Schema.Struct({ + attributes: Schema.Struct({ + lag_ms: Schema.Union([ + Schema.Number.annotate({ + description: + "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", + }) + .check(Schema.isFinite().annotate({ expected: "a finite number" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + name: Schema.String.annotate({ description: "Source PostgreSQL table name." }), + observed_at: Schema.Union([ + Schema.String.annotate({ + description: + "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", + format: "date-time", + }), + Schema.Null, + ]), + replication_feedback: Schema.Union([ + Schema.Struct({ + active: Schema.Boolean, + feedback_age_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + flush_lag_bytes: Schema.Union([ + Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + Schema.Null, + ]), + flush_lag_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + source: Schema.Union([ + Schema.Literals(["pipeline_apply", "table_sync"]).annotate({ + description: + "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", + }), + OpenString, + ]), + wal_status: Schema.Union([ + Schema.Union([ + Schema.Literals(["extended", "lost", "reserved", "unknown", "unreserved"]), + Schema.Null, + ]), + OpenString, + ]), + write_lag_ms: Schema.Union([ + Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + }).annotate({ + description: + "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", + }), + Schema.Null, + ]), + replication_state: Schema.Union([ + Schema.Union([ + Schema.Literals(["copied_table", "copying_table", "error", "following_wal", "queued"]), + Schema.Null, + ]).annotate({ + description: + "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", + }), + OpenString, + ]), + schema: Schema.String.annotate({ description: "Source PostgreSQL schema of the table." }), + status: Schema.Union([ + Schema.Literals(["error", "live", "stopped", "syncing", "unknown"]).annotate({ + description: + "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", + }), + OpenString, + ]), + warehouse_name: Schema.String.annotate({ + description: "Quoted, fully qualified name of the replicated table in the Warehouse.", + }), + }), + id: Schema.String.annotate({ + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + }) + .check( + Schema.isMaxCodePoints(10).annotate({ expected: "a string with at most 10 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[1-9]\\d*$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*$", + }), + ), + type: Schema.Literal("warehouse_table").annotate({ description: "Resource type." }), + }), + ), +}); export const V2OrganizationsSlugWebhooksDeliveriesIdGetInput = Schema.Struct({ slug: Schema.String.check( Schema.isPattern(new RegExp("^[\\w-]+$", "u")).annotate({ @@ -20084,6 +20397,7 @@ export const openApiOperationIdMap = { "v2-get-warehouse-connection": "v2GetWarehouseConnection", "v2-get-warehouse-setup": "v2GetWarehouseSetup", "v2-get-warehouse-status": "v2GetWarehouseStatus", + "v2-get-warehouse-table": "v2GetWarehouseTable", "v2-get-warehouse-teardown": "v2GetWarehouseTeardown", "v2-list-all-compute-instances": "v2ListAllComputeInstances", "v2-list-log-drains": "v2ListLogDrains", @@ -20094,6 +20408,7 @@ export const openApiOperationIdMap = { "v2-list-organization-projects": "v2ListOrganizationProjects", "v2-list-organization-roles": "v2ListOrganizationRoles", "v2-list-private-link-associations": "v2ListPrivateLinkAssociations", + "v2-list-warehouse-tables": "v2ListWarehouseTables", "v2-organizations-slug-webhooks-deliveries-id-get": "v2OrganizationsSlugWebhooksDeliveriesIdGet", "v2-organizations-slug-webhooks-deliveries-id-retry-post": "v2OrganizationsSlugWebhooksDeliveriesIdRetryPost", @@ -23299,6 +23614,20 @@ export const operationDefinitions = { inputSchema: V2GetWarehouseStatusInput, outputSchema: V2GetWarehouseStatusOutput, }, + v2GetWarehouseTable: { + id: "v2GetWarehouseTable", + description: + "Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/tables/{table_id}", + pathParams: ["ref", "table_id"], + queryParams: [], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2GetWarehouseTableInput, + outputSchema: V2GetWarehouseTableOutput, + }, v2GetWarehouseTeardown: { id: "v2GetWarehouseTeardown", description: @@ -23436,6 +23765,20 @@ export const operationDefinitions = { inputSchema: V2ListPrivateLinkAssociationsInput, outputSchema: V2ListPrivateLinkAssociationsOutput, }, + v2ListWarehouseTables: { + id: "v2ListWarehouseTables", + description: + "Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/tables", + pathParams: ["ref"], + queryParams: [], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2ListWarehouseTablesInput, + outputSchema: V2ListWarehouseTablesOutput, + }, v2OrganizationsSlugWebhooksDeliveriesIdGet: { id: "v2OrganizationsSlugWebhooksDeliveriesIdGet", description: "Get details of a specific delivery attempt.", diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index a50f091773..dfcad4c47e 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -3140,6 +3140,22 @@ export const versionedEffectOperations = { options, ); }), + getWarehouseTable: ( + input: typeof operationDefinitions.v2GetWarehouseTable.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2GetWarehouseTable.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2GetWarehouseTable">( + operationDefinitions.v2GetWarehouseTable, + input, + options, + ); + }), getWarehouseTeardown: ( input: typeof operationDefinitions.v2GetWarehouseTeardown.inputSchema.Type, options?: SupabaseApiRequestOptions, @@ -3300,6 +3316,22 @@ export const versionedEffectOperations = { options, ); }), + listWarehouseTables: ( + input: typeof operationDefinitions.v2ListWarehouseTables.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2ListWarehouseTables.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2ListWarehouseTables">( + operationDefinitions.v2ListWarehouseTables, + input, + options, + ); + }), organizationsSlugWebhooksDeliveriesIdGet: ( input: typeof operationDefinitions.v2OrganizationsSlugWebhooksDeliveriesIdGet.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index e9dd2b2d2a..a47c989ec1 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -32858,6 +32858,234 @@ }, "x-scalar-stability": "experimental" } + }, + "/v2/projects/{ref}/warehouse/tables": { + "get": { + "description": "Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-list-warehouse-tables", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTablesResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse DuckLake destination not found" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature, project metadata or table selection unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "List tables replicated to Warehouse", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.tables", + "method": "list" + }, + "x-scalar-stability": "experimental" + } + }, + "/v2/projects/{ref}/warehouse/tables/{table_id}": { + "get": { + "description": "Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-table", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "in": "path", + "name": "table_id", + "required": true, + "schema": { + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTableResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Table not replicated to Warehouse, or Warehouse DuckLake destination not found" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature, project metadata or table selection unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get a table replicated to Warehouse", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.tables", + "method": "get" + }, + "x-scalar-stability": "experimental" + } } }, "components": { @@ -48390,7 +48618,7 @@ "replication": { "properties": { "apply_lag": { - "description": "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "description": "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", "nullable": true, "properties": { "active": { @@ -48401,6 +48629,12 @@ "nullable": true, "type": "number" }, + "flush_lag_bytes": { + "maximum": 9007199254740991, + "minimum": 0, + "nullable": true, + "type": "integer" + }, "flush_lag_ms": { "minimum": 0, "nullable": true, @@ -48420,6 +48654,7 @@ "required": [ "active", "feedback_age_ms", + "flush_lag_bytes", "flush_lag_ms", "wal_status", "write_lag_ms" @@ -48504,7 +48739,7 @@ "type": "string" }, "sync_lag": { - "description": "Postgres replication feedback. Null means unknown. Feedback age measures time since the last response and does not establish how current query results are.", + "description": "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", "nullable": true, "properties": { "active": { @@ -48515,6 +48750,12 @@ "nullable": true, "type": "number" }, + "flush_lag_bytes": { + "maximum": 9007199254740991, + "minimum": 0, + "nullable": true, + "type": "integer" + }, "flush_lag_ms": { "minimum": 0, "nullable": true, @@ -48541,6 +48782,7 @@ "required": [ "active", "feedback_age_ms", + "flush_lag_bytes", "flush_lag_ms", "wal_status", "write_lag_ms" @@ -48781,6 +49023,273 @@ }, "required": ["data"], "type": "object" + }, + "V2WarehouseTablesResponse_Output": { + "properties": { + "data": { + "items": { + "properties": { + "attributes": { + "properties": { + "lag_ms": { + "description": "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", + "minimum": 0, + "nullable": true, + "type": "number" + }, + "name": { + "description": "Source PostgreSQL table name.", + "type": "string" + }, + "observed_at": { + "description": "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "replication_feedback": { + "description": "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", + "nullable": true, + "properties": { + "active": { + "type": "boolean" + }, + "feedback_age_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "flush_lag_bytes": { + "maximum": 9007199254740991, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "flush_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "source": { + "description": "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", + "enum": ["pipeline_apply", "table_sync"], + "type": "string" + }, + "wal_status": { + "enum": ["extended", "lost", null, "reserved", "unknown", "unreserved"], + "nullable": true, + "type": "string" + }, + "write_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + } + }, + "required": [ + "active", + "feedback_age_ms", + "flush_lag_bytes", + "flush_lag_ms", + "source", + "wal_status", + "write_lag_ms" + ], + "type": "object" + }, + "replication_state": { + "description": "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", + "enum": [ + "copied_table", + "copying_table", + "error", + "following_wal", + null, + "queued" + ], + "nullable": true, + "type": "string" + }, + "schema": { + "description": "Source PostgreSQL schema of the table.", + "type": "string" + }, + "status": { + "description": "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", + "enum": ["error", "live", "stopped", "syncing", "unknown"], + "type": "string" + }, + "warehouse_name": { + "description": "Quoted, fully qualified name of the replicated table in the Warehouse.", + "type": "string" + } + }, + "required": [ + "lag_ms", + "name", + "observed_at", + "replication_feedback", + "replication_state", + "schema", + "status", + "warehouse_name" + ], + "type": "object" + }, + "id": { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["data"], + "type": "object" + }, + "V2WarehouseTableResponse_Output": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "lag_ms": { + "description": "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", + "minimum": 0, + "nullable": true, + "type": "number" + }, + "name": { + "description": "Source PostgreSQL table name.", + "type": "string" + }, + "observed_at": { + "description": "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", + "format": "date-time", + "nullable": true, + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "replication_feedback": { + "description": "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", + "nullable": true, + "properties": { + "active": { + "type": "boolean" + }, + "feedback_age_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "flush_lag_bytes": { + "maximum": 9007199254740991, + "minimum": 0, + "nullable": true, + "type": "integer" + }, + "flush_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "source": { + "description": "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", + "enum": ["pipeline_apply", "table_sync"], + "type": "string" + }, + "wal_status": { + "enum": ["extended", "lost", null, "reserved", "unknown", "unreserved"], + "nullable": true, + "type": "string" + }, + "write_lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + } + }, + "required": [ + "active", + "feedback_age_ms", + "flush_lag_bytes", + "flush_lag_ms", + "source", + "wal_status", + "write_lag_ms" + ], + "type": "object" + }, + "replication_state": { + "description": "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", + "enum": [ + "copied_table", + "copying_table", + "error", + "following_wal", + null, + "queued" + ], + "nullable": true, + "type": "string" + }, + "schema": { + "description": "Source PostgreSQL schema of the table.", + "type": "string" + }, + "status": { + "description": "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", + "enum": ["error", "live", "stopped", "syncing", "unknown"], + "type": "string" + }, + "warehouse_name": { + "description": "Quoted, fully qualified name of the replicated table in the Warehouse.", + "type": "string" + } + }, + "required": [ + "lag_ms", + "name", + "observed_at", + "replication_feedback", + "replication_state", + "schema", + "status", + "warehouse_name" + ], + "type": "object" + }, + "id": { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index 413ac5c910..d074d62edf 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -450,4 +450,6 @@ export const operationPermissions: Readonly "v2-organizations-slug-webhooks-deliveries-id-retry-post": { fga: [] }, "v2-get-warehouse-status": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-get-warehouse-connection": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-list-warehouse-tables": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-get-warehouse-table": { fga: [["database_read"]], oauthScope: "database:read" }, }; From b21f084a27bcffa957565711b6ab3aca5f69af1f Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Wed, 18 Nov 2026 17:14:57 +0100 Subject: [PATCH 20/45] feat(cli): add warehouse tables layout get (#7690) Generate `warehouse tables layout get ` from `GET /v2/projects/{ref}/warehouse/tables/{table_id}/layout`. It reads one replicated table by the source OID that `warehouse tables list` shows, and reports two layouts side by side: - `desired`: the saved sorting and partitioning rules, where null means unmanaged and `{ "kind": "none" }` or `[]` is an explicit clear; - `observed`: the sort expressions and partition keys the DuckLake catalog records, with the time they were read and an `observation_status` of `observed`, `table_missing` or `unavailable`. The two can differ until the replicator applies saved rules, and a catalog layout does not establish that existing files are sorted or partitioned. Text output shows both as nested tables. A table that isn't replicated is an API error. `sort_by` is the first nullable `oneOf` in the specification. The API client generator now adds `null` to a nullable `oneOf` as it already did for `anyOf`, so the typed client accepts a table with unmanaged sorting. The bindings test's schema fingerprint also reads a `null` union branch as a nullable type. The layout contract comes from OpenAPI overrides until it ships in the deployed Management API specification. Stacked on #7640, after #7689. Depends on https://github.com/supabase/platform/pull/42055 and https://github.com/supabase/platform/pull/42126. Implements PIPE-1455. --- .../command-surface.integration.test.ts | 2 + .../api-command-bindings.integration.test.ts | 10 +- .../src/commands/api/api-command-policy.ts | 2 + .../api/api-commands.integration.test.ts | 40 ++ apps/cli/src/commands/api/generated.md | 11 + .../cli/src/commands/api/generated.schemas.ts | 258 ++++++++++++ apps/cli/src/commands/api/generated.ts | 34 ++ packages/api/scripts/generate.ts | 13 +- packages/api/scripts/generate.unit.test.ts | 9 + packages/api/scripts/openapi-overrides.json | 374 ++++++++++++++++++ packages/api/src/generated/contracts.ts | 154 ++++++++ packages/api/src/generated/effect-client.ts | 16 + packages/api/src/generated/openapi.json | 364 +++++++++++++++++ packages/api/src/generated/permissions.ts | 1 + 14 files changed, 1280 insertions(+), 8 deletions(-) diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 052b2a00c3..394a10f8d8 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -60,6 +60,8 @@ describe("command surface", () => { "warehouse status", "warehouse tables", "warehouse tables get", + "warehouse tables layout", + "warehouse tables layout get", "warehouse tables list", "warehouse teardowns", "warehouse teardowns get", diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 40165faa4b..224bae2207 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -81,13 +81,19 @@ const operationOf = (operationId: string): SpecOperation => { throw new Error(`${operationId} is not in openapi.json`); }; -/** The JSON Schema types of a node, with OpenAPI 3.0 `nullable` folded in as a `null` type. */ +/** + * The JSON Schema types of a node, with OpenAPI 3.0 `nullable` and a `null` union branch folded in + * as a `null` type. + */ const typesOf = (node: Json): ReadonlyArray => { const declared = node["type"]; const types = (Array.isArray(declared) ? declared : declared === undefined ? [] : [declared]).map( String, ); - return (node["nullable"] === true ? [...types, "null"] : types) + const nullable = + node["nullable"] === true || + asList(node["anyOf"]).some((branch) => asRecord(branch)["type"] === "null"); + return (nullable ? [...types, "null"] : types) .filter((type, index, all) => all.indexOf(type) === index) .toSorted((a, b) => a.localeCompare(b)); }; diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 9d00ea8806..dfb73fa48e 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -38,6 +38,7 @@ export const generatedOperations: ReadonlyArray = [ "v2-get-warehouse-teardown", "v2-list-warehouse-tables", "v2-get-warehouse-table", + "v2-get-warehouse-table-layout", ]; export const nouns = { @@ -46,6 +47,7 @@ export const nouns = { feature: "warehouse", groups: { tables: "Inspect tables replicated to Warehouse", + "tables.layout": "Inspect the layout of tables replicated to Warehouse", teardowns: "Inspect Warehouse cleanup operations", }, }, diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 2386d39f88..4d9740021a 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -480,6 +480,46 @@ describe("generated warehouse commands", () => { }, ); }); + describe("warehouse tables layout get", () => { + const layoutPath = `/v2/projects/${VALID_REF}/warehouse/tables/16385/layout`; + const body = { + data: { + id: "16385", + type: "warehouse_table_layout", + attributes: { + schema: "public", + name: "events", + desired: { + sort_by: null, + partition_by: [{ column: "account_id", transform: { kind: "bucket", count: 16 } }], + }, + observation_status: "observed", + observed: { + sort_by: [{ expression: '"created_at"', direction: "DESC", nulls: "NULLS_LAST" }], + partition_by: [{ column: "account_id", transform: "bucket(16)" }], + observed_at: "2026-11-18T09:30:00.123456Z", + }, + }, + }, + }; + + it.effect("renders unmanaged desired sorting beside the observed catalog layout", () => { + const { out, sent, run } = setup(["warehouse", "tables", "layout", "get", "16385"], { + route: ok(body), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([{ method: "GET", path: layoutPath, search: "", body: undefined }]); + expect(out.stdoutText).toMatch(/^Warehouse table layout\n/); + expect(out.stdoutText).toMatch(/Desired\n\s+Sort by\s+-\n/); + expect(out.stdoutText).toMatch(/account_id \| \{"kind":"bucket","count":16\}/); + expect(out.stdoutText).toMatch(/Observation status\s+observed/); + expect(out.stdoutText).toMatch(/account_id \| bucket\(16\)/); + expect(out.stdoutText).toMatch(/Observed at\s+2026-11-18T09:30:00\.123456Z/); + }); + }); + }); describe("warehouse connection", () => { const connectionPath = `/v2/projects/${VALID_REF}/warehouse/connection`; const host = `${VALID_REF}.warehouse.example.invalid`; diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index 9a1bb54ab3..e010aa47b3 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -88,6 +88,17 @@ Returns one source table selected for Warehouse replication by its source OID, f - Request: `GET /v2/projects/{ref}/warehouse/tables/{table_id}` (`v2-get-warehouse-table`), success 200 json. - Positional argument ``, bound to path parameter `table_id`. +## `supabase warehouse tables layout get` + +Get the layout of a table replicated to Warehouse + +Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up. + +- Access: read-only, no consent. +- Feature: `warehouse`. +- Request: `GET /v2/projects/{ref}/warehouse/tables/{table_id}/layout` (`v2-get-warehouse-table-layout`), success 200 json. +- Positional argument ``, bound to path parameter `table_id`. + ## `supabase warehouse tables list` List tables replicated to Warehouse diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index 4cbcade337..334a34bed9 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -1201,6 +1201,264 @@ export const apiCommandSchemas = { type: "object", }, }, + "v2-get-warehouse-table-layout": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + desired: { + description: + "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", + properties: { + partition_by: { + description: + "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", + items: { + properties: { + column: { + description: "Source column name.", + type: "string", + }, + transform: { + oneOf: [ + { + properties: { + kind: { + enum: ["identity"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["year"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["month"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["day"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["hour"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + count: { + description: "Number of hash buckets.", + maximum: 2147483647, + type: "integer", + exclusiveMinimum: 0, + }, + kind: { + enum: ["bucket"], + type: "string", + }, + }, + required: ["count", "kind"], + type: "object", + }, + ], + }, + }, + required: ["column", "transform"], + type: "object", + }, + type: ["array", "null"], + }, + sort_by: { + anyOf: [ + { + description: + "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + oneOf: [ + { + properties: { + kind: { + enum: ["none"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["primary_key"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + columns: { + items: { + properties: { + direction: { + enum: ["asc", "desc"], + type: "string", + }, + name: { + description: "Source column name.", + type: "string", + }, + nulls: { + description: + "Null placement. Null uses DuckLake's default placement.", + enum: ["first", "last", null], + type: ["string", "null"], + }, + }, + required: ["direction", "name", "nulls"], + type: "object", + }, + type: "array", + }, + kind: { + enum: ["columns"], + type: "string", + }, + }, + required: ["columns", "kind"], + type: "object", + }, + ], + }, + { + type: "null", + }, + ], + }, + }, + required: ["partition_by", "sort_by"], + type: "object", + }, + name: { + description: "Source PostgreSQL table name.", + type: "string", + }, + observation_status: { + description: + "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, and unavailable when the catalog could not be read.", + enum: ["observed", "table_missing", "unavailable"], + type: "string", + }, + observed: { + description: + "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", + properties: { + observed_at: { + description: "Time the catalog metadata was read.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: "string", + }, + partition_by: { + description: + "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", + items: { + properties: { + column: { + type: "string", + }, + transform: { + type: "string", + }, + }, + required: ["column", "transform"], + type: "object", + }, + type: "array", + }, + sort_by: { + description: + "Active sort expressions in key order, as the catalog reports them.", + items: { + properties: { + direction: { + type: "string", + }, + expression: { + type: "string", + }, + nulls: { + type: "string", + }, + }, + required: ["direction", "expression", "nulls"], + type: "object", + }, + type: "array", + }, + }, + required: ["observed_at", "partition_by", "sort_by"], + type: ["object", "null"], + }, + schema: { + description: "Source PostgreSQL schema of the table.", + type: "string", + }, + }, + required: ["desired", "name", "observation_status", "observed", "schema"], + type: "object", + }, + id: { + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + maxLength: 10, + pattern: "^[1-9]\\d*$", + type: "string", + examples: ["16385"], + }, + type: { + description: "Resource type.", + enum: ["warehouse_table_layout"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-get-warehouse-teardown": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index d6b37b1b13..52f0e35045 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -248,6 +248,40 @@ export const apiCommands = [ }, ], }, + { + command: ["warehouse", "tables", "layout", "get"], + operationId: "v2-get-warehouse-table-layout", + definition: "v2GetWarehouseTableLayout", + method: "GET", + apiPath: "/v2/projects/{ref}/warehouse/tables/{table_id}/layout", + summary: "Get the layout of a table replicated to Warehouse", + description: + "Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up.", + readOnly: true, + feature: "warehouse", + response: { + status: 200, + kind: "json", + }, + argument: { + name: "table-id", + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + }, + flags: [], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "path", + name: "table_id", + source: "argument", + argument: "table-id", + }, + ], + }, { command: ["warehouse", "tables", "list"], operationId: "v2-list-warehouse-tables", diff --git a/packages/api/scripts/generate.ts b/packages/api/scripts/generate.ts index db22bc75ba..8678ee9534 100644 --- a/packages/api/scripts/generate.ts +++ b/packages/api/scripts/generate.ts @@ -332,14 +332,15 @@ export function sanitizeOpenApiSchema( delete sanitized.pattern; } - if ( - sanitized.nullable === true && - sanitized.type === undefined && - Array.isArray(sanitized.anyOf) - ) { + const union = Array.isArray(sanitized.anyOf) + ? "anyOf" + : Array.isArray(sanitized.oneOf) + ? "oneOf" + : undefined; + if (sanitized.nullable === true && sanitized.type === undefined && union !== undefined) { const normalized = { ...sanitized, - anyOf: [...sanitized.anyOf, { type: "null" }], + [union]: [...(sanitized[union] ?? []), { type: "null" }], }; delete normalized.nullable; return normalized; diff --git a/packages/api/scripts/generate.unit.test.ts b/packages/api/scripts/generate.unit.test.ts index 278fd316a5..6e361ec65f 100644 --- a/packages/api/scripts/generate.unit.test.ts +++ b/packages/api/scripts/generate.unit.test.ts @@ -275,6 +275,15 @@ describe("generate", () => { ).toBe("Schema.Union([Schema.String, Schema.Finite, Schema.Boolean, Schema.Null])"); }); + test("preserves null in nullable oneOf variants without an explicit type", () => { + expect( + renderOpenApiSchema({ + oneOf: [{ type: "string", enum: ["none"] }, { type: "integer" }], + nullable: true, + }), + ).toBe('Schema.Union([Schema.Literal("none"), Schema.Int, Schema.Null], { mode: "oneOf" })'); + }); + test("accepts booleans for string-encoded boolean query parameters", () => { expect( normalizeQueryParameterSchema( diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index d36f9c98c3..8e26f033d3 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -1472,6 +1472,380 @@ }, "$comment": "The Warehouse table inspection contract is not yet in the deployed Management API specification." }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1tables~1{table_id}~1layout", + "value": { + "get": { + "description": "Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-table-layout", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "in": "path", + "name": "table_id", + "required": true, + "schema": { + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Table not replicated to Warehouse" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature, project metadata or table layout unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get the layout of a table replicated to Warehouse", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.tables.layout", + "method": "get" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The Warehouse table layout contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseTableLayoutResponse_Output", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "desired": { + "description": "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", + "properties": { + "partition_by": { + "description": "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", + "items": { + "properties": { + "column": { + "description": "Source column name.", + "type": "string" + }, + "transform": { + "oneOf": [ + { + "properties": { + "kind": { + "enum": ["identity"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["year"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["month"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["day"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["hour"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "count": { + "description": "Number of hash buckets.", + "exclusiveMinimum": true, + "maximum": 2147483647, + "minimum": 0, + "type": "integer" + }, + "kind": { + "enum": ["bucket"], + "type": "string" + } + }, + "required": ["count", "kind"], + "type": "object" + } + ] + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "nullable": true, + "type": "array" + }, + "sort_by": { + "description": "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + "nullable": true, + "oneOf": [ + { + "properties": { + "kind": { + "enum": ["none"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["primary_key"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "columns": { + "items": { + "properties": { + "direction": { + "enum": ["asc", "desc"], + "type": "string" + }, + "name": { + "description": "Source column name.", + "type": "string" + }, + "nulls": { + "description": "Null placement. Null uses DuckLake's default placement.", + "enum": ["first", "last", null], + "nullable": true, + "type": "string" + } + }, + "required": ["direction", "name", "nulls"], + "type": "object" + }, + "type": "array" + }, + "kind": { + "enum": ["columns"], + "type": "string" + } + }, + "required": ["columns", "kind"], + "type": "object" + } + ] + } + }, + "required": ["partition_by", "sort_by"], + "type": "object" + }, + "name": { + "description": "Source PostgreSQL table name.", + "type": "string" + }, + "observation_status": { + "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, and unavailable when the catalog could not be read.", + "enum": ["observed", "table_missing", "unavailable"], + "type": "string" + }, + "observed": { + "description": "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", + "nullable": true, + "properties": { + "observed_at": { + "description": "Time the catalog metadata was read.", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "partition_by": { + "description": "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", + "items": { + "properties": { + "column": { + "type": "string" + }, + "transform": { + "type": "string" + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "type": "array" + }, + "sort_by": { + "description": "Active sort expressions in key order, as the catalog reports them.", + "items": { + "properties": { + "direction": { + "type": "string" + }, + "expression": { + "type": "string" + }, + "nulls": { + "type": "string" + } + }, + "required": ["direction", "expression", "nulls"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["observed_at", "partition_by", "sort_by"], + "type": "object" + }, + "schema": { + "description": "Source PostgreSQL schema of the table.", + "type": "string" + } + }, + "required": ["desired", "name", "observation_status", "observed", "schema"], + "type": "object" + }, + "id": { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table_layout"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse table layout contract is not yet in the deployed Management API specification." + }, { "op": "test", "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1setups~1current/get/x-operation", diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index b5a6a4c5c8..07acba934a 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -15191,6 +15191,145 @@ export const V2GetWarehouseTableOutput = Schema.Struct({ type: Schema.Literal("warehouse_table").annotate({ description: "Resource type." }), }), }); +export const V2GetWarehouseTableLayoutInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + table_id: Schema.String.check( + Schema.isMaxCodePoints(10).annotate({ expected: "a string with at most 10 code points" }), + ).check( + Schema.isPattern(new RegExp("^[1-9]\\d*$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*$", + }), + ), +}); +export const V2GetWarehouseTableLayoutOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + desired: Schema.Struct({ + partition_by: Schema.Union([ + Schema.Array( + Schema.Struct({ + column: Schema.String.annotate({ description: "Source column name." }), + transform: Schema.Union( + [ + Schema.Struct({ kind: Schema.Literal("identity") }), + Schema.Struct({ kind: Schema.Literal("year") }), + Schema.Struct({ kind: Schema.Literal("month") }), + Schema.Struct({ kind: Schema.Literal("day") }), + Schema.Struct({ kind: Schema.Literal("hour") }), + Schema.Struct({ + count: Schema.Number.annotate({ description: "Number of hash buckets." }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(2147483647).annotate({ + expected: "a value less than or equal to 2147483647", + }), + ) + .check( + Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" }), + ), + kind: Schema.Literal("bucket"), + }), + ], + { mode: "oneOf" }, + ), + }), + ).annotate({ + description: + "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", + }), + Schema.Null, + ]), + sort_by: Schema.Union( + [ + Schema.Struct({ kind: Schema.Literal("none") }), + Schema.Struct({ kind: Schema.Literal("primary_key") }), + Schema.Struct({ + columns: Schema.Array( + Schema.Struct({ + direction: Schema.Union([Schema.Literals(["asc", "desc"]), OpenString]), + name: Schema.String.annotate({ description: "Source column name." }), + nulls: Schema.Union([ + Schema.Union([Schema.Literals(["first", "last"]), Schema.Null]).annotate({ + description: "Null placement. Null uses DuckLake's default placement.", + }), + OpenString, + ]), + }), + ), + kind: Schema.Literal("columns"), + }), + Schema.Null, + ], + { mode: "oneOf" }, + ).annotate({ + description: + "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + }), + }).annotate({ + description: + "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", + }), + name: Schema.String.annotate({ description: "Source PostgreSQL table name." }), + observation_status: Schema.Union([ + Schema.Literals(["observed", "table_missing", "unavailable"]).annotate({ + description: + "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, and unavailable when the catalog could not be read.", + }), + OpenString, + ]), + observed: Schema.Union([ + Schema.Struct({ + observed_at: Schema.String.annotate({ + description: "Time the catalog metadata was read.", + format: "date-time", + }), + partition_by: Schema.Array( + Schema.Struct({ column: Schema.String, transform: Schema.String }), + ).annotate({ + description: + "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", + }), + sort_by: Schema.Array( + Schema.Struct({ + direction: Schema.String, + expression: Schema.String, + nulls: Schema.String, + }), + ).annotate({ + description: "Active sort expressions in key order, as the catalog reports them.", + }), + }).annotate({ + description: + "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", + }), + Schema.Null, + ]), + schema: Schema.String.annotate({ description: "Source PostgreSQL schema of the table." }), + }), + id: Schema.String.annotate({ + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + }) + .check( + Schema.isMaxCodePoints(10).annotate({ expected: "a string with at most 10 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[1-9]\\d*$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*$", + }), + ), + type: Schema.Literal("warehouse_table_layout").annotate({ description: "Resource type." }), + }), +}); export const V2GetWarehouseTeardownInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -20398,6 +20537,7 @@ export const openApiOperationIdMap = { "v2-get-warehouse-setup": "v2GetWarehouseSetup", "v2-get-warehouse-status": "v2GetWarehouseStatus", "v2-get-warehouse-table": "v2GetWarehouseTable", + "v2-get-warehouse-table-layout": "v2GetWarehouseTableLayout", "v2-get-warehouse-teardown": "v2GetWarehouseTeardown", "v2-list-all-compute-instances": "v2ListAllComputeInstances", "v2-list-log-drains": "v2ListLogDrains", @@ -23628,6 +23768,20 @@ export const operationDefinitions = { inputSchema: V2GetWarehouseTableInput, outputSchema: V2GetWarehouseTableOutput, }, + v2GetWarehouseTableLayout: { + id: "v2GetWarehouseTableLayout", + description: + "Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/tables/{table_id}/layout", + pathParams: ["ref", "table_id"], + queryParams: [], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2GetWarehouseTableLayoutInput, + outputSchema: V2GetWarehouseTableLayoutOutput, + }, v2GetWarehouseTeardown: { id: "v2GetWarehouseTeardown", description: diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index dfcad4c47e..d8832c0141 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -3156,6 +3156,22 @@ export const versionedEffectOperations = { options, ); }), + getWarehouseTableLayout: ( + input: typeof operationDefinitions.v2GetWarehouseTableLayout.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2GetWarehouseTableLayout.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2GetWarehouseTableLayout">( + operationDefinitions.v2GetWarehouseTableLayout, + input, + options, + ); + }), getWarehouseTeardown: ( input: typeof operationDefinitions.v2GetWarehouseTeardown.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index a47c989ec1..66f86343b5 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -33086,6 +33086,126 @@ }, "x-scalar-stability": "experimental" } + }, + "/v2/projects/{ref}/warehouse/tables/{table_id}/layout": { + "get": { + "description": "Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-table-layout", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "in": "path", + "name": "table_id", + "required": true, + "schema": { + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutResponse_Output" + } + } + }, + "description": "" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Table not replicated to Warehouse" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse feature, project metadata or table layout unavailable" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Get the layout of a table replicated to Warehouse", + "tags": ["Projects Warehouse"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.tables.layout", + "method": "get" + }, + "x-scalar-stability": "experimental" + } } }, "components": { @@ -49290,6 +49410,250 @@ }, "required": ["data"], "type": "object" + }, + "V2WarehouseTableLayoutResponse_Output": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "desired": { + "description": "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", + "properties": { + "partition_by": { + "description": "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", + "items": { + "properties": { + "column": { + "description": "Source column name.", + "type": "string" + }, + "transform": { + "oneOf": [ + { + "properties": { + "kind": { + "enum": ["identity"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["year"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["month"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["day"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["hour"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "count": { + "description": "Number of hash buckets.", + "exclusiveMinimum": true, + "maximum": 2147483647, + "minimum": 0, + "type": "integer" + }, + "kind": { + "enum": ["bucket"], + "type": "string" + } + }, + "required": ["count", "kind"], + "type": "object" + } + ] + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "nullable": true, + "type": "array" + }, + "sort_by": { + "description": "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + "nullable": true, + "oneOf": [ + { + "properties": { + "kind": { + "enum": ["none"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["primary_key"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "columns": { + "items": { + "properties": { + "direction": { + "enum": ["asc", "desc"], + "type": "string" + }, + "name": { + "description": "Source column name.", + "type": "string" + }, + "nulls": { + "description": "Null placement. Null uses DuckLake's default placement.", + "enum": ["first", "last", null], + "nullable": true, + "type": "string" + } + }, + "required": ["direction", "name", "nulls"], + "type": "object" + }, + "type": "array" + }, + "kind": { + "enum": ["columns"], + "type": "string" + } + }, + "required": ["columns", "kind"], + "type": "object" + } + ] + } + }, + "required": ["partition_by", "sort_by"], + "type": "object" + }, + "name": { + "description": "Source PostgreSQL table name.", + "type": "string" + }, + "observation_status": { + "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, and unavailable when the catalog could not be read.", + "enum": ["observed", "table_missing", "unavailable"], + "type": "string" + }, + "observed": { + "description": "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", + "nullable": true, + "properties": { + "observed_at": { + "description": "Time the catalog metadata was read.", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "partition_by": { + "description": "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", + "items": { + "properties": { + "column": { + "type": "string" + }, + "transform": { + "type": "string" + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "type": "array" + }, + "sort_by": { + "description": "Active sort expressions in key order, as the catalog reports them.", + "items": { + "properties": { + "direction": { + "type": "string" + }, + "expression": { + "type": "string" + }, + "nulls": { + "type": "string" + } + }, + "required": ["direction", "expression", "nulls"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["observed_at", "partition_by", "sort_by"], + "type": "object" + }, + "schema": { + "description": "Source PostgreSQL schema of the table.", + "type": "string" + } + }, + "required": ["desired", "name", "observation_status", "observed", "schema"], + "type": "object" + }, + "id": { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table_layout"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index d074d62edf..85ddcad1f1 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -452,4 +452,5 @@ export const operationPermissions: Readonly "v2-get-warehouse-connection": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-list-warehouse-tables": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-get-warehouse-table": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-get-warehouse-table-layout": { fga: [["database_read"]], oauthScope: "database:read" }, }; From b9edac9faf2a417701ca9cdd12dace2505731e13 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 18:50:03 +0100 Subject: [PATCH 21/45] fix(cli): keep the consent suggestion and regenerate commands after the spec refresh --- .github/workflows/api-package-sync.yml | 3 --- apps/cli/src/commands/api/SIDE_EFFECTS.md | 21 +++++++++++-------- .../src/commands/api/api-commands.e2e.test.ts | 2 +- .../cli/standard-errors.integration.test.ts | 4 ++-- apps/cli/src/shared/cli/standard-errors.ts | 2 +- .../shared/cli/standard-errors.unit.test.ts | 2 +- package.json | 2 +- turbo.json | 1 - 8 files changed, 18 insertions(+), 19 deletions(-) diff --git a/.github/workflows/api-package-sync.yml b/.github/workflows/api-package-sync.yml index 74ff75a551..996ea8afcc 100644 --- a/.github/workflows/api-package-sync.yml +++ b/.github/workflows/api-package-sync.yml @@ -28,9 +28,6 @@ jobs: env: SUPABASE_API_URL: https://api.supabase.com - - name: Regenerate API commands - run: pnpm --filter supabase run api-commands:generate - - name: Format API package run: pnpm run fmt:fix diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index a97891d061..9d7b284931 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -55,19 +55,22 @@ Each command sends the one request described in the [per-command reference](./ge Bearer token authentication, and passes the JSON response through unchanged. The calls every command can add: -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | -------------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------ | -| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive (project picker) | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}`; linked-project cache miss only (best-effort, after the command) | +| Method | Path | Auth | Request body | Response (used fields) | +| ------ | -------------------------------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive (project picker) | +| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}`; linked-project cache miss only (best-effort, after the command) | +| `GET` | `/v1/projects/{parent}/branches` | Bearer token | none | `[{id, name, project_ref, is_default}]` — only for `--remote=`, and for a bare `--remote` followed by a word that could name a branch; `{parent}` is `SUPABASE_PROJECT_ID`, else the linked project | +| `GET` | `/v1/branches/{id}` | Bearer token | none | `{ref, status, …}` — only for `--remote=` when no project is linked | With `--wait`, the command also polls the read operation named in its reference entry. ### Request input - `--body` or `--file` supply the whole body; a flag replaces its own field and nothing else. -- The input is validated before consent and before any request: a top-level body key outside the - declared request-body fields, an unknown nested field or a missing required flag fails with - nothing sent. +- The input is validated before consent and before the command request: a top-level body key + outside the declared request-body fields, an unknown nested field or a missing required flag + fails with no command request sent. Target resolution runs first, so the project picker and + branch lookups in the table above can still run. - `--dry-run` prints `{method, path, query, headers, body}` and sends no command request, before consent. The linked-project cache read in the table above can still run. It shows the local request, not a server-resolved impact. @@ -88,8 +91,8 @@ error). - The wait succeeds on a status in the succeeded set and fails (`operation_failed`) on a status in the failed set. The failure pointer only supplies the error message and never ends the wait by itself. -- Any non-2xx response while polling, a 409 included, ends the command with the API error; the wait - never resumes. +- Each poll read goes through the API client's own retries (429 and 5xx). Any non-2xx response left + after them, a 409 included, ends the command with the API error; the wait never resumes. - At the timeout the command fails with `wait_timeout`. Timeout and cancellation stop local polling only and do not change server state. - The failure and timeout hint names the command that re-reads the state. When the polled read is a diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index 69e4233203..0523763eb7 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -188,7 +188,7 @@ it.live("warehouse enable without --yes refuses to run when stdin is piped", () const lastLine = result.stderr.trimEnd().split("\n").at(-1) ?? ""; expect(decodeJson(lastLine)).toMatchObject({ code: "usage_error", - hint: expect.stringContaining("Pass --yes"), + hint: "Re-run with --yes to confirm.", }); expect(requests).toEqual([]); }).pipe(Effect.provide(BunServices.layer)), diff --git a/apps/cli/src/shared/cli/standard-errors.integration.test.ts b/apps/cli/src/shared/cli/standard-errors.integration.test.ts index c4dc204752..6b0d778cb7 100644 --- a/apps/cli/src/shared/cli/standard-errors.integration.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.integration.test.ts @@ -71,7 +71,7 @@ describe("errors.standard failure contract", { timeout: SUBPROCESS_TIMEOUT_MS }, ); it.live( - "a run that cannot ask for consent is a usage error telling the caller to pass --yes", + "a run that cannot ask for consent is a usage error that keeps the consent suggestion", () => Effect.gen(function* () { const { exitCode, stdout, stderr } = yield* runFixture(["needs-consent"]); @@ -79,7 +79,7 @@ describe("errors.standard failure contract", { timeout: SUBPROCESS_TIMEOUT_MS }, expect(exitCode).toBe(2); expect(yield* decodeJson(lastLine(stderr))).toMatchObject({ code: "usage_error", - hint: "Pass --yes", + hint: "Re-run with --yes to confirm.", }); }).pipe(Effect.provide(BunServices.layer)), ); diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index 36c14b6dd1..25baf1ff73 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -160,7 +160,7 @@ const failureForError = ( return failure(EXIT_USAGE, "usage_error", error.message, error.hint ?? null); } if (error instanceof HostedMutationConsentRequiredError) { - return failure(EXIT_USAGE, "usage_error", error.message, "Pass --yes"); + return failure(EXIT_USAGE, "usage_error", error.message, error.suggestion); } if (error instanceof HostedMutationDeclinedError) { return failure(EXIT_CANCELLED, "cancelled", error.message); diff --git a/apps/cli/src/shared/cli/standard-errors.unit.test.ts b/apps/cli/src/shared/cli/standard-errors.unit.test.ts index f95aa96146..5db4d82851 100644 --- a/apps/cli/src/shared/cli/standard-errors.unit.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.unit.test.ts @@ -89,7 +89,7 @@ describe("standardFailureFor", () => { { name: "consent required", cause: Cause.fail(new HostedMutationConsentRequiredError({ message: "m", suggestion: "s" })), - expected: { exitCode: 2, code: "usage_error", status: null, hint: "Pass --yes" }, + expected: { exitCode: 2, code: "usage_error", status: null, hint: "s" }, }, { name: "declined confirmation", diff --git a/package.json b/package.json index 0d48b0a0e6..806821e40f 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "scripts": { "prepare": "effect-tsgo patch --no-typescript --oxlint && husky", "build": "pnpm exec turbo run build", - "generate": "pnpm exec turbo run @supabase/api#generate @supabase/stack#generate supabase#api-commands:generate && pnpm exec turbo run supabase#schemas:generate", + "generate": "pnpm exec turbo run @supabase/api#generate @supabase/stack#generate && pnpm exec turbo run supabase#api-commands:generate supabase#schemas:generate", "test:live": "pnpm exec turbo run supabase#test:live --concurrency=1 --", "record": "pnpm exec turbo run @supabase/cli-e2e#record --", "test:smoke": "pnpm exec turbo run supabase#test:smoke --", diff --git a/turbo.json b/turbo.json index dd4a9f0ec9..cfd309f546 100644 --- a/turbo.json +++ b/turbo.json @@ -87,7 +87,6 @@ }, "supabase#api-commands:generate": { "cache": true, - "dependsOn": ["@supabase/api#generate"], "inputs": [ "$TURBO_DEFAULT$", "!src/commands/api/generated*", From 1779d818d9253e1f46936e42685d8d3d4110ac64 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 18 Nov 2026 20:26:21 +0100 Subject: [PATCH 22/45] ci(api): regenerate the API commands in the spec sync --- .github/workflows/api-package-sync.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/api-package-sync.yml b/.github/workflows/api-package-sync.yml index 996ea8afcc..74ff75a551 100644 --- a/.github/workflows/api-package-sync.yml +++ b/.github/workflows/api-package-sync.yml @@ -28,6 +28,9 @@ jobs: env: SUPABASE_API_URL: https://api.supabase.com + - name: Regenerate API commands + run: pnpm --filter supabase run api-commands:generate + - name: Format API package run: pnpm run fmt:fix From 3e17855d917421bff386412395758a86625fd8b5 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 09:41:01 +0100 Subject: [PATCH 23/45] chore(cli): drop the verb vocabulary and command length cap from API command generation --- apps/cli/scripts/api-command-derive.ts | 11 +---------- apps/cli/scripts/api-command-derive.unit.test.ts | 14 -------------- apps/cli/src/commands/api/api-command-policy.ts | 16 ---------------- apps/cli/src/commands/api/api-command.model.ts | 2 +- 4 files changed, 2 insertions(+), 41 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index afdf6032c5..38a180ef32 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -1,6 +1,6 @@ import type { OperationId } from "@supabase/api/effect"; import { Cause, Exit, Predicate, Schema } from "effect"; -import { verbVocabulary, type ApiNoun } from "../src/commands/api/api-command-policy.ts"; +import type { ApiNoun } from "../src/commands/api/api-command-policy.ts"; import type { ApiCommandBinding, ApiCommandEntry, @@ -36,11 +36,8 @@ const CREDENTIAL_TOKENS: ReadonlySet = new Set([ "private", ]); -const VERBS: ReadonlySet = new Set(verbVocabulary); - const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const; const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u; -const MAX_COMMAND_WORDS = 4; /** Headers the request builder owns; a spec that declares them gets no flag. */ const UNMAPPED_HEADERS: ReadonlySet = new Set(["authorization", "content-type", "accept"]); const NON_SECRET_HEADERS: ReadonlySet = new Set(["idempotency-key"]); @@ -772,15 +769,9 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const failuresBefore = problems.length; const command = [...group.split("."), method]; - if (command.length > MAX_COMMAND_WORDS) { - fail(`command "${command.join(" ")}" has more than four words`); - } if (!command.every((segment) => KEBAB.test(segment))) { fail(`command "${command.join(" ")}" must be lowercase kebab-case words`); } - if (!VERBS.has(method)) { - fail(`verb "${method}" is outside the vocabulary; use a listed verb`); - } const noun = nouns[command[0] ?? ""]; if (noun === undefined) { fail(`noun "${command[0]}" is missing from the nouns table`); diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 0338f959a1..49635b262f 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -1280,15 +1280,6 @@ describe("deriveApiCommands", () => { }); it.each([ - [ - "a command of more than four words", - { - "create-thing": operation({ - "x-operation": { group: "thing.sub.deep.deeper", method: "create" }, - }), - }, - 'command "thing sub deep deeper create" has more than four words', - ], [ "a sub-group without a description", { "create-thing": operation({ "x-operation": { group: "thing.other", method: "create" } }) }, @@ -1307,11 +1298,6 @@ describe("deriveApiCommands", () => { { "create-thing": operation({ ...create, parameters: [] }) }, 'operation has no "ref" path parameter', ], - [ - "a verb outside the vocabulary", - { "create-thing": operation({ "x-operation": { group: "thing", method: "frobnicate" } }) }, - 'verb "frobnicate" is outside the vocabulary', - ], [ "an unknown key in x-operation", { diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index dfb73fa48e..e9158102e6 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -1,22 +1,6 @@ import type { OpenApiOperationId } from "@supabase/api/effect"; import type { ExperimentalFeature } from "../../shared/config/experimental-feature.ts"; -/** Verbs every generated command may use. */ -export const verbVocabulary = [ - "list", - "get", - "create", - "update", - "delete", - "enable", - "disable", - "status", - "connection", - "add", - "remove", - "resync", -] as const; - export interface ApiNoun { /** Help text of the noun's group; set only when no hand-written group of that name exists. */ readonly description?: string; diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index 8181339d26..9d09648f34 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -71,7 +71,7 @@ export interface ApiCommandWait { /** A generated command as plain data; the runtime turns each entry into a CLI command. */ export interface ApiCommandEntry { - /** Noun, optional sub-groups and the verb, e.g. `["warehouse", "enable"]`. */ + /** Noun, optional sub-groups and the method, e.g. `["warehouse", "enable"]`. */ readonly command: readonly string[]; /** Kebab-case operation id from the OpenAPI spec. */ readonly operationId: string; From f17926e185993bd77a907be8c882deb27d1566de Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Thu, 19 Nov 2026 10:39:51 +0100 Subject: [PATCH 24/45] feat(cli): add warehouse table layout updates (#7691) Adds generated `warehouse tables layout update` on top of #7640. Accepts typed layout bodies/files and `--reset-table`. Omission preserves a saved setting, null makes it unmanaged, and explicit empty partition rules or the `none` sort selector clear rules. Generated examples for body-taking commands use `--file `. The API requires `sort_by` or `partition_by`; this cross-field rule is server-validated because the emitted OpenAPI does not express it. `--dry-run` validates only the imported schema. The command returns the API response without waiting. Help directs users to `warehouse tables layout get` and `warehouse tables get`; neither read proves completion of this specific update. Waiting needs an update revision or an applied marker. Layout GET remains compatible with responses without update orchestration fields. The OpenAPI request accepts null and all supported sort selectors. Related to PIPE-1459. --- .../command-surface.integration.test.ts | 24 + .../api-command-bindings.integration.test.ts | 34 +- .../src/commands/api/api-command-policy.ts | 3 +- .../api/api-commands.integration.test.ts | 103 +++ apps/cli/src/commands/api/generated.md | 18 + .../cli/src/commands/api/generated.schemas.ts | 593 ++++++++++++++-- apps/cli/src/commands/api/generated.ts | 55 ++ apps/cli/src/commands/api/runtime.ts | 11 +- packages/api/scripts/openapi-overrides.json | 659 +++++++++++++++++- packages/api/src/effect.unit.test.ts | 34 + packages/api/src/generated/contracts.ts | 266 ++++++- packages/api/src/generated/effect-client.ts | 16 + packages/api/src/generated/openapi.json | 644 ++++++++++++++++- packages/api/src/generated/permissions.ts | 4 + 14 files changed, 2386 insertions(+), 78 deletions(-) diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 394a10f8d8..c76d733b63 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -62,6 +62,7 @@ describe("command surface", () => { "warehouse tables get", "warehouse tables layout", "warehouse tables layout get", + "warehouse tables layout update", "warehouse tables list", "warehouse teardowns", "warehouse teardowns get", @@ -79,6 +80,29 @@ describe("command surface", () => { }), ); + it.effect("describes layout updates without unsupported backend workflow flags", () => + Effect.gen(function* () { + const warehouse = yield* warehouseVariant; + const update = warehouse["warehouse tables layout update"]; + expect(update).toMatchObject({ + path: ["warehouse", "tables", "layout", "update"], + stage: { status: "experimental", feature: "warehouse" }, + errors: "standard", + api: { + operationId: "v2-update-warehouse-table-layout", + request: { contentType: "application/json" }, + }, + }); + expect(Object.keys(update?.flags ?? {})).toEqual( + expect.arrayContaining(["body", "file", "dry-run", "reset-table"]), + ); + for (const flag of ["wait", "timeout"]) { + expect(update?.flags).not.toHaveProperty(flag); + } + expect(titlesOf(update?.result)).toEqual(["response", "dryRun"]); + }), + ); + it.effect("describes a generated command from its annotations and operation schemas", () => Effect.gen(function* () { const warehouse = yield* warehouseVariant; diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 224bae2207..81dfab7541 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -157,7 +157,7 @@ interface Input { } /** - * Every non-path input of the operation, read from openapi.json; the flag spelling comes from the + * Every scalar or scalar-array non-path input, read from openapi.json; the flag spelling comes from the * command's declared binding, since naming is the derivation's contract. */ const inputsOf = ( @@ -191,17 +191,27 @@ const inputsOf = ( const envelope = Object.keys(attributes).length > 0; const container = envelope ? attributes : operation.requestSchema; const required = asList(container["required"]); - const fields = Object.entries(asRecord(container["properties"])).map(([field, schema]): Input => { - const sample = sampleOf(schema); - return { - location: "body", - field, - flag: flagFor("body", field), - pointer: `${envelope ? "/data/attributes" : ""}/${field}`, - required: required.includes(field), - sample, - }; - }); + const scalarTypes = ["boolean", "integer", "number", "string"]; + const fields = Object.entries(asRecord(container["properties"])) + .filter(([, schema]) => { + const node = resolveRef(schema); + return ( + scalarTypes.includes(String(node["type"])) || + (node["type"] === "array" && + scalarTypes.includes(String(resolveRef(node["items"])["type"]))) + ); + }) + .map(([field, schema]): Input => { + const sample = sampleOf(schema); + return { + location: "body", + field, + flag: flagFor("body", field), + pointer: `${envelope ? "/data/attributes" : ""}/${field}`, + required: required.includes(field), + sample, + }; + }); return [...queries, ...fields]; }; diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index e9158102e6..e1f6637cd5 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -23,6 +23,7 @@ export const generatedOperations: ReadonlyArray = [ "v2-list-warehouse-tables", "v2-get-warehouse-table", "v2-get-warehouse-table-layout", + "v2-update-warehouse-table-layout", ]; export const nouns = { @@ -31,7 +32,7 @@ export const nouns = { feature: "warehouse", groups: { tables: "Inspect tables replicated to Warehouse", - "tables.layout": "Inspect the layout of tables replicated to Warehouse", + "tables.layout": "Inspect and update the layout of tables replicated to Warehouse", teardowns: "Inspect Warehouse cleanup operations", }, }, diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 4d9740021a..5f89dd0c92 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -520,6 +520,96 @@ describe("generated warehouse commands", () => { }); }); }); + describe("warehouse tables layout update", () => { + const argv = ["warehouse", "tables", "layout", "update", "16385"]; + const layoutPath = `/v2/projects/${VALID_REF}/warehouse/tables/16385/layout`; + const body = { + data: { + type: "warehouse_table_layout", + attributes: { sort_by: { kind: "primary_key" }, partition_by: [] }, + }, + }; + + it.effect.each([ + { flags: [], reset: {} }, + { flags: ["--reset-table"], reset: { reset_table: true } }, + { flags: ["--reset-table", "false"], reset: { reset_table: false } }, + ])( + "sends a layout file with reset option $flags and prints the full API response", + ({ flags, reset }) => { + const response = { + data: { + type: "warehouse_table_layout", + id: "16385", + attributes: { + pipeline_id: "pipeline-1", + schema: "public", + name: "events", + desired: body.data.attributes, + application_status: "waiting_for_start", + reset_table: reset.reset_table ?? false, + observation_status: "not_requested", + observed: null, + future_state: { reason: null }, + }, + }, + }; + const file = `${tempRoot.current}/layout.json`; + const { sent, out, run } = setup([...argv, "--file", file, ...flags], { + yes: true, + route: () => ({ status: 202, body: response }), + }); + return Effect.gen(function* () { + yield* (yield* FileSystem.FileSystem).writeFileString(file, encodeJson(body)); + yield* run; + expect(sent).toEqual([ + { + method: "PATCH", + path: layoutPath, + search: "", + body: { data: { ...body.data, attributes: { ...body.data.attributes, ...reset } } }, + }, + ]); + expect(decodeJson(out.stdoutText)).toEqual(response); + }).pipe(Effect.provide(BunServices.layer)); + }, + ); + + it.effect( + "previews unmanaged sorting while preserving omitted settings without sending a request", + () => { + const clear = { data: { type: "warehouse_table_layout", attributes: { sort_by: null } } }; + const { sent, out, run } = setup([...argv, "--body", encodeJson(clear), "--dry-run"], { + route: accepted, + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([]); + expect(decodeJson(out.stdoutText)).toEqual({ + method: "PATCH", + path: layoutPath, + query: {}, + headers: {}, + body: clear, + }); + }); + }, + ); + + it.effect("rejects a non-boolean reset before making a hosted request", () => { + const reset = { + data: { type: "warehouse_table_layout", attributes: { reset_table: "true" } }, + }; + const { sent, run } = setup([...argv, "--body", encodeJson(reset)], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + expect(failureOf(yield* Effect.exit(run))).toBeInstanceOf(ApiCommandUsageError); + expect(sent).toEqual([]); + }); + }); + }); describe("warehouse connection", () => { const connectionPath = `/v2/projects/${VALID_REF}/warehouse/connection`; const host = `${VALID_REF}.warehouse.example.invalid`; @@ -1193,6 +1283,19 @@ describe("generated warehouse commands", () => { }); describe("help", () => { + it.effect("shows a body file in the layout update example", () => { + const { console, calls } = fakeConsole(); + const { run } = setup(["warehouse", "tables", "layout", "update", "--help"], { + route: accepted, + }); + return Effect.gen(function* () { + yield* run.pipe(Effect.provideService(Console.Console, console)); + expect(calls.join("\n")).toContain( + "supabase warehouse tables layout update --file ", + ); + }); + }); + it.effect("marks a required API flag as required in its description", () => { const { console, calls } = fakeConsole(); const { run } = setup(["warehouse", "enable", "--help"], { route: accepted }); diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index e010aa47b3..dd83ee349f 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -99,6 +99,24 @@ Returns the sorting and partitioning rules saved for one replicated table, by so - Request: `GET /v2/projects/{ref}/warehouse/tables/{table_id}/layout` (`v2-get-warehouse-table-layout`), success 200 json. - Positional argument ``, bound to path parameter `table_id`. +## `supabase warehouse tables layout update` + +Update the layout of a table replicated to Warehouse + +Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying. + +- Access: mutation, consent defaults to No (`--yes` when it cannot prompt). +- Feature: `warehouse`. +- Request: `PATCH /v2/projects/{ref}/warehouse/tables/{table_id}/layout` (`v2-update-warehouse-table-layout`), success 202 json. +- Body: JSON envelope `data.type = warehouse_table_layout`, fields under `data.attributes`. +- Positional argument ``, bound to path parameter `table_id`. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| --------------- | ------- | -------- | ---------- | ----------------------------------- | +| `--reset-table` | boolean | no | no | body `/data/attributes/reset_table` | + ## `supabase warehouse tables list` List tables replicated to Warehouse diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index 334a34bed9..af39c4086d 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -1209,6 +1209,11 @@ export const apiCommandSchemas = { properties: { attributes: { properties: { + application_status: { + description: + "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + type: "string", + }, desired: { description: "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", @@ -1299,68 +1304,65 @@ export const apiCommandSchemas = { type: ["array", "null"], }, sort_by: { - anyOf: [ + description: + "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + oneOf: [ { - description: - "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", - oneOf: [ - { - properties: { - kind: { - enum: ["none"], - type: "string", - }, - }, - required: ["kind"], - type: "object", + properties: { + kind: { + enum: ["none"], + type: "string", }, - { - properties: { - kind: { - enum: ["primary_key"], - type: "string", - }, - }, - required: ["kind"], - type: "object", + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["primary_key"], + type: "string", }, - { - properties: { - columns: { - items: { - properties: { - direction: { - enum: ["asc", "desc"], - type: "string", - }, - name: { - description: "Source column name.", - type: "string", - }, - nulls: { - description: - "Null placement. Null uses DuckLake's default placement.", - enum: ["first", "last", null], - type: ["string", "null"], - }, - }, - required: ["direction", "name", "nulls"], - type: "object", + }, + required: ["kind"], + type: "object", + }, + { + properties: { + columns: { + items: { + properties: { + direction: { + enum: ["asc", "desc"], + type: "string", + }, + name: { + description: "Source column name.", + type: "string", + }, + nulls: { + description: + "Null placement. Null uses DuckLake's default placement.", + enum: ["first", "last", null], + type: ["string", "null"], }, - type: "array", - }, - kind: { - enum: ["columns"], - type: "string", }, + required: ["direction", "name", "nulls"], + type: "object", }, - required: ["columns", "kind"], - type: "object", + type: "array", }, - ], + kind: { + enum: ["columns"], + type: "string", + }, + }, + required: ["columns", "kind"], + type: "object", }, { - type: "null", + type: ["object", "null"], + enum: [null], }, ], }, @@ -1374,8 +1376,8 @@ export const apiCommandSchemas = { }, observation_status: { description: - "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, and unavailable when the catalog could not be read.", - enum: ["observed", "table_missing", "unavailable"], + "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", + enum: ["not_requested", "observed", "table_missing", "unavailable"], type: "string", }, observed: { @@ -1430,6 +1432,15 @@ export const apiCommandSchemas = { required: ["observed_at", "partition_by", "sort_by"], type: ["object", "null"], }, + pipeline_id: { + description: "Warehouse replication pipeline identity.", + type: "string", + }, + reset_table: { + description: + "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + type: "boolean", + }, schema: { description: "Source PostgreSQL schema of the table.", type: "string", @@ -1649,4 +1660,476 @@ export const apiCommandSchemas = { type: "object", }, }, + "v2-update-warehouse-table-layout": { + request: { + contentType: "application/json", + schema: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + additionalProperties: false, + properties: { + partition_by: { + description: + "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + items: { + additionalProperties: false, + properties: { + column: { + description: "Source column name.", + minLength: 1, + type: "string", + }, + transform: { + oneOf: [ + { + additionalProperties: false, + properties: { + kind: { + enum: ["identity"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["year"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["month"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["day"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["hour"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + count: { + description: "Number of hash buckets.", + maximum: 2147483647, + type: "integer", + exclusiveMinimum: 0, + }, + kind: { + enum: ["bucket"], + type: "string", + }, + }, + required: ["count", "kind"], + type: "object", + }, + ], + }, + }, + required: ["column", "transform"], + type: "object", + }, + type: ["array", "null"], + }, + reset_table: { + description: + "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + type: "boolean", + }, + sort_by: { + description: + "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + oneOf: [ + { + additionalProperties: false, + properties: { + kind: { + enum: ["none"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["primary_key"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + columns: { + items: { + additionalProperties: false, + properties: { + direction: { + enum: ["asc", "desc"], + type: "string", + }, + name: { + description: "Source column name.", + minLength: 1, + type: "string", + }, + nulls: { + description: + "Null placement. Null uses DuckLake's default placement.", + enum: ["first", "last", null], + type: ["string", "null"], + }, + }, + required: ["direction", "name"], + type: "object", + }, + minItems: 1, + type: "array", + }, + kind: { + enum: ["columns"], + type: "string", + }, + }, + required: ["columns", "kind"], + type: "object", + }, + { + type: ["object", "null"], + enum: [null], + }, + ], + }, + }, + type: "object", + }, + type: { + description: "Resource type.", + enum: ["warehouse_table_layout"], + type: "string", + }, + }, + required: ["attributes", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + application_status: { + description: + "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + type: "string", + }, + desired: { + description: + "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", + properties: { + partition_by: { + description: + "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", + items: { + properties: { + column: { + description: "Source column name.", + type: "string", + }, + transform: { + oneOf: [ + { + properties: { + kind: { + enum: ["identity"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["year"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["month"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["day"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["hour"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + count: { + description: "Number of hash buckets.", + maximum: 2147483647, + type: "integer", + exclusiveMinimum: 0, + }, + kind: { + enum: ["bucket"], + type: "string", + }, + }, + required: ["count", "kind"], + type: "object", + }, + ], + }, + }, + required: ["column", "transform"], + type: "object", + }, + type: ["array", "null"], + }, + sort_by: { + description: + "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + oneOf: [ + { + properties: { + kind: { + enum: ["none"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + kind: { + enum: ["primary_key"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + properties: { + columns: { + items: { + properties: { + direction: { + enum: ["asc", "desc"], + type: "string", + }, + name: { + description: "Source column name.", + type: "string", + }, + nulls: { + description: + "Null placement. Null uses DuckLake's default placement.", + enum: ["first", "last", null], + type: ["string", "null"], + }, + }, + required: ["direction", "name", "nulls"], + type: "object", + }, + type: "array", + }, + kind: { + enum: ["columns"], + type: "string", + }, + }, + required: ["columns", "kind"], + type: "object", + }, + { + type: ["object", "null"], + enum: [null], + }, + ], + }, + }, + required: ["partition_by", "sort_by"], + type: "object", + }, + name: { + description: "Source PostgreSQL table name.", + type: "string", + }, + observation_status: { + description: + "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", + enum: ["not_requested", "observed", "table_missing", "unavailable"], + type: "string", + }, + observed: { + description: + "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", + properties: { + observed_at: { + description: "Time the catalog metadata was read.", + format: "date-time", + pattern: + "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + type: "string", + }, + partition_by: { + description: + "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", + items: { + properties: { + column: { + type: "string", + }, + transform: { + type: "string", + }, + }, + required: ["column", "transform"], + type: "object", + }, + type: "array", + }, + sort_by: { + description: + "Active sort expressions in key order, as the catalog reports them.", + items: { + properties: { + direction: { + type: "string", + }, + expression: { + type: "string", + }, + nulls: { + type: "string", + }, + }, + required: ["direction", "expression", "nulls"], + type: "object", + }, + type: "array", + }, + }, + required: ["observed_at", "partition_by", "sort_by"], + type: ["object", "null"], + }, + pipeline_id: { + description: "Warehouse replication pipeline identity.", + type: "string", + }, + reset_table: { + description: + "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + type: "boolean", + }, + schema: { + description: "Source PostgreSQL schema of the table.", + type: "string", + }, + }, + required: [ + "application_status", + "desired", + "name", + "observation_status", + "observed", + "pipeline_id", + "reset_table", + "schema", + ], + type: "object", + }, + id: { + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + maxLength: 10, + pattern: "^[1-9]\\d*$", + type: "string", + examples: ["16385"], + }, + type: { + description: "Resource type.", + enum: ["warehouse_table_layout"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, } as const satisfies Readonly>; diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 52f0e35045..9a320f0442 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -282,6 +282,61 @@ export const apiCommands = [ }, ], }, + { + command: ["warehouse", "tables", "layout", "update"], + operationId: "v2-update-warehouse-table-layout", + definition: "v2UpdateWarehouseTableLayout", + method: "PATCH", + apiPath: "/v2/projects/{ref}/warehouse/tables/{table_id}/layout", + summary: "Update the layout of a table replicated to Warehouse", + description: + "Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying.", + readOnly: false, + feature: "warehouse", + body: { + contentType: "application/json", + kind: "json-envelope", + type: "warehouse_table_layout", + }, + response: { + status: 202, + kind: "json", + }, + argument: { + name: "table-id", + description: "Source Postgres table OID from the Warehouse tables list.", + }, + flags: [ + { + name: "reset-table", + type: "boolean", + repeatable: false, + required: false, + description: + "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "path", + name: "table_id", + source: "argument", + argument: "table-id", + }, + { + location: "body", + name: "reset_table", + pointer: "/data/attributes/reset_table", + source: "flag", + flag: "reset-table", + }, + ], + }, { command: ["warehouse", "tables", "list"], operationId: "v2-list-warehouse-tables", diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 91fa50c5c8..06fe703d3a 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -297,10 +297,17 @@ const handle = Effect.fn("api-command.run")(function* ( const exampleFor = (entry: ApiCommandEntry): string => { const required = entry.flags - .filter((flag) => flag.required) + .filter( + (flag) => + flag.required && + !entry.bindings.some( + (binding) => binding.location === "body" && binding.flag === flag.name, + ), + ) .map((flag) => `--${flag.name}${flag.type === "boolean" ? "" : ` <${flag.name}>`}`); const positional = entry.argument === undefined ? [] : [`<${entry.argument.name}>`]; - return ["supabase", ...entry.command, ...positional, ...required].join(" "); + const body = entry.body === undefined ? [] : ["--file "]; + return ["supabase", ...entry.command, ...positional, ...required, ...body].join(" "); }; const permissionsOf = (entry: ApiCommandEntry, resolved: ResolvedWait | undefined) => { diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 8e26f033d3..d81a2b35e1 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -1606,6 +1606,10 @@ "properties": { "attributes": { "properties": { + "application_status": { + "description": "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + "type": "string" + }, "desired": { "description": "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", "properties": { @@ -1697,7 +1701,6 @@ }, "sort_by": { "description": "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", - "nullable": true, "oneOf": [ { "properties": { @@ -1751,6 +1754,11 @@ }, "required": ["columns", "kind"], "type": "object" + }, + { + "type": "object", + "nullable": true, + "enum": [null] } ] } @@ -1763,8 +1771,8 @@ "type": "string" }, "observation_status": { - "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, and unavailable when the catalog could not be read.", - "enum": ["observed", "table_missing", "unavailable"], + "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", + "enum": ["not_requested", "observed", "table_missing", "unavailable"], "type": "string" }, "observed": { @@ -1816,6 +1824,14 @@ "required": ["observed_at", "partition_by", "sort_by"], "type": "object" }, + "pipeline_id": { + "description": "Warehouse replication pipeline identity.", + "type": "string" + }, + "reset_table": { + "description": "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + "type": "boolean" + }, "schema": { "description": "Source PostgreSQL schema of the table.", "type": "string" @@ -1875,5 +1891,642 @@ "inspect": "v2-get-warehouse-status" } } + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1tables~1{table_id}~1layout/patch", + "value": { + "description": "Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-update-warehouse-table-layout", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Source Postgres table OID from the Warehouse tables list.", + "in": "path", + "name": "table_id", + "required": true, + "schema": { + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutUpdateRequest" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutUpdateResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid layout or source schema" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse pipeline or replicated table not found" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse or pipeline mutation conflict, or reset requested without initial sync" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Layout update unavailable or outcome uncertain; inspect the saved layout, pipeline, and table state before retrying" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Update the layout of a table replicated to Warehouse", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse.tables.layout", + "method": "update" + }, + "x-scalar-stability": "experimental" + }, + "$comment": "The Warehouse layout update contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseTableLayoutUpdateRequest", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "additionalProperties": false, + "properties": { + "partition_by": { + "description": "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + "items": { + "additionalProperties": false, + "properties": { + "column": { + "description": "Source column name.", + "minLength": 1, + "type": "string" + }, + "transform": { + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["identity"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["year"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["month"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["day"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["hour"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "count": { + "description": "Number of hash buckets.", + "exclusiveMinimum": true, + "maximum": 2147483647, + "minimum": 0, + "type": "integer" + }, + "kind": { + "enum": ["bucket"], + "type": "string" + } + }, + "required": ["count", "kind"], + "type": "object" + } + ] + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "nullable": true, + "type": "array" + }, + "reset_table": { + "description": "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + "type": "boolean" + }, + "sort_by": { + "description": "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["none"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["primary_key"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "columns": { + "items": { + "additionalProperties": false, + "properties": { + "direction": { + "enum": ["asc", "desc"], + "type": "string" + }, + "name": { + "description": "Source column name.", + "minLength": 1, + "type": "string" + }, + "nulls": { + "description": "Null placement. Null uses DuckLake's default placement.", + "enum": ["first", "last", null], + "nullable": true, + "type": "string" + } + }, + "required": ["direction", "name"], + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "kind": { + "enum": ["columns"], + "type": "string" + } + }, + "required": ["columns", "kind"], + "type": "object" + }, + { + "type": "object", + "nullable": true, + "enum": [null] + } + ] + } + }, + "type": "object" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table_layout"], + "type": "string" + } + }, + "required": ["attributes", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse layout update contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseTableLayoutUpdateResponse_Output", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "application_status": { + "description": "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + "type": "string" + }, + "desired": { + "description": "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", + "properties": { + "partition_by": { + "description": "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", + "items": { + "properties": { + "column": { + "description": "Source column name.", + "type": "string" + }, + "transform": { + "oneOf": [ + { + "properties": { + "kind": { + "enum": ["identity"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["year"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["month"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["day"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["hour"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "count": { + "description": "Number of hash buckets.", + "exclusiveMinimum": true, + "maximum": 2147483647, + "minimum": 0, + "type": "integer" + }, + "kind": { + "enum": ["bucket"], + "type": "string" + } + }, + "required": ["count", "kind"], + "type": "object" + } + ] + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "nullable": true, + "type": "array" + }, + "sort_by": { + "description": "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + "oneOf": [ + { + "properties": { + "kind": { + "enum": ["none"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["primary_key"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "columns": { + "items": { + "properties": { + "direction": { + "enum": ["asc", "desc"], + "type": "string" + }, + "name": { + "description": "Source column name.", + "type": "string" + }, + "nulls": { + "description": "Null placement. Null uses DuckLake's default placement.", + "enum": ["first", "last", null], + "nullable": true, + "type": "string" + } + }, + "required": ["direction", "name", "nulls"], + "type": "object" + }, + "type": "array" + }, + "kind": { + "enum": ["columns"], + "type": "string" + } + }, + "required": ["columns", "kind"], + "type": "object" + }, + { + "type": "object", + "nullable": true, + "enum": [null] + } + ] + } + }, + "required": ["partition_by", "sort_by"], + "type": "object" + }, + "name": { + "description": "Source PostgreSQL table name.", + "type": "string" + }, + "observation_status": { + "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", + "enum": ["not_requested", "observed", "table_missing", "unavailable"], + "type": "string" + }, + "observed": { + "description": "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", + "nullable": true, + "properties": { + "observed_at": { + "description": "Time the catalog metadata was read.", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "partition_by": { + "description": "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", + "items": { + "properties": { + "column": { + "type": "string" + }, + "transform": { + "type": "string" + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "type": "array" + }, + "sort_by": { + "description": "Active sort expressions in key order, as the catalog reports them.", + "items": { + "properties": { + "direction": { + "type": "string" + }, + "expression": { + "type": "string" + }, + "nulls": { + "type": "string" + } + }, + "required": ["direction", "expression", "nulls"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["observed_at", "partition_by", "sort_by"], + "type": "object" + }, + "pipeline_id": { + "description": "Warehouse replication pipeline identity.", + "type": "string" + }, + "reset_table": { + "description": "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + "type": "boolean" + }, + "schema": { + "description": "Source PostgreSQL schema of the table.", + "type": "string" + } + }, + "required": [ + "application_status", + "desired", + "name", + "observation_status", + "observed", + "pipeline_id", + "reset_table", + "schema" + ], + "type": "object" + }, + "id": { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table_layout"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "Layout updates return orchestration fields that older layout reads do not include." } ] diff --git a/packages/api/src/effect.unit.test.ts b/packages/api/src/effect.unit.test.ts index 61098ed1c4..c6cc2eda89 100644 --- a/packages/api/src/effect.unit.test.ts +++ b/packages/api/src/effect.unit.test.ts @@ -146,6 +146,40 @@ describe("database OpenAPI response contract", () => { }); describe("makeApiClient", () => { + test("decodes Warehouse layout reads without update orchestration fields", () => + Effect.runPromise( + Effect.gen(function* () { + const body = { + data: { + type: "warehouse_table_layout", + id: "16385", + attributes: { + schema: "public", + name: "events", + desired: { sort_by: null, partition_by: [] }, + observation_status: "observed", + observed: { + sort_by: [], + partition_by: [], + observed_at: "2026-11-18T09:30:00Z", + }, + }, + }, + }; + const client = yield* makeApiClient(config).pipe( + Effect.provide( + httpClientLayer((request) => Effect.succeed(jsonResponse(request, 200, body))), + ), + ); + + const result = yield* client.v2.getWarehouseTableLayout({ + ref: "abcdefghijklmnopqrst", + table_id: "16385", + }); + expect(result).toEqual(body); + }), + )); + test("allows raw operations to override generated request headers", () => Effect.runPromise( Effect.gen(function* () { diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 07acba934a..63581d265a 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -15214,6 +15214,12 @@ export const V2GetWarehouseTableLayoutInput = Schema.Struct({ export const V2GetWarehouseTableLayoutOutput = Schema.Struct({ data: Schema.Struct({ attributes: Schema.Struct({ + application_status: Schema.optionalKey( + Schema.String.annotate({ + description: + "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + }), + ), desired: Schema.Struct({ partition_by: Schema.Union([ Schema.Array( @@ -15281,9 +15287,9 @@ export const V2GetWarehouseTableLayoutOutput = Schema.Struct({ }), name: Schema.String.annotate({ description: "Source PostgreSQL table name." }), observation_status: Schema.Union([ - Schema.Literals(["observed", "table_missing", "unavailable"]).annotate({ + Schema.Literals(["not_requested", "observed", "table_missing", "unavailable"]).annotate({ description: - "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, and unavailable when the catalog could not be read.", + "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", }), OpenString, ]), @@ -15314,6 +15320,15 @@ export const V2GetWarehouseTableLayoutOutput = Schema.Struct({ }), Schema.Null, ]), + pipeline_id: Schema.optionalKey( + Schema.String.annotate({ description: "Warehouse replication pipeline identity." }), + ), + reset_table: Schema.optionalKey( + Schema.Boolean.annotate({ + description: + "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + }), + ), schema: Schema.String.annotate({ description: "Source PostgreSQL schema of the table." }), }), id: Schema.String.annotate({ @@ -20292,6 +20307,238 @@ export const V2UpdateNotebookOutput = Schema.Struct({ }), }), }); +export const V2UpdateWarehouseTableLayoutInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + table_id: Schema.String.check( + Schema.isMaxCodePoints(10).annotate({ expected: "a string with at most 10 code points" }), + ).check( + Schema.isPattern(new RegExp("^[1-9]\\d*$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*$", + }), + ), + data: Schema.Struct({ + attributes: Schema.Struct({ + partition_by: Schema.optionalKey( + Schema.Union([ + Schema.Array( + Schema.Struct({ + column: Schema.String.annotate({ description: "Source column name." }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + transform: Schema.Union( + [ + Schema.Struct({ kind: Schema.Literal("identity") }), + Schema.Struct({ kind: Schema.Literal("year") }), + Schema.Struct({ kind: Schema.Literal("month") }), + Schema.Struct({ kind: Schema.Literal("day") }), + Schema.Struct({ kind: Schema.Literal("hour") }), + Schema.Struct({ + count: Schema.Number.annotate({ description: "Number of hash buckets." }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(2147483647).annotate({ + expected: "a value less than or equal to 2147483647", + }), + ) + .check( + Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" }), + ), + kind: Schema.Literal("bucket"), + }), + ], + { mode: "oneOf" }, + ), + }), + ).annotate({ + description: + "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + }), + Schema.Null, + ]), + ), + reset_table: Schema.optionalKey( + Schema.Boolean.annotate({ + description: + "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + }), + ), + sort_by: Schema.optionalKey( + Schema.Union( + [ + Schema.Struct({ kind: Schema.Literal("none") }), + Schema.Struct({ kind: Schema.Literal("primary_key") }), + Schema.Struct({ + columns: Schema.Array( + Schema.Struct({ + direction: Schema.Literals(["asc", "desc"]), + name: Schema.String.annotate({ description: "Source column name." }).check( + Schema.isMinLength(1).annotate({ + expected: "a value with a length of at least 1", + }), + ), + nulls: Schema.optionalKey( + Schema.Union([Schema.Literals(["first", "last"]), Schema.Null]).annotate({ + description: "Null placement. Null uses DuckLake's default placement.", + }), + ), + }), + ).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + kind: Schema.Literal("columns"), + }), + Schema.Null, + ], + { mode: "oneOf" }, + ).annotate({ + description: + "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + }), + ), + }), + type: Schema.Literal("warehouse_table_layout").annotate({ description: "Resource type." }), + }), +}); +export const V2UpdateWarehouseTableLayoutOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + application_status: Schema.String.annotate({ + description: + "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + }), + desired: Schema.Struct({ + partition_by: Schema.Union([ + Schema.Array( + Schema.Struct({ + column: Schema.String.annotate({ description: "Source column name." }), + transform: Schema.Union( + [ + Schema.Struct({ kind: Schema.Literal("identity") }), + Schema.Struct({ kind: Schema.Literal("year") }), + Schema.Struct({ kind: Schema.Literal("month") }), + Schema.Struct({ kind: Schema.Literal("day") }), + Schema.Struct({ kind: Schema.Literal("hour") }), + Schema.Struct({ + count: Schema.Number.annotate({ description: "Number of hash buckets." }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(2147483647).annotate({ + expected: "a value less than or equal to 2147483647", + }), + ) + .check( + Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" }), + ), + kind: Schema.Literal("bucket"), + }), + ], + { mode: "oneOf" }, + ), + }), + ).annotate({ + description: + "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", + }), + Schema.Null, + ]), + sort_by: Schema.Union( + [ + Schema.Struct({ kind: Schema.Literal("none") }), + Schema.Struct({ kind: Schema.Literal("primary_key") }), + Schema.Struct({ + columns: Schema.Array( + Schema.Struct({ + direction: Schema.Union([Schema.Literals(["asc", "desc"]), OpenString]), + name: Schema.String.annotate({ description: "Source column name." }), + nulls: Schema.Union([ + Schema.Union([Schema.Literals(["first", "last"]), Schema.Null]).annotate({ + description: "Null placement. Null uses DuckLake's default placement.", + }), + OpenString, + ]), + }), + ), + kind: Schema.Literal("columns"), + }), + Schema.Null, + ], + { mode: "oneOf" }, + ).annotate({ + description: + "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + }), + }).annotate({ + description: + "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", + }), + name: Schema.String.annotate({ description: "Source PostgreSQL table name." }), + observation_status: Schema.Union([ + Schema.Literals(["not_requested", "observed", "table_missing", "unavailable"]).annotate({ + description: + "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", + }), + OpenString, + ]), + observed: Schema.Union([ + Schema.Struct({ + observed_at: Schema.String.annotate({ + description: "Time the catalog metadata was read.", + format: "date-time", + }), + partition_by: Schema.Array( + Schema.Struct({ column: Schema.String, transform: Schema.String }), + ).annotate({ + description: + "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", + }), + sort_by: Schema.Array( + Schema.Struct({ + direction: Schema.String, + expression: Schema.String, + nulls: Schema.String, + }), + ).annotate({ + description: "Active sort expressions in key order, as the catalog reports them.", + }), + }).annotate({ + description: + "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", + }), + Schema.Null, + ]), + pipeline_id: Schema.String.annotate({ + description: "Warehouse replication pipeline identity.", + }), + reset_table: Schema.Boolean.annotate({ + description: + "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + }), + schema: Schema.String.annotate({ description: "Source PostgreSQL schema of the table." }), + }), + id: Schema.String.annotate({ + description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + }) + .check( + Schema.isMaxCodePoints(10).annotate({ expected: "a string with at most 10 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[1-9]\\d*$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*$", + }), + ), + type: Schema.Literal("warehouse_table_layout").annotate({ description: "Resource type." }), + }), +}); export const V1ApplyAMigrationOutput = Schema.Void; export const V1ApplyProjectAddonOutput = Schema.Void; export const V1AuthorizeUserOutput = Schema.Void; @@ -20581,6 +20828,7 @@ export const openApiOperationIdMap = { "v2-transfer-a-project": "v2TransferAProject", "v2-update-log-drain": "v2UpdateLogDrain", "v2-update-notebook": "v2UpdateNotebook", + "v2-update-warehouse-table-layout": "v2UpdateWarehouseTableLayout", } as const; export const operationDefinitions = { @@ -24284,6 +24532,20 @@ export const operationDefinitions = { inputSchema: V2UpdateNotebookInput, outputSchema: V2UpdateNotebookOutput, }, + v2UpdateWarehouseTableLayout: { + id: "v2UpdateWarehouseTableLayout", + description: + "Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "PATCH", + path: "/v2/projects/{ref}/warehouse/tables/{table_id}/layout", + pathParams: ["ref", "table_id"], + queryParams: [], + headerParams: [], + requestBody: { kind: "json", contentType: "application/json", fields: ["data"] }, + response: { kind: "json" }, + inputSchema: V2UpdateWarehouseTableLayoutInput, + outputSchema: V2UpdateWarehouseTableLayoutOutput, + }, } as const; export type OpenApiOperationId = keyof typeof openApiOperationIdMap; diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index d8832c0141..d9740de20a 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -3764,6 +3764,22 @@ export const versionedEffectOperations = { options, ); }), + updateWarehouseTableLayout: ( + input: typeof operationDefinitions.v2UpdateWarehouseTableLayout.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2UpdateWarehouseTableLayout.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2UpdateWarehouseTableLayout">( + operationDefinitions.v2UpdateWarehouseTableLayout, + input, + options, + ); + }), }, } as const; diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index 66f86343b5..600907edaa 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -33205,6 +33205,169 @@ "method": "get" }, "x-scalar-stability": "experimental" + }, + "patch": { + "description": "Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-update-warehouse-table-layout", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Source Postgres table OID from the Warehouse tables list.", + "in": "path", + "name": "table_id", + "required": true, + "schema": { + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutUpdateRequest" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutUpdateResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid layout or source schema" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse pipeline or replicated table not found" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse or pipeline mutation conflict, or reset requested without initial sync" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Layout update unavailable or outcome uncertain; inspect the saved layout, pipeline, and table state before retrying" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Update the layout of a table replicated to Warehouse", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse.tables.layout", + "method": "update" + }, + "x-scalar-stability": "experimental" } } }, @@ -49417,6 +49580,10 @@ "properties": { "attributes": { "properties": { + "application_status": { + "description": "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + "type": "string" + }, "desired": { "description": "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", "properties": { @@ -49508,7 +49675,6 @@ }, "sort_by": { "description": "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", - "nullable": true, "oneOf": [ { "properties": { @@ -49562,6 +49728,11 @@ }, "required": ["columns", "kind"], "type": "object" + }, + { + "type": "object", + "nullable": true, + "enum": [null] } ] } @@ -49574,8 +49745,8 @@ "type": "string" }, "observation_status": { - "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, and unavailable when the catalog could not be read.", - "enum": ["observed", "table_missing", "unavailable"], + "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", + "enum": ["not_requested", "observed", "table_missing", "unavailable"], "type": "string" }, "observed": { @@ -49627,6 +49798,14 @@ "required": ["observed_at", "partition_by", "sort_by"], "type": "object" }, + "pipeline_id": { + "description": "Warehouse replication pipeline identity.", + "type": "string" + }, + "reset_table": { + "description": "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + "type": "boolean" + }, "schema": { "description": "Source PostgreSQL schema of the table.", "type": "string" @@ -49654,6 +49833,465 @@ }, "required": ["data"], "type": "object" + }, + "V2WarehouseTableLayoutUpdateRequest": { + "properties": { + "data": { + "properties": { + "attributes": { + "additionalProperties": false, + "properties": { + "partition_by": { + "description": "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + "items": { + "additionalProperties": false, + "properties": { + "column": { + "description": "Source column name.", + "minLength": 1, + "type": "string" + }, + "transform": { + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["identity"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["year"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["month"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["day"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["hour"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "count": { + "description": "Number of hash buckets.", + "exclusiveMinimum": true, + "maximum": 2147483647, + "minimum": 0, + "type": "integer" + }, + "kind": { + "enum": ["bucket"], + "type": "string" + } + }, + "required": ["count", "kind"], + "type": "object" + } + ] + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "nullable": true, + "type": "array" + }, + "reset_table": { + "description": "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + "type": "boolean" + }, + "sort_by": { + "description": "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["none"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["primary_key"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "columns": { + "items": { + "additionalProperties": false, + "properties": { + "direction": { + "enum": ["asc", "desc"], + "type": "string" + }, + "name": { + "description": "Source column name.", + "minLength": 1, + "type": "string" + }, + "nulls": { + "description": "Null placement. Null uses DuckLake's default placement.", + "enum": ["first", "last", null], + "nullable": true, + "type": "string" + } + }, + "required": ["direction", "name"], + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "kind": { + "enum": ["columns"], + "type": "string" + } + }, + "required": ["columns", "kind"], + "type": "object" + }, + { + "type": "object", + "nullable": true, + "enum": [null] + } + ] + } + }, + "type": "object" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table_layout"], + "type": "string" + } + }, + "required": ["attributes", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "V2WarehouseTableLayoutUpdateResponse_Output": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "application_status": { + "description": "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + "type": "string" + }, + "desired": { + "description": "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", + "properties": { + "partition_by": { + "description": "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", + "items": { + "properties": { + "column": { + "description": "Source column name.", + "type": "string" + }, + "transform": { + "oneOf": [ + { + "properties": { + "kind": { + "enum": ["identity"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["year"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["month"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["day"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["hour"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "count": { + "description": "Number of hash buckets.", + "exclusiveMinimum": true, + "maximum": 2147483647, + "minimum": 0, + "type": "integer" + }, + "kind": { + "enum": ["bucket"], + "type": "string" + } + }, + "required": ["count", "kind"], + "type": "object" + } + ] + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "nullable": true, + "type": "array" + }, + "sort_by": { + "description": "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", + "oneOf": [ + { + "properties": { + "kind": { + "enum": ["none"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "kind": { + "enum": ["primary_key"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "properties": { + "columns": { + "items": { + "properties": { + "direction": { + "enum": ["asc", "desc"], + "type": "string" + }, + "name": { + "description": "Source column name.", + "type": "string" + }, + "nulls": { + "description": "Null placement. Null uses DuckLake's default placement.", + "enum": ["first", "last", null], + "nullable": true, + "type": "string" + } + }, + "required": ["direction", "name", "nulls"], + "type": "object" + }, + "type": "array" + }, + "kind": { + "enum": ["columns"], + "type": "string" + } + }, + "required": ["columns", "kind"], + "type": "object" + }, + { + "type": "object", + "nullable": true, + "enum": [null] + } + ] + } + }, + "required": ["partition_by", "sort_by"], + "type": "object" + }, + "name": { + "description": "Source PostgreSQL table name.", + "type": "string" + }, + "observation_status": { + "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", + "enum": ["not_requested", "observed", "table_missing", "unavailable"], + "type": "string" + }, + "observed": { + "description": "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", + "nullable": true, + "properties": { + "observed_at": { + "description": "Time the catalog metadata was read.", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "type": "string" + }, + "partition_by": { + "description": "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", + "items": { + "properties": { + "column": { + "type": "string" + }, + "transform": { + "type": "string" + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "type": "array" + }, + "sort_by": { + "description": "Active sort expressions in key order, as the catalog reports them.", + "items": { + "properties": { + "direction": { + "type": "string" + }, + "expression": { + "type": "string" + }, + "nulls": { + "type": "string" + } + }, + "required": ["direction", "expression", "nulls"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["observed_at", "partition_by", "sort_by"], + "type": "object" + }, + "pipeline_id": { + "description": "Warehouse replication pipeline identity.", + "type": "string" + }, + "reset_table": { + "description": "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + "type": "boolean" + }, + "schema": { + "description": "Source PostgreSQL schema of the table.", + "type": "string" + } + }, + "required": [ + "application_status", + "desired", + "name", + "observation_status", + "observed", + "pipeline_id", + "reset_table", + "schema" + ], + "type": "object" + }, + "id": { + "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", + "example": "16385", + "maxLength": 10, + "pattern": "^[1-9]\\d*$", + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_table_layout"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index 85ddcad1f1..a2feddfdf0 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -453,4 +453,8 @@ export const operationPermissions: Readonly "v2-list-warehouse-tables": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-get-warehouse-table": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-get-warehouse-table-layout": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-update-warehouse-table-layout": { + fga: [["database_write", "project_admin_write"]], + oauthScope: "database:write", + }, }; From 9849943e12164c11ba8a86e7b9fbef51e693dac5 Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Thu, 19 Nov 2026 11:56:30 +0100 Subject: [PATCH 25/45] feat(cli): add warehouse inspect query-stats (#7708) Add the experimental `supabase warehouse inspect query-stats` command, stacked on #7640. ```sh supabase warehouse inspect query-stats --remote --since 30m ``` Generate the command from the public Management API contract. Support `--from`/`--to`, `--attributes`, and `--interval`. Use the shared output contract: text on a terminal, JSON when piped, and explicit JSON/YAML/pretty output. Text preserves nested ranges, labels, and sample values, with the last 10 items of each nested array and an omission notice. JSON/YAML retain the complete response, including null samples and unknown fields. Range validation and metric semantics remain server-owned. The shared renderer also retains nested fields in other generated resource collections. Closes PIPE-1461. --------- Co-authored-by: Julien Goux --- .../command-surface.integration.test.ts | 28 ++ apps/cli/src/commands/api/SIDE_EFFECTS.md | 16 +- .../api-command-bindings.integration.test.ts | 2 + .../src/commands/api/api-command-policy.ts | 2 + .../src/commands/api/api-command.format.ts | 81 +++- .../api/api-command.format.unit.test.ts | 31 ++ .../src/commands/api/api-commands.e2e.test.ts | 35 ++ .../api/api-commands.integration.test.ts | 270 ++++++++++- apps/cli/src/commands/api/generated.md | 20 + .../cli/src/commands/api/generated.schemas.ts | 237 ++++++++++ apps/cli/src/commands/api/generated.ts | 96 ++++ packages/api/scripts/openapi-overrides.json | 428 ++++++++++++++++++ packages/api/src/generated/contracts.ts | 206 +++++++++ packages/api/src/generated/effect-client.ts | 16 + packages/api/src/generated/openapi.json | 418 +++++++++++++++++ packages/api/src/generated/permissions.ts | 1 + 16 files changed, 1845 insertions(+), 42 deletions(-) diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index c76d733b63..ace075fa52 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -57,6 +57,8 @@ describe("command surface", () => { "warehouse connection", "warehouse disable", "warehouse enable", + "warehouse inspect", + "warehouse inspect query-stats", "warehouse status", "warehouse tables", "warehouse tables get", @@ -80,6 +82,32 @@ describe("command surface", () => { }), ); + it.effect( + "mounts workload inspection under Warehouse and preserves standalone inspect commands", + () => + Effect.gen(function* () { + const { commands } = yield* Effect.promise(() => surface); + expect(commands).not.toHaveProperty("warehouse inspect query-stats"); + const enabled = yield* walkCommandSurface( + rootCommandForFeatures({ apiFeatures: ["warehouse"] }), + ); + for (const path of ["inspect", "inspect db", "inspect report", "inspect db table-stats"]) { + expect(enabled[path]).toEqual(commands[path]); + } + expect(enabled).not.toHaveProperty("inspect warehouse"); + const stats = enabled["warehouse inspect query-stats"]; + expect(stats).toMatchObject({ + stage: { status: "experimental", feature: "warehouse" }, + target: { group: "hosted", consent: "none" }, + api: { operationId: "v2-get-warehouse-query-stats" }, + }); + expect(Object.keys(stats?.flags ?? {})).toEqual( + expect.arrayContaining(["since", "from", "to", "attributes", "interval", "remote"]), + ); + expect(stats?.flags).not.toHaveProperty("wait"); + }), + ); + it.effect("describes layout updates without unsupported backend workflow flags", () => Effect.gen(function* () { const warehouse = yield* warehouseVariant; diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index 9d7b284931..bf9a10356e 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -148,14 +148,14 @@ Text rendering applies on a terminal by default, with `--output-format text` (al with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the API's JSON bytes. `-o` takes precedence over `--output-format`. -| Mode | stdout | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| text presentation | the response as labelled fields and tables, nested objects as indented blocks (a collection table omits a column holding nested values; `-o json` shows them), `-` for null or empty values; with `--wait` the final read response; an empty response prints `Done.` and an empty collection `No results` | -| JSON presentation | the API's JSON response bytes, unchanged, preserving unknown and null fields; with `--wait` the final read response | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | -| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | +| Mode | stdout | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| text presentation | the response as labelled fields and tables, nested objects as indented blocks; a collection prints its scalar fields as a table, with each item's nested fields, null shown as `-`, in a block below it, and a `points` sample series shows its last 10 samples in response order with an omission notice (`-o json` shows all of them), `-` for null or empty values; with `--wait` the final read response; an empty response prints `Done.` and an empty collection `No results` | +| JSON presentation | the API's JSON response bytes, unchanged, preserving unknown and null fields; with `--wait` the final read response | +| `-o json` | the same bytes; no `target` key is added | +| `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | +| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | +| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 81dfab7541..dde6292d6b 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -115,6 +115,7 @@ const shapeOf = (schema: unknown): unknown => { }; const PATTERN_SAMPLES: Readonly> = { + "^[1-9]\\d*(s|m|h|d)$": "30m", "^[a-f0-9]{64}$": "ab".repeat(32), "^[a-z]+$": "zyxwvutsrqponmlkjihg", "^[1-9]\\d*$": "16385", @@ -136,6 +137,7 @@ const sampleOf = (schema: unknown): unknown => { case "array": return [sampleOf(node["items"]), `${String(sampleOf(node["items"]))}-2`]; case "string": { + if (node["format"] === "date-time") return "2026-11-18T10:00:00Z"; const pattern = node["pattern"]; if (pattern === undefined) return "sample"; const sample = typeof pattern === "string" ? PATTERN_SAMPLES[pattern] : undefined; diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index e1f6637cd5..44421ab146 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -24,6 +24,7 @@ export const generatedOperations: ReadonlyArray = [ "v2-get-warehouse-table", "v2-get-warehouse-table-layout", "v2-update-warehouse-table-layout", + "v2-get-warehouse-query-stats", ]; export const nouns = { @@ -31,6 +32,7 @@ export const nouns = { description: "Manage the data warehouse for a project", feature: "warehouse", groups: { + inspect: "Inspect Warehouse workload metrics", tables: "Inspect tables replicated to Warehouse", "tables.layout": "Inspect and update the layout of tables replicated to Warehouse", teardowns: "Inspect Warehouse cleanup operations", diff --git a/apps/cli/src/commands/api/api-command.format.ts b/apps/cli/src/commands/api/api-command.format.ts index 32c33f7ca1..950ac967f7 100644 --- a/apps/cli/src/commands/api/api-command.format.ts +++ b/apps/cli/src/commands/api/api-command.format.ts @@ -2,6 +2,8 @@ import { renderGlamourTable } from "../../output/glamour-table.ts"; import type { ApiRequestPreview } from "./api-command-request.ts"; const INDENT = " "; +const SAMPLE_SERIES_KEY = "points"; +const SAMPLE_PREVIEW_LIMIT = 10; const ACRONYMS: ReadonlySet = new Set(["id", "url", "fdw", "dns", "api", "sql", "tls"]); type JsonObject = Readonly>; @@ -86,30 +88,29 @@ const inlineText = (value: unknown): string | undefined => { if (Array.isArray(value)) { if (value.length === 0) return "-"; if (value.every(isScalar)) return value.map(scalarText).join(", "); - return isObjectArray(value) ? undefined : compactJson(value); + return undefined; } return isObject(value) && Object.keys(value).length > 0 ? undefined : "-"; }; const blockLines = (entries: ReadonlyArray, indent: string) => { - const rows = entries.map(([key, value]) => ({ - label: humanize(key), - value, - inline: inlineText(value), - })); + const rows = entries.map(([key, value]) => { + const series = key === SAMPLE_SERIES_KEY && Array.isArray(value) && value.length > 0; + return { label: humanize(key), value, series, inline: series ? undefined : inlineText(value) }; + }); const width = Math.max( 0, ...rows.flatMap((row) => (row.inline === undefined ? [] : [row.label.length])), ); const lines: Array = []; - for (const { label, value, inline } of rows) { + for (const { label, value, series, inline } of rows) { if (inline !== undefined) { lines.push(`${indent}${label.padEnd(width)}${INDENT}${inline}`); continue; } lines.push(`${indent}${label}`); - if (isObjectArray(value)) { - lines.push(...objectTable(value, unionKeys(value), indent)); + if (Array.isArray(value)) { + lines.push(...arrayLines(value, indent, series ? SAMPLE_PREVIEW_LIMIT : value.length)); } else if (isObject(value)) { lines.push(...blockLines(Object.entries(value), `${indent}${INDENT}`)); } @@ -117,6 +118,42 @@ const blockLines = (entries: ReadonlyArray, indent: return lines; }; +const isFlatObjectArray = (value: unknown): value is ReadonlyArray => + isObjectArray(value) && value.every((item) => Object.values(item).every(isScalar)); + +/** Sample series under a `points` key keep only their last samples in response order; other arrays render whole. */ +const arrayLines = ( + items: ReadonlyArray, + indent: string, + limit: number, +): ReadonlyArray => { + const offset = Math.max(0, items.length - limit); + const preview = items.slice(offset); + const notice = + offset === 0 + ? [] + : [ + `${indent}${INDENT}Showing last ${preview.length} of ${items.length} samples; ${offset} omitted; use -o json for all samples.`, + ]; + if (isFlatObjectArray(preview)) { + return [...notice, ...objectTable(preview, unionKeys(preview), indent)]; + } + if (preview.every(isScalar)) + return [...notice, `${indent}${INDENT}${preview.map(scalarText).join(", ")}`]; + return [ + ...notice, + ...preview.flatMap((item, index) => { + const label = `Item ${offset + index + 1}`; + return isObject(item) + ? [ + `${indent}${INDENT}${label}`, + ...blockLines(Object.entries(item), `${indent}${INDENT}${INDENT}`), + ] + : blockLines([[label, item]], `${indent}${INDENT}`); + }), + ]; +}; + const isResource = (value: unknown): value is JsonObject & { readonly attributes: JsonObject } => isObject(value) && typeof value["type"] === "string" && isObject(value["attributes"]); @@ -138,11 +175,25 @@ const resourceLines = (document: JsonObject): ReadonlyArray | undefined } if (Array.isArray(data) && data.every(isResource)) { const rows = data.map((resource) => Object.fromEntries(resourceEntries(resource))); - const columns = unionKeys(rows).filter( - (column) => - rows.every((row) => isScalar(row[column])) && rows.some((row) => row[column] !== undefined), + const columns = unionKeys(rows).filter((column) => + rows.some((row) => row[column] !== undefined), ); - return [humanize(String(data[0]?.["type"])), ...objectTable(rows, columns, "")]; + const nested = new Set(columns.filter((column) => rows.some((row) => !isScalar(row[column])))); + const summary = columns.filter((column) => !nested.has(column)); + const details = data.flatMap((resource, index) => { + const entries = resourceEntries(resource).filter( + ([key, value]) => nested.has(key) && value !== undefined, + ); + if (entries.length === 0) return []; + const id = resource["id"]; + const name = id === undefined || id === null ? `item ${index + 1}` : scalarText(id); + return ["", `${humanize(String(resource["type"]))} ${name}`, ...blockLines(entries, INDENT)]; + }); + return [ + humanize(String(data[0]?.["type"])), + ...(summary.length === 0 ? [] : objectTable(rows, summary, "")), + ...details, + ]; } return undefined; }; @@ -153,8 +204,8 @@ export const renderResponseText = (value: unknown): string => { const lines = resourceLines(value) ?? blockLines(Object.entries(value), ""); return `${(lines.length === 0 ? ["-"] : lines).join("\n")}\n`; } - if (isObjectArray(value)) { - return `${objectTable(value, unionKeys(value), "").join("\n")}\n`; + if (Array.isArray(value) && value.length > 0) { + return `${arrayLines(value, "", value.length).join("\n")}\n`; } return `${inlineText(value) ?? compactJson(value)}\n`; }; diff --git a/apps/cli/src/commands/api/api-command.format.unit.test.ts b/apps/cli/src/commands/api/api-command.format.unit.test.ts index c8fb7997b5..01089d8cb7 100644 --- a/apps/cli/src/commands/api/api-command.format.unit.test.ts +++ b/apps/cli/src/commands/api/api-command.format.unit.test.ts @@ -37,4 +37,35 @@ describe("renderResponseText", () => { it("prints a clear line for an empty resource collection", () => { expect(renderResponseText({ data: [] })).toBe("No results\n"); }); + + it.each([ + { name: "scalar", item: (index: number): unknown => `sample-${index}` }, + { name: "object", item: (index: number): unknown => ({ value: `sample-${index}` }) }, + ])("shows the last 10 $name samples of a points series in response order", ({ item }) => { + const points = Array.from({ length: 12 }, (_, index) => item(index)); + const output = renderResponseText({ points }); + expect(output).not.toMatch(/sample-[01]\b/); + expect(output.indexOf("sample-2")).toBeGreaterThanOrEqual(0); + expect(output.indexOf("sample-2")).toBeLessThan(output.indexOf("sample-11")); + expect(output).toContain( + "Showing last 10 of 12 samples; 2 omitted; use -o json for all samples.", + ); + expect(renderResponseText({ points: points.slice(2) })).not.toContain("omitted"); + }); + + it("bounds points series nested inside a top-level array of objects", () => { + const points = Array.from({ length: 12 }, (_, index) => `point-${index}`); + const output = renderResponseText([{ points }]); + expect(output).not.toMatch(/point-[01]\b/); + expect(output).toContain("point-11"); + expect(output).toContain("2 omitted"); + }); + + it("renders every item of an array that is not a points series", () => { + const tables = Array.from({ length: 12 }, (_, index) => ({ name: `table-${index}` })); + const output = renderResponseText({ tables }); + expect(output).toContain("table-0"); + expect(output).toContain("table-11"); + expect(output).not.toContain("omitted"); + }); }); diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index 0523763eb7..ad934d25e2 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -1,5 +1,6 @@ import { BunServices } from "@effect/platform-bun"; import { expect, it } from "@effect/vitest"; +import type { OperationOutput } from "@supabase/api/effect"; import { Data, Effect, FileSystem, Path, Schema } from "effect"; import { makeTempHome, requireCliSuccess, runSupabaseEffect } from "../../../tests/helpers/cli.ts"; @@ -106,6 +107,40 @@ const runWarehouse = ( return { result, requests, bodies }; }).pipe(Effect.scoped); +it.live("warehouse inspect query-stats reaches the public route through the compiled CLI", () => + Effect.gen(function* () { + const response = json(200, { + data: [ + { + type: "warehouse_metric", + id: "query_rate", + attributes: { + project_ref: REF, + metric: "query_rate", + unit: "per_second", + aggregation: "rate", + definition: "Query invocations per second.", + requested: { metric: "query_rate", start: 1795000000, end: 1795001800 }, + effective: { start: 1795000000, end: 1795001800, step: 60, rate_window_seconds: 300 }, + scrape_interval_seconds: 60, + last_sample_at: null, + availability: "unavailable", + series: [], + }, + }, + ], + } satisfies OperationOutput<"v2GetWarehouseQueryStats">); + const { result, requests } = yield* runWarehouse( + ["inspect", "query-stats", "--since", "30m"], + () => response, + ); + + requireCliSuccess(result, "warehouse inspect query-stats"); + expect(result.stdout, result.stderr).toBe(response.body); + expect(requests).toEqual([`GET /v2/projects/${REF}/warehouse/query-stats`]); + }).pipe(Effect.provide(BunServices.layer)), +); + it.live("warehouse status reports a 409 as a conflict failure document on stderr", () => Effect.gen(function* () { const { result } = yield* runWarehouse(["status", "-o", "json"], () => diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 5f89dd0c92..c4a75b4e2e 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -1,5 +1,7 @@ import { BunServices } from "@effect/platform-bun"; import { describe, expect, it } from "@effect/vitest"; +import type { OperationOutput } from "@supabase/api/effect"; +import { parse as parseYaml } from "yaml"; import { Cause, Console, @@ -306,26 +308,50 @@ const driveClock = (fiber: Fiber.Fiber) => describe("generated warehouse commands", () => { describe("consolidated warehouse status", () => { + const attributes = { + project_ref: VALID_REF, + enabled: true, + status: "degraded", + configured_readiness: "not_ready", + query_connectivity: "not_checked", + observed_at: "2026-11-17T10:00:00Z", + compute: { + status: "available", + region: "us-east-1", + routing_status: "ready", + unavailable_reason: null, + observed_at: "2026-11-17T10:00:00Z", + }, + lifecycle: null, + pipeline: null, + tables: { + status: "available", + unavailable_reason: null, + observed_at: "2026-11-17T10:00:00Z", + items: [], + }, + replication: { + status: "unavailable", + unavailable_reason: "observation_unavailable", + observed_at: null, + apply_lag: null, + }, + capabilities: { + context: true, + query_explain: false, + replication_add: false, + replication_remove: true, + table_layout_read: true, + table_layout_update: false, + table_resync: false, + workload_metrics: true, + }, + } satisfies OperationOutput<"v2GetWarehouseStatus">["data"]["attributes"]; const body = { data: { type: "warehouse_context", id: VALID_REF, - attributes: { - enabled: true, - status: "degraded", - configured_readiness: "not_ready", - query_connectivity: "not_checked", - observed_at: "2026-11-17T10:00:00Z", - tables: { status: "available", items: [] }, - replication: { - status: "unavailable", - unavailable_reason: "observation_unavailable", - observed_at: null, - apply_lag: null, - }, - capabilities: { replication_add: false, replication_remove: true, table_resync: false }, - future_field: { retained: true }, - }, + attributes: { ...attributes, future_field: { retained: true } }, }, }; @@ -368,7 +394,45 @@ describe("generated warehouse commands", () => { expect(out.stdoutText).toMatch(/Observed at\s+2026-11-17T10:00:00Z/); }); }); + + it.effect("lists every table of a large warehouse in terminal output", () => { + const items = Array.from({ length: 12 }, (_, index) => ({ + id: 20000 + index, + schema: "public", + name: `table_${index}`, + replication_state: index === 0 ? ("error" as const) : ("following_wal" as const), + sync_lag: + index === 1 + ? { + active: true, + feedback_age_ms: 5, + flush_lag_bytes: 2048, + flush_lag_ms: 120, + wal_status: "reserved" as const, + write_lag_ms: 80, + } + : null, + })) satisfies OperationOutput<"v2GetWarehouseStatus">["data"]["attributes"]["tables"]["items"]; + const { out, run } = setup(["warehouse", "status"], { + route: ok({ + data: { + ...body.data, + attributes: { ...attributes, tables: { ...attributes.tables, items } }, + }, + }), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toMatch( + /ID\s+20000\n\s+Schema\s+public\n\s+Name\s+table_0\n\s+Replication state\s+error\n/, + ); + for (const item of items) expect(out.stdoutText).toContain(String(item.id)); + expect(out.stdoutText).not.toContain("omitted"); + }); + }); }); + describe("warehouse tables list", () => { const tablesPath = `/v2/projects/${VALID_REF}/warehouse/tables`; const table = (attributes: Readonly>) => ({ @@ -410,7 +474,7 @@ describe("generated warehouse commands", () => { ], }; - it.effect("renders one row per table without the nested replication feedback", () => { + it.effect("lists tables in one row each with replication feedback in a block below", () => { const { out, sent, run } = setup(["warehouse", "tables", "list"], { route: ok(body), stdoutIsTty: true, @@ -420,7 +484,9 @@ describe("generated warehouse commands", () => { expect(sent).toEqual([{ method: "GET", path: tablesPath, search: "", body: undefined }]); expect(out.stdoutText).toMatch(/16385\s.*orders.*live.*following_wal.*120/); expect(out.stdoutText).toMatch(/16402\s.*events.*syncing.*copying_table/); - expect(out.stdoutText).not.toMatch(/pipeline_apply|feedback_age|FEEDBACK/i); + expect(out.stdoutText).toMatch(/Warehouse table 16385\n[\s\S]*Source\s+pipeline_apply/); + expect(out.stdoutText).toMatch(/Feedback age ms\s+5/); + expect(out.stdoutText).toMatch(/Warehouse table 16402\n\s+Replication feedback\s+-\n/); }); }); @@ -434,6 +500,151 @@ describe("generated warehouse commands", () => { }); }); }); + describe("warehouse inspect query-stats", () => { + const argv = ["warehouse", "inspect", "query-stats"]; + const attributes = { + project_ref: VALID_REF, + metric: "query_duration_p95", + unit: "seconds", + aggregation: "p95", + definition: + "Executor duration through terminal outcome, including assignment wait and streaming.", + requested: { metric: "query_duration_p95", start: 1795000000, end: 1795001800 }, + effective: { start: 1795000000, end: 1795001800, step: 60, rate_window_seconds: 300 }, + scrape_interval_seconds: 60, + last_sample_at: 1795001740, + availability: "partial", + series: [ + { + labels: { method: "DoGet", status: "ok" }, + points: [ + { timestamp: 1795001740, value: 0.2 }, + { timestamp: 1795001800, value: null }, + ], + coverage: { returned_points: 1, expected_points: 2 }, + }, + ], + } satisfies OperationOutput<"v2GetWarehouseQueryStats">["data"][number]["attributes"]; + const response = { + data: [ + { + type: "warehouse_metric", + id: "query_duration_p95", + attributes: { ...attributes, future_observation: { reason: null } }, + }, + ], + }; + + it.effect("shows the last 10 samples of a long series with an omission notice", () => { + const points = Array.from({ length: 12 }, (_, index) => ({ + timestamp: 1795001000 + index * 60, + value: 1001 + index, + })); + const [first] = response.data; + const [firstSeries] = attributes.series; + const { out, run } = setup(argv, { + route: ok({ + data: [ + { + ...first, + attributes: { + ...first?.attributes, + series: [ + { + ...firstSeries, + points, + coverage: { returned_points: 12, expected_points: 12 }, + }, + ], + }, + }, + ], + }), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toContain( + "Showing last 10 of 12 samples; 2 omitted; use -o json for all samples.", + ); + expect(out.stdoutText).not.toContain("1001"); + expect(out.stdoutText).not.toContain("1002"); + expect(out.stdoutText).toContain("1003"); + expect(out.stdoutText).toContain("1012"); + }); + }); + + it.effect("forwards a relative range and preserves the full JSON response", () => { + const { sent, out, run } = setup( + [ + ...argv, + "--since", + "30m", + "--attributes", + "query_rate,query_duration_p95", + "--interval", + "5m", + "-o", + "json", + ], + { + route: ok(response), + stdoutIsTty: true, + }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toHaveLength(1); + expect(sent[0]).toMatchObject({ + method: "GET", + path: `/v2/projects/${VALID_REF}/warehouse/query-stats`, + body: undefined, + }); + expect(Object.fromEntries(new URLSearchParams(sent[0]?.search))).toEqual({ + since: "30m", + attributes: "query_rate,query_duration_p95", + interval: "5m", + }); + expect(decodeJson(out.stdoutText)).toEqual(response); + }); + }); + + it.effect("forwards fixed timestamps unchanged and preserves null samples in YAML", () => { + const from = "2026-11-18T09:30:00+01:00"; + const to = "2026-11-18T10:00:00+01:00"; + const { sent, out, run } = setup([...argv, "--from", from, "--to", to, "-o", "yaml"], { + route: ok(response), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(Object.fromEntries(new URLSearchParams(sent[0]?.search))).toEqual({ from, to }); + expect(parseYaml(out.stdoutText)).toEqual(response); + }); + }); + + it.effect.each([ + { name: "terminal default", flags: [], stdoutIsTty: true }, + { name: "explicit text", flags: ["--output-format", "text"], stdoutIsTty: false }, + { name: "pretty alias", flags: ["-o", "pretty"], stdoutIsTty: false }, + ])("shows ranges, dimensions, and sample values with $name", ({ flags, stdoutIsTty }) => { + const { out, run } = setup([...argv, ...flags], { + route: ok(response), + stdoutIsTty, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toContain("query_duration_p95"); + expect(out.stdoutText).toContain("partial"); + expect(out.stdoutText).toMatch(/Requested[\s\S]*1795000000/); + expect(out.stdoutText).toMatch(/Effective[\s\S]*Rate window seconds\s+300/); + expect(out.stdoutText).toMatch(/Method\s+DoGet/); + expect(out.stdoutText).toMatch(/1795001740\s*[|│]?\s*0\.2/); + expect(out.stdoutText).toMatch(/1795001800\s*[|│]?\s*-/); + expect(out.stdoutText.trimStart().startsWith("{")).toBe(false); + }); + }); + }); describe("warehouse tables get", () => { const tablePath = `/v2/projects/${VALID_REF}/warehouse/tables/16385`; const body = { @@ -513,7 +724,7 @@ describe("generated warehouse commands", () => { expect(sent).toEqual([{ method: "GET", path: layoutPath, search: "", body: undefined }]); expect(out.stdoutText).toMatch(/^Warehouse table layout\n/); expect(out.stdoutText).toMatch(/Desired\n\s+Sort by\s+-\n/); - expect(out.stdoutText).toMatch(/account_id \| \{"kind":"bucket","count":16\}/); + expect(out.stdoutText).toMatch(/Column\s+account_id[\s\S]*Kind\s+bucket[\s\S]*Count\s+16/); expect(out.stdoutText).toMatch(/Observation status\s+observed/); expect(out.stdoutText).toMatch(/account_id \| bucket\(16\)/); expect(out.stdoutText).toMatch(/Observed at\s+2026-11-18T09:30:00\.123456Z/); @@ -1850,6 +2061,24 @@ describe("generated warehouse commands", () => { args: ["__complete", "ware"], features: ["warehouse"], }, + { name: "inspection parent help", args: ["inspect"], features: [] }, + { + name: "Warehouse inspection", + args: ["warehouse", "inspect", "query-stats"], + features: ["warehouse"], + }, + { name: "database inspection", args: ["inspect", "db", "table-stats"], features: [] }, + { name: "inspection report", args: ["inspect", "report"], features: [] }, + { + name: "inspection completion", + args: ["__complete", "inspect", ""], + features: [], + }, + { + name: "database inspection completion", + args: ["__complete", "inspect", "db", ""], + features: [], + }, { name: "a command of another group", args: ["projects", "list"], features: [] }, { name: "completion of another group", args: ["__complete", "projects", ""], features: [] }, { name: "the root version flag", args: ["--version"], features: [] }, @@ -1864,6 +2093,9 @@ describe("generated warehouse commands", () => { Effect.gen(function* () { const env = { SUPABASE_EXPERIMENTAL_WAREHOUSE: "maybe" }; expect(yield* resolve(env, tempRoot.current, ["projects", "list"])).toEqual([]); + expect(yield* resolve(env, tempRoot.current, ["inspect"])).toEqual([]); + expect(yield* resolve(env, tempRoot.current, ["inspect", "db", "table-stats"])).toEqual([]); + expect(yield* resolve(env, tempRoot.current, ["inspect", "report"])).toEqual([]); }), ); diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index dd83ee349f..3e21bb3db0 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -67,6 +67,26 @@ Enables replication for the currently eligible tables in a schema, or the named - Failure message from `/data/attributes/status_error`. - Failure hint names `supabase warehouse status --remote=`. +## `supabase warehouse inspect query-stats` + +Inspect Warehouse workload query statistics + +Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results. + +- Access: read-only, no consent. +- Feature: `warehouse`. +- Request: `GET /v2/projects/{ref}/warehouse/query-stats` (`v2-get-warehouse-query-stats`), success 200 json. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| --------------------------- | --------------------------------------------- | -------- | ---------- | ------------------ | +| `--attributes ` | string | no | no | query `attributes` | +| `--from ` | string | no | no | query `from` | +| `--interval ` | string (`10m`, `1d`, `1h`, `1m`, `30m`, `5m`) | no | no | query `interval` | +| `--since ` | string | no | no | query `since` | +| `--to ` | string | no | no | query `to` | + ## `supabase warehouse status` Get consolidated Warehouse status and capabilities diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index af39c4086d..259740bc14 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -417,6 +417,243 @@ export const apiCommandSchemas = { type: "object", }, }, + "v2-get-warehouse-query-stats": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + items: { + properties: { + attributes: { + properties: { + aggregation: { + enum: ["mean", "occupied", "p50", "p95", "p99", "rate", "sum"], + type: "string", + }, + availability: { + enum: [ + "disabled", + "insufficient_data", + "no_data", + "not_provisioned", + "ok", + "partial", + "stale", + "unavailable", + ], + type: "string", + }, + definition: { + type: "string", + }, + effective: { + properties: { + end: { + type: "number", + }, + rate_window_seconds: { + type: "number", + }, + start: { + type: "number", + }, + step: { + type: "number", + }, + }, + required: ["end", "rate_window_seconds", "start", "step"], + type: "object", + }, + last_sample_at: { + description: + "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", + type: ["number", "null"], + }, + metric: { + enum: [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ], + type: "string", + }, + project_ref: { + type: "string", + }, + requested: { + properties: { + end: { + type: "number", + }, + metric: { + enum: [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ], + type: "string", + }, + start: { + type: "number", + }, + step: { + type: "number", + }, + }, + required: ["end", "metric", "start"], + type: "object", + }, + scrape_interval_seconds: { + type: "number", + }, + series: { + items: { + properties: { + coverage: { + description: + "Grid point coverage, not proof that every worker was scraped.", + properties: { + expected_points: { + type: "number", + }, + returned_points: { + type: "number", + }, + }, + required: ["expected_points", "returned_points"], + type: "object", + }, + labels: { + additionalProperties: { + type: "string", + }, + type: "object", + }, + points: { + items: { + properties: { + timestamp: { + type: "number", + }, + value: { + type: ["number", "null"], + }, + }, + required: ["timestamp", "value"], + type: "object", + }, + type: "array", + }, + }, + required: ["coverage", "labels", "points"], + type: "object", + }, + type: "array", + }, + unit: { + enum: ["grants", "per_second", "queries", "seconds"], + type: "string", + }, + }, + required: [ + "aggregation", + "availability", + "definition", + "effective", + "last_sample_at", + "metric", + "project_ref", + "requested", + "scrape_interval_seconds", + "series", + "unit", + ], + type: "object", + }, + id: { + enum: [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ], + type: "string", + }, + type: { + description: "Resource type.", + enum: ["warehouse_metric"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + type: "array", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-get-warehouse-setup": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 9a320f0442..0a5793dae4 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -190,6 +190,102 @@ export const apiCommands = [ error: "/data/attributes/status_error", }, }, + { + command: ["warehouse", "inspect", "query-stats"], + operationId: "v2-get-warehouse-query-stats", + definition: "v2GetWarehouseQueryStats", + method: "GET", + apiPath: "/v2/projects/{ref}/warehouse/query-stats", + summary: "Inspect Warehouse workload query statistics", + description: + "Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.", + readOnly: true, + feature: "warehouse", + response: { + status: 200, + kind: "json", + }, + flags: [ + { + name: "attributes", + type: "string", + repeatable: false, + required: false, + description: + "Up to eight distinct workload measurements. Defaults to invocation rate, latency p50/p95/p99, error rate, and timeout rate. Supply a comma-separated list. Allowed measurements: query_rate, query_error_rate, query_timeout_rate, query_canceled_rate, query_duration_mean, query_duration_p50, query_duration_p95, query_duration_p99, duckdb_duration_mean, rpc_rate, rpc_duration_mean, rpc_duration_p95.", + }, + { + name: "from", + type: "string", + repeatable: false, + required: false, + description: + "Range start as an ISO timestamp, within the last 30 days. Requires to; cannot be combined with since.", + }, + { + name: "interval", + type: "string", + choices: ["10m", "1d", "1h", "1m", "30m", "5m"], + repeatable: false, + required: false, + description: + "Defaults to 1m. The effective step increases to stay within 1441 points per series. Rate and latency windows are at least 5m.", + }, + { + name: "since", + type: "string", + repeatable: false, + required: false, + description: + "Look back from server time, for example 30m, 2h, or 1d. Defaults to 30m when from/to are omitted. Maximum 30d. Cannot be combined with from/to.", + }, + { + name: "to", + type: "string", + repeatable: false, + required: false, + description: + "Range end as an ISO timestamp, no later than server time. Requires from; cannot be combined with since. The service tolerates up to 60 seconds of request delay or clock skew.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "query", + name: "attributes", + source: "flag", + flag: "attributes", + }, + { + location: "query", + name: "from", + source: "flag", + flag: "from", + }, + { + location: "query", + name: "interval", + source: "flag", + flag: "interval", + }, + { + location: "query", + name: "since", + source: "flag", + flag: "since", + }, + { + location: "query", + name: "to", + source: "flag", + flag: "to", + }, + ], + }, { command: ["warehouse", "status"], operationId: "v2-get-warehouse-status", diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index d81a2b35e1..5c022cc142 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -2528,5 +2528,433 @@ "type": "object" }, "$comment": "Layout updates return orchestration fields that older layout reads do not include." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseQueryStatsResponse_Output", + "value": { + "properties": { + "data": { + "items": { + "properties": { + "attributes": { + "properties": { + "aggregation": { + "enum": ["mean", "occupied", "p50", "p95", "p99", "rate", "sum"], + "type": "string" + }, + "availability": { + "enum": [ + "disabled", + "insufficient_data", + "no_data", + "not_provisioned", + "ok", + "partial", + "stale", + "unavailable" + ], + "type": "string" + }, + "definition": { + "type": "string" + }, + "effective": { + "properties": { + "end": { + "type": "number" + }, + "rate_window_seconds": { + "type": "number" + }, + "start": { + "type": "number" + }, + "step": { + "type": "number" + } + }, + "required": ["end", "rate_window_seconds", "start", "step"], + "type": "object" + }, + "last_sample_at": { + "description": "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", + "nullable": true, + "type": "number" + }, + "metric": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "project_ref": { + "type": "string" + }, + "requested": { + "properties": { + "end": { + "type": "number" + }, + "metric": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "start": { + "type": "number" + }, + "step": { + "type": "number" + } + }, + "required": ["end", "metric", "start"], + "type": "object" + }, + "scrape_interval_seconds": { + "type": "number" + }, + "series": { + "items": { + "properties": { + "coverage": { + "description": "Grid point coverage, not proof that every worker was scraped.", + "properties": { + "expected_points": { + "type": "number" + }, + "returned_points": { + "type": "number" + } + }, + "required": ["expected_points", "returned_points"], + "type": "object" + }, + "labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "points": { + "items": { + "properties": { + "timestamp": { + "type": "number" + }, + "value": { + "nullable": true, + "type": "number" + } + }, + "required": ["timestamp", "value"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["coverage", "labels", "points"], + "type": "object" + }, + "type": "array" + }, + "unit": { + "enum": ["grants", "per_second", "queries", "seconds"], + "type": "string" + } + }, + "required": [ + "aggregation", + "availability", + "definition", + "effective", + "last_sample_at", + "metric", + "project_ref", + "requested", + "scrape_interval_seconds", + "series", + "unit" + ], + "type": "object" + }, + "id": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_metric"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "Warehouse workload metrics are not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1query-stats", + "value": { + "get": { + "description": "Returns aggregate workload measurements over a bounded time range, using the project\u2019s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-query-stats", + "parameters": [ + { + "description": "Up to eight distinct workload measurements. Defaults to invocation rate, latency p50/p95/p99, error rate, and timeout rate. Supply a comma-separated list. Allowed measurements: query_rate, query_error_rate, query_timeout_rate, query_canceled_rate, query_duration_mean, query_duration_p50, query_duration_p95, query_duration_p99, duckdb_duration_mean, rpc_rate, rpc_duration_mean, rpc_duration_p95.", + "in": "query", + "name": "attributes", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Range start as an ISO timestamp, within the last 30 days. Requires to; cannot be combined with since.", + "in": "query", + "name": "from", + "required": false, + "schema": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + }, + { + "description": "Defaults to 1m. The effective step increases to stay within 1441 points per series. Rate and latency windows are at least 5m.", + "in": "query", + "name": "interval", + "required": false, + "schema": { + "enum": ["10m", "1d", "1h", "1m", "30m", "5m"], + "type": "string" + } + }, + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Look back from server time, for example 30m, 2h, or 1d. Defaults to 30m when from/to are omitted. Maximum 30d. Cannot be combined with from/to.", + "in": "query", + "name": "since", + "required": false, + "schema": { + "pattern": "^[1-9]\\d*(s|m|h|d)$", + "type": "string" + } + }, + { + "description": "Range end as an ISO timestamp, no later than server time. Requires from; cannot be combined with since. The service tolerates up to 60 seconds of request delay or clock skew.", + "in": "query", + "name": "to", + "required": false, + "schema": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseQueryStatsResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "validation_failed: Invalid measurement selection, range, interval, or query parameter" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Project not found" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "warehouse_metrics_unavailable: Metrics query capacity is temporarily unavailable; retry after a short delay. warehouse_setup_unavailable: Warehouse feature or project metadata unavailable." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Inspect Warehouse workload query statistics", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.inspect", + "method": "query-stats" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "Public Warehouse workload metrics generate warehouse inspect query-stats." } ] diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 63581d265a..169abe1535 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -14463,6 +14463,197 @@ export const V2GetWarehouseConnectionOutput = Schema.Struct({ type: Schema.Literal("warehouse_connection").annotate({ description: "Resource type." }), }), }); +export const V2GetWarehouseQueryStatsInput = Schema.Struct({ + attributes: Schema.optionalKey(Schema.String), + from: Schema.optionalKey(Schema.String.annotate({ format: "date-time" })), + interval: Schema.optionalKey(Schema.Literals(["10m", "1d", "1h", "1m", "30m", "5m"])), + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + since: Schema.optionalKey( + Schema.String.check( + Schema.isPattern(new RegExp("^[1-9]\\d*(s|m|h|d)$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*(s|m|h|d)$", + }), + ), + ), + to: Schema.optionalKey(Schema.String.annotate({ format: "date-time" })), +}); +export const V2GetWarehouseQueryStatsOutput = Schema.Struct({ + data: Schema.Array( + Schema.Struct({ + attributes: Schema.Struct({ + aggregation: Schema.Union([ + Schema.Literals(["mean", "occupied", "p50", "p95", "p99", "rate", "sum"]), + OpenString, + ]), + availability: Schema.Union([ + Schema.Literals([ + "disabled", + "insufficient_data", + "no_data", + "not_provisioned", + "ok", + "partial", + "stale", + "unavailable", + ]), + OpenString, + ]), + definition: Schema.String, + effective: Schema.Struct({ + end: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + rate_window_seconds: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + start: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + step: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + }), + last_sample_at: Schema.Union([ + Schema.Number.annotate({ + description: + "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", + }).check(Schema.isFinite().annotate({ expected: "a finite number" })), + Schema.Null, + ]), + metric: Schema.Union([ + Schema.Literals([ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ]), + OpenString, + ]), + project_ref: Schema.String, + requested: Schema.Struct({ + end: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + metric: Schema.Union([ + Schema.Literals([ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ]), + OpenString, + ]), + start: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + step: Schema.optionalKey( + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + ), + }), + scrape_interval_seconds: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + series: Schema.Array( + Schema.Struct({ + coverage: Schema.Struct({ + expected_points: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + returned_points: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + }).annotate({ + description: "Grid point coverage, not proof that every worker was scraped.", + }), + labels: Schema.Record(Schema.String, Schema.String), + points: Schema.Array( + Schema.Struct({ + timestamp: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + value: Schema.Union([ + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + Schema.Null, + ]), + }), + ), + }), + ), + unit: Schema.Union([ + Schema.Literals(["grants", "per_second", "queries", "seconds"]), + OpenString, + ]), + }), + id: Schema.Union([ + Schema.Literals([ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ]), + OpenString, + ]), + type: Schema.Literal("warehouse_metric").annotate({ description: "Resource type." }), + }), + ), +}); export const V2GetWarehouseSetupInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -20781,6 +20972,7 @@ export const openApiOperationIdMap = { "v2-get-notebook": "v2GetNotebook", "v2-get-project-config": "v2GetProjectConfig", "v2-get-warehouse-connection": "v2GetWarehouseConnection", + "v2-get-warehouse-query-stats": "v2GetWarehouseQueryStats", "v2-get-warehouse-setup": "v2GetWarehouseSetup", "v2-get-warehouse-status": "v2GetWarehouseStatus", "v2-get-warehouse-table": "v2GetWarehouseTable", @@ -23974,6 +24166,20 @@ export const operationDefinitions = { inputSchema: V2GetWarehouseConnectionInput, outputSchema: V2GetWarehouseConnectionOutput, }, + v2GetWarehouseQueryStats: { + id: "v2GetWarehouseQueryStats", + description: + "Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/query-stats", + pathParams: ["ref"], + queryParams: ["attributes", "from", "interval", "since", "to"], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2GetWarehouseQueryStatsInput, + outputSchema: V2GetWarehouseQueryStatsOutput, + }, v2GetWarehouseSetup: { id: "v2GetWarehouseSetup", description: diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index d9740de20a..c014161cb9 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -3108,6 +3108,22 @@ export const versionedEffectOperations = { options, ); }), + getWarehouseQueryStats: ( + input: typeof operationDefinitions.v2GetWarehouseQueryStats.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2GetWarehouseQueryStats.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2GetWarehouseQueryStats">( + operationDefinitions.v2GetWarehouseQueryStats, + input, + options, + ); + }), getWarehouseSetup: ( input: typeof operationDefinitions.v2GetWarehouseSetup.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index 600907edaa..4fea2b2f5e 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -33369,6 +33369,190 @@ }, "x-scalar-stability": "experimental" } + }, + "/v2/projects/{ref}/warehouse/query-stats": { + "get": { + "description": "Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-query-stats", + "parameters": [ + { + "description": "Up to eight distinct workload measurements. Defaults to invocation rate, latency p50/p95/p99, error rate, and timeout rate. Supply a comma-separated list. Allowed measurements: query_rate, query_error_rate, query_timeout_rate, query_canceled_rate, query_duration_mean, query_duration_p50, query_duration_p95, query_duration_p99, duckdb_duration_mean, rpc_rate, rpc_duration_mean, rpc_duration_p95.", + "in": "query", + "name": "attributes", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Range start as an ISO timestamp, within the last 30 days. Requires to; cannot be combined with since.", + "in": "query", + "name": "from", + "required": false, + "schema": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + }, + { + "description": "Defaults to 1m. The effective step increases to stay within 1441 points per series. Rate and latency windows are at least 5m.", + "in": "query", + "name": "interval", + "required": false, + "schema": { + "enum": ["10m", "1d", "1h", "1m", "30m", "5m"], + "type": "string" + } + }, + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Look back from server time, for example 30m, 2h, or 1d. Defaults to 30m when from/to are omitted. Maximum 30d. Cannot be combined with from/to.", + "in": "query", + "name": "since", + "required": false, + "schema": { + "pattern": "^[1-9]\\d*(s|m|h|d)$", + "type": "string" + } + }, + { + "description": "Range end as an ISO timestamp, no later than server time. Requires from; cannot be combined with since. The service tolerates up to 60 seconds of request delay or clock skew.", + "in": "query", + "name": "to", + "required": false, + "schema": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseQueryStatsResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "validation_failed: Invalid measurement selection, range, interval, or query parameter" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Project not found" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "warehouse_metrics_unavailable: Metrics query capacity is temporarily unavailable; retry after a short delay. warehouse_setup_unavailable: Warehouse feature or project metadata unavailable." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Inspect Warehouse workload query statistics", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.inspect", + "method": "query-stats" + }, + "x-scalar-stability": "experimental" + } } }, "components": { @@ -50292,6 +50476,240 @@ }, "required": ["data"], "type": "object" + }, + "V2WarehouseQueryStatsResponse_Output": { + "properties": { + "data": { + "items": { + "properties": { + "attributes": { + "properties": { + "aggregation": { + "enum": ["mean", "occupied", "p50", "p95", "p99", "rate", "sum"], + "type": "string" + }, + "availability": { + "enum": [ + "disabled", + "insufficient_data", + "no_data", + "not_provisioned", + "ok", + "partial", + "stale", + "unavailable" + ], + "type": "string" + }, + "definition": { + "type": "string" + }, + "effective": { + "properties": { + "end": { + "type": "number" + }, + "rate_window_seconds": { + "type": "number" + }, + "start": { + "type": "number" + }, + "step": { + "type": "number" + } + }, + "required": ["end", "rate_window_seconds", "start", "step"], + "type": "object" + }, + "last_sample_at": { + "description": "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", + "nullable": true, + "type": "number" + }, + "metric": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "project_ref": { + "type": "string" + }, + "requested": { + "properties": { + "end": { + "type": "number" + }, + "metric": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "start": { + "type": "number" + }, + "step": { + "type": "number" + } + }, + "required": ["end", "metric", "start"], + "type": "object" + }, + "scrape_interval_seconds": { + "type": "number" + }, + "series": { + "items": { + "properties": { + "coverage": { + "description": "Grid point coverage, not proof that every worker was scraped.", + "properties": { + "expected_points": { + "type": "number" + }, + "returned_points": { + "type": "number" + } + }, + "required": ["expected_points", "returned_points"], + "type": "object" + }, + "labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "points": { + "items": { + "properties": { + "timestamp": { + "type": "number" + }, + "value": { + "nullable": true, + "type": "number" + } + }, + "required": ["timestamp", "value"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["coverage", "labels", "points"], + "type": "object" + }, + "type": "array" + }, + "unit": { + "enum": ["grants", "per_second", "queries", "seconds"], + "type": "string" + } + }, + "required": [ + "aggregation", + "availability", + "definition", + "effective", + "last_sample_at", + "metric", + "project_ref", + "requested", + "scrape_interval_seconds", + "series", + "unit" + ], + "type": "object" + }, + "id": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "duckdb_duration_mean", + "query_canceled_rate", + "query_duration_mean", + "query_duration_p50", + "query_duration_p95", + "query_duration_p99", + "query_error_rate", + "query_in_flight", + "query_rate", + "query_timeout_rate", + "rpc_duration_mean", + "rpc_duration_p95", + "rpc_rate", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_metric"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["data"], + "type": "object" } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index a2feddfdf0..fc787e4a6e 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -457,4 +457,5 @@ export const operationPermissions: Readonly fga: [["database_write", "project_admin_write"]], oauthScope: "database:write", }, + "v2-get-warehouse-query-stats": { fga: [["database_read"]], oauthScope: "database:read" }, }; From f8159c309e40dd4042bd5c223699d1ecf12bebc4 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 11:59:39 +0100 Subject: [PATCH 26/45] test(cli): cover hosted consent for warehouse tables layout update --- .../hosted-consent-coverage.unit.test.ts | 1 + .../api/api-commands.integration.test.ts | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts b/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts index 010f20f7d7..8255dc584e 100644 --- a/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts +++ b/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts @@ -137,6 +137,7 @@ describe("hosted consent coverage", () => { "vanity-subdomains delete": "no", "warehouse disable": "no", "warehouse enable": "no", + "warehouse tables layout update": "no", } `); }); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index c4a75b4e2e..30d025ad29 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -2142,3 +2142,21 @@ describeHostedConsent("warehouse disable", { }; }, }); + +const layoutUpdateConsentCommand = commandTreeFor({ apiFeatures: ["warehouse"] }).get( + "warehouse tables layout update", +)?.command; +describeHostedConsent("warehouse tables layout update", { + ...(layoutUpdateConsentCommand === undefined ? {} : { command: layoutUpdateConsentCommand }), + invoke: ({ workdir, yes }) => { + const body = { data: { type: "warehouse_table_layout", attributes: { sort_by: null } } }; + const { args, sent, run } = execute( + ["warehouse", "tables", "layout", "update", "16385", "--body", encodeJson(body)], + { yes, route: accepted }, + ); + return { + run: run.pipe(Effect.provide(cliServices(workdir, args))), + mutations: () => sent.filter((request) => request.method !== "GET").length, + }; + }, +}); From e35de1ef5b9b47cb0e8ac5d13e0d4ffdebbdddff Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Thu, 19 Nov 2026 12:04:00 +0100 Subject: [PATCH 27/45] feat(cli): add warehouse inspect capacity (#7714) Add the experimental `supabase warehouse inspect capacity` command, stacked on #7640. ```sh supabase warehouse inspect capacity --remote --since 30m ``` Generate the command from the public capacity API contract, with `--from`/`--to`, `--attributes`, and `--interval`. Keep metric selection defaults and range validation server-owned. Reuse the shared text, JSON, and YAML output contract, preserving units, dimensions, null values, and availability. JSON/YAML retain the complete response. No new generated-command runtime or generator logic is needed. Closes PIPE-1463. --- .../command-surface.integration.test.ts | 25 +- .../src/commands/api/api-command-policy.ts | 1 + .../src/commands/api/api-commands.e2e.test.ts | 67 +-- .../api/api-commands.integration.test.ts | 105 +++++ apps/cli/src/commands/api/generated.md | 28 ++ .../cli/src/commands/api/generated.schemas.ts | 201 +++++++++ apps/cli/src/commands/api/generated.ts | 96 +++++ packages/api/scripts/openapi-overrides.json | 391 ++++++++++++++++++ packages/api/src/generated/contracts.ts | 170 ++++++++ packages/api/src/generated/effect-client.ts | 16 + packages/api/src/generated/openapi.json | 382 +++++++++++++++++ packages/api/src/generated/permissions.ts | 1 + 12 files changed, 1442 insertions(+), 41 deletions(-) diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index ace075fa52..0fa0dfb89c 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -58,6 +58,7 @@ describe("command surface", () => { "warehouse disable", "warehouse enable", "warehouse inspect", + "warehouse inspect capacity", "warehouse inspect query-stats", "warehouse status", "warehouse tables", @@ -83,7 +84,7 @@ describe("command surface", () => { ); it.effect( - "mounts workload inspection under Warehouse and preserves standalone inspect commands", + "mounts metrics inspection under Warehouse and preserves standalone inspect commands", () => Effect.gen(function* () { const { commands } = yield* Effect.promise(() => surface); @@ -95,16 +96,18 @@ describe("command surface", () => { expect(enabled[path]).toEqual(commands[path]); } expect(enabled).not.toHaveProperty("inspect warehouse"); - const stats = enabled["warehouse inspect query-stats"]; - expect(stats).toMatchObject({ - stage: { status: "experimental", feature: "warehouse" }, - target: { group: "hosted", consent: "none" }, - api: { operationId: "v2-get-warehouse-query-stats" }, - }); - expect(Object.keys(stats?.flags ?? {})).toEqual( - expect.arrayContaining(["since", "from", "to", "attributes", "interval", "remote"]), - ); - expect(stats?.flags).not.toHaveProperty("wait"); + for (const command of ["capacity", "query-stats"]) { + const entry = enabled[`warehouse inspect ${command}`]; + expect(entry).toMatchObject({ + stage: { status: "experimental", feature: "warehouse" }, + target: { group: "hosted", consent: "none" }, + api: { operationId: `v2-get-warehouse-${command}` }, + }); + expect(Object.keys(entry?.flags ?? {})).toEqual( + expect.arrayContaining(["since", "from", "to", "attributes", "interval", "remote"]), + ); + expect(entry?.flags).not.toHaveProperty("wait"); + } }), ); diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 44421ab146..b1a7925060 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -25,6 +25,7 @@ export const generatedOperations: ReadonlyArray = [ "v2-get-warehouse-table-layout", "v2-update-warehouse-table-layout", "v2-get-warehouse-query-stats", + "v2-get-warehouse-capacity", ]; export const nouns = { diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index ad934d25e2..b3b26d860f 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -107,38 +107,45 @@ const runWarehouse = ( return { result, requests, bodies }; }).pipe(Effect.scoped); -it.live("warehouse inspect query-stats reaches the public route through the compiled CLI", () => - Effect.gen(function* () { - const response = json(200, { - data: [ - { - type: "warehouse_metric", - id: "query_rate", - attributes: { - project_ref: REF, - metric: "query_rate", - unit: "per_second", - aggregation: "rate", - definition: "Query invocations per second.", - requested: { metric: "query_rate", start: 1795000000, end: 1795001800 }, - effective: { start: 1795000000, end: 1795001800, step: 60, rate_window_seconds: 300 }, - scrape_interval_seconds: 60, - last_sample_at: null, - availability: "unavailable", - series: [], +it.live.each([ + { command: "query-stats", metric: "query_rate", unit: "per_second", aggregation: "rate" }, + { command: "capacity", metric: "query_in_flight", unit: "queries", aggregation: "sum" }, +] as const)( + "warehouse inspect $command reaches the public route through the compiled CLI", + ({ command, metric, unit, aggregation }) => + Effect.gen(function* () { + const response = json(200, { + data: [ + { + type: "warehouse_metric", + id: metric, + attributes: { + project_ref: REF, + metric, + unit, + aggregation, + definition: "Executor query invocations.", + requested: { metric, start: 1795000000, end: 1795001800 }, + effective: { start: 1795000000, end: 1795001800, step: 60, rate_window_seconds: 300 }, + scrape_interval_seconds: 60, + last_sample_at: null, + availability: "unavailable", + series: [], + }, }, - }, - ], - } satisfies OperationOutput<"v2GetWarehouseQueryStats">); - const { result, requests } = yield* runWarehouse( - ["inspect", "query-stats", "--since", "30m"], - () => response, - ); + ], + } satisfies + | OperationOutput<"v2GetWarehouseQueryStats"> + | OperationOutput<"v2GetWarehouseCapacity">); + const { result, requests } = yield* runWarehouse( + ["inspect", command, "--since", "30m"], + () => response, + ); - requireCliSuccess(result, "warehouse inspect query-stats"); - expect(result.stdout, result.stderr).toBe(response.body); - expect(requests).toEqual([`GET /v2/projects/${REF}/warehouse/query-stats`]); - }).pipe(Effect.provide(BunServices.layer)), + requireCliSuccess(result, `warehouse inspect ${command}`); + expect(result.stdout, result.stderr).toBe(response.body); + expect(requests).toEqual([`GET /v2/projects/${REF}/warehouse/${command}`]); + }).pipe(Effect.provide(BunServices.layer)), ); it.live("warehouse status reports a 409 as a conflict failure document on stderr", () => diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 30d025ad29..0ca827c87f 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -645,6 +645,106 @@ describe("generated warehouse commands", () => { }); }); }); + describe("warehouse inspect capacity", () => { + const argv = ["warehouse", "inspect", "capacity"]; + const attributes = { + project_ref: VALID_REF, + metric: "activation_duration_p95", + unit: "seconds", + aggregation: "p95", + definition: "Activation duration by kind and result.", + requested: { metric: "activation_duration_p95", start: 1795000000, end: 1795001800 }, + effective: { start: 1795000000, end: 1795001800, step: 60, rate_window_seconds: 300 }, + scrape_interval_seconds: 60, + last_sample_at: 1795001740, + availability: "partial", + series: [ + { + labels: { kind: "cold", result: "success" }, + points: [ + { timestamp: 1795001740, value: 0.2 }, + { timestamp: 1795001800, value: null }, + ], + coverage: { returned_points: 1, expected_points: 2 }, + }, + { + labels: { kind: "warm", result: "success" }, + points: [{ timestamp: 1795001800, value: 0.01 }], + coverage: { returned_points: 1, expected_points: 2 }, + }, + ], + } satisfies OperationOutput<"v2GetWarehouseCapacity">["data"][number]["attributes"]; + const response = { + data: [ + { + type: "warehouse_metric", + id: "activation_duration_p95", + attributes: { ...attributes, future_observation: { reason: null } }, + }, + ], + }; + + it.effect("leaves default selection to the API and preserves all JSON bytes when piped", () => { + const rawResponse = `\n${encodeJson(response).replace('"value":0.2', '"value":0.20')}\n`; + const { sent, out, run } = setup([...argv, "--since", "30m", "--interval", "5m"], { + route: ok(rawResponse), + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toHaveLength(1); + expect(sent[0]).toMatchObject({ + method: "GET", + path: `/v2/projects/${VALID_REF}/warehouse/capacity`, + body: undefined, + }); + expect(Object.fromEntries(new URLSearchParams(sent[0]?.search))).toEqual({ + since: "30m", + interval: "5m", + }); + expect(out.stdoutText).toBe(rawResponse); + }); + }); + + it.effect( + "renders both capacity series, their dimensions, unit, availability, and null sample", + () => { + const { out, run } = setup(argv, { route: ok(response), stdoutIsTty: true }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toMatch(/Kind\s+cold/); + expect(out.stdoutText).toMatch(/Kind\s+warm/); + expect(out.stdoutText.match(/Result\s+success/g)).toHaveLength(2); + expect(out.stdoutText).toMatch(/\bUNIT\b[\s\S]*\bseconds\b/); + expect(out.stdoutText).toMatch(/\bAVAILABILITY\b[\s\S]*\bpartial\b/); + expect(out.stdoutText).toMatch(/1795001800\s*[|│]?\s*-/); + expect(out.stdoutText).toMatch(/1795001800\s*[|│]?\s*0\.01/); + }); + }, + ); + + it.effect( + "forwards fixed timestamps and metric selection and keeps all dimensions in YAML", + () => { + const from = "2026-11-18T09:30:00+01:00"; + const to = "2026-11-18T10:00:00+01:00"; + const selection = "activation_duration_p95,worker_admission_occupied"; + const { sent, out, run } = setup( + [...argv, "--from", from, "--to", to, "--attributes", selection, "-o", "yaml"], + { route: ok(response), stdoutIsTty: true }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toHaveLength(1); + expect(Object.fromEntries(new URLSearchParams(sent[0]?.search))).toEqual({ + from, + to, + attributes: selection, + }); + expect(parseYaml(out.stdoutText)).toEqual(response); + }); + }, + ); + }); describe("warehouse tables get", () => { const tablePath = `/v2/projects/${VALID_REF}/warehouse/tables/16385`; const body = { @@ -2067,6 +2167,11 @@ describe("generated warehouse commands", () => { args: ["warehouse", "inspect", "query-stats"], features: ["warehouse"], }, + { + name: "Warehouse capacity inspection", + args: ["warehouse", "inspect", "capacity"], + features: ["warehouse"], + }, { name: "database inspection", args: ["inspect", "db", "table-stats"], features: [] }, { name: "inspection report", args: ["inspect", "report"], features: [] }, { diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index 3e21bb3db0..ff1837604a 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -67,6 +67,34 @@ Enables replication for the currently eligible tables in a schema, or the named - Failure message from `/data/attributes/status_error`. - Failure hint names `supabase warehouse status --remote=`. +## `supabase warehouse inspect capacity` + +Inspect Warehouse capacity diagnostics + +Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes. + +Each measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`. + +Executor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity. + +Point timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. + +Each request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted. + +- Access: read-only, no consent. +- Feature: `warehouse`. +- Request: `GET /v2/projects/{ref}/warehouse/capacity` (`v2-get-warehouse-capacity`), success 200 json. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| --------------------------- | --------------------------------------------- | -------- | ---------- | ------------------ | +| `--attributes ` | string | no | no | query `attributes` | +| `--from ` | string | no | no | query `from` | +| `--interval ` | string (`10m`, `1d`, `1h`, `1m`, `30m`, `5m`) | no | no | query `interval` | +| `--since ` | string | no | no | query `since` | +| `--to ` | string | no | no | query `to` | + ## `supabase warehouse inspect query-stats` Inspect Warehouse workload query statistics diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index 259740bc14..7503a81041 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -246,6 +246,207 @@ export const apiCommandSchemas = { required: ["data"], }, }, + "v2-get-warehouse-capacity": { + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + items: { + properties: { + attributes: { + properties: { + aggregation: { + enum: ["mean", "occupied", "p50", "p95", "p99", "rate", "sum"], + type: "string", + }, + availability: { + enum: [ + "disabled", + "insufficient_data", + "no_data", + "not_provisioned", + "ok", + "partial", + "stale", + "unavailable", + ], + type: "string", + }, + definition: { + type: "string", + }, + effective: { + properties: { + end: { + type: "number", + }, + rate_window_seconds: { + type: "number", + }, + start: { + type: "number", + }, + step: { + type: "number", + }, + }, + required: ["end", "rate_window_seconds", "start", "step"], + type: "object", + }, + last_sample_at: { + description: + "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", + type: ["number", "null"], + }, + metric: { + enum: [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ], + type: "string", + }, + project_ref: { + type: "string", + }, + requested: { + properties: { + end: { + type: "number", + }, + metric: { + enum: [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ], + type: "string", + }, + start: { + type: "number", + }, + step: { + type: "number", + }, + }, + required: ["end", "metric", "start"], + type: "object", + }, + scrape_interval_seconds: { + type: "number", + }, + series: { + items: { + properties: { + coverage: { + description: + "Grid point coverage, not proof that every worker was scraped.", + properties: { + expected_points: { + type: "number", + }, + returned_points: { + type: "number", + }, + }, + required: ["expected_points", "returned_points"], + type: "object", + }, + labels: { + additionalProperties: { + type: "string", + }, + type: "object", + }, + points: { + items: { + properties: { + timestamp: { + type: "number", + }, + value: { + type: ["number", "null"], + }, + }, + required: ["timestamp", "value"], + type: "object", + }, + type: "array", + }, + }, + required: ["coverage", "labels", "points"], + type: "object", + }, + type: "array", + }, + unit: { + enum: ["grants", "per_second", "queries", "seconds"], + type: "string", + }, + }, + required: [ + "aggregation", + "availability", + "definition", + "effective", + "last_sample_at", + "metric", + "project_ref", + "requested", + "scrape_interval_seconds", + "series", + "unit", + ], + type: "object", + }, + id: { + enum: [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ], + type: "string", + }, + type: { + description: "Resource type.", + enum: ["warehouse_metric"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + type: "array", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-get-warehouse-connection": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 0a5793dae4..30ff3dc771 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -190,6 +190,102 @@ export const apiCommands = [ error: "/data/attributes/status_error", }, }, + { + command: ["warehouse", "inspect", "capacity"], + operationId: "v2-get-warehouse-capacity", + definition: "v2GetWarehouseCapacity", + method: "GET", + apiPath: "/v2/projects/{ref}/warehouse/capacity", + summary: "Inspect Warehouse capacity diagnostics", + description: + "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.", + readOnly: true, + feature: "warehouse", + response: { + status: 200, + kind: "json", + }, + flags: [ + { + name: "attributes", + type: "string", + repeatable: false, + required: false, + description: + "Up to eight distinct measurements. Defaults to `query_in_flight`, `worker_admission_limit`, `worker_admission_active`, `worker_admission_pending`, `worker_admission_occupied`, `admission_rejection_rate`, `assignment_wait_p95`, `activation_duration_p95`. Supply a comma-separated list. Allowed measurements: `query_in_flight`, `worker_admission_limit`, `worker_admission_active`, `worker_admission_pending`, `worker_admission_occupied`, `admission_rejection_rate`, `assignment_wait_mean`, `assignment_wait_p95`, `activation_rate`, `activation_duration_mean`, `activation_duration_p95`.", + }, + { + name: "from", + type: "string", + repeatable: false, + required: false, + description: + "Range start as an ISO 8601 timestamp with seconds and a time zone, for example `2026-11-18T09:30:00Z`, within the last 30 days. Requires `--to`; cannot be combined with `--since`.", + }, + { + name: "interval", + type: "string", + choices: ["10m", "1d", "1h", "1m", "30m", "5m"], + repeatable: false, + required: false, + description: + "Defaults to `1m`. The effective step increases to stay within 1,441 points per series. Rate and latency windows are at least `5m`.", + }, + { + name: "since", + type: "string", + repeatable: false, + required: false, + description: + "Look back from server time, for example `30m`, `2h`, or `1d`. Defaults to `30m` when `--from`/`--to` are omitted. Maximum `30d`. Cannot be combined with `--from`/`--to`.", + }, + { + name: "to", + type: "string", + repeatable: false, + required: false, + description: + "Range end as an ISO 8601 timestamp with seconds and a time zone, for example `2026-11-18T09:30:00Z`, no later than server time. Requires `--from`; cannot be combined with `--since`. The service tolerates up to 60 seconds of request delay or clock skew.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "query", + name: "attributes", + source: "flag", + flag: "attributes", + }, + { + location: "query", + name: "from", + source: "flag", + flag: "from", + }, + { + location: "query", + name: "interval", + source: "flag", + flag: "interval", + }, + { + location: "query", + name: "since", + source: "flag", + flag: "since", + }, + { + location: "query", + name: "to", + source: "flag", + flag: "to", + }, + ], + }, { command: ["warehouse", "inspect", "query-stats"], operationId: "v2-get-warehouse-query-stats", diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 5c022cc142..e5cd825c21 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -2956,5 +2956,396 @@ } }, "$comment": "Public Warehouse workload metrics generate warehouse inspect query-stats." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseCapacityResponse_Output", + "value": { + "properties": { + "data": { + "items": { + "properties": { + "attributes": { + "properties": { + "aggregation": { + "enum": ["mean", "occupied", "p50", "p95", "p99", "rate", "sum"], + "type": "string" + }, + "availability": { + "enum": [ + "disabled", + "insufficient_data", + "no_data", + "not_provisioned", + "ok", + "partial", + "stale", + "unavailable" + ], + "type": "string" + }, + "definition": { + "type": "string" + }, + "effective": { + "properties": { + "end": { + "type": "number" + }, + "rate_window_seconds": { + "type": "number" + }, + "start": { + "type": "number" + }, + "step": { + "type": "number" + } + }, + "required": ["end", "rate_window_seconds", "start", "step"], + "type": "object" + }, + "last_sample_at": { + "description": "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", + "nullable": true, + "type": "number" + }, + "metric": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "project_ref": { + "type": "string" + }, + "requested": { + "properties": { + "end": { + "type": "number" + }, + "metric": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "start": { + "type": "number" + }, + "step": { + "type": "number" + } + }, + "required": ["end", "metric", "start"], + "type": "object" + }, + "scrape_interval_seconds": { + "type": "number" + }, + "series": { + "items": { + "properties": { + "coverage": { + "description": "Grid point coverage, not proof that every worker was scraped.", + "properties": { + "expected_points": { + "type": "number" + }, + "returned_points": { + "type": "number" + } + }, + "required": ["expected_points", "returned_points"], + "type": "object" + }, + "labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "points": { + "items": { + "properties": { + "timestamp": { + "type": "number" + }, + "value": { + "nullable": true, + "type": "number" + } + }, + "required": ["timestamp", "value"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["coverage", "labels", "points"], + "type": "object" + }, + "type": "array" + }, + "unit": { + "enum": ["grants", "per_second", "queries", "seconds"], + "type": "string" + } + }, + "required": [ + "aggregation", + "availability", + "definition", + "effective", + "last_sample_at", + "metric", + "project_ref", + "requested", + "scrape_interval_seconds", + "series", + "unit" + ], + "type": "object" + }, + "id": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_metric"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["data"], + "type": "object" + } + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1capacity", + "value": { + "get": { + "description": "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project\u2019s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-capacity", + "parameters": [ + { + "description": "Up to eight distinct measurements. Defaults to `query_in_flight`, `worker_admission_limit`, `worker_admission_active`, `worker_admission_pending`, `worker_admission_occupied`, `admission_rejection_rate`, `assignment_wait_p95`, `activation_duration_p95`. Supply a comma-separated list. Allowed measurements: `query_in_flight`, `worker_admission_limit`, `worker_admission_active`, `worker_admission_pending`, `worker_admission_occupied`, `admission_rejection_rate`, `assignment_wait_mean`, `assignment_wait_p95`, `activation_rate`, `activation_duration_mean`, `activation_duration_p95`.", + "in": "query", + "name": "attributes", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Range start as an ISO 8601 timestamp with seconds and a time zone, for example `2026-11-18T09:30:00Z`, within the last 30 days. Requires `--to`; cannot be combined with `--since`.", + "in": "query", + "name": "from", + "required": false, + "schema": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + }, + { + "description": "Defaults to `1m`. The effective step increases to stay within 1,441 points per series. Rate and latency windows are at least `5m`.", + "in": "query", + "name": "interval", + "required": false, + "schema": { + "enum": ["10m", "1d", "1h", "1m", "30m", "5m"], + "type": "string" + } + }, + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Look back from server time, for example `30m`, `2h`, or `1d`. Defaults to `30m` when `--from`/`--to` are omitted. Maximum `30d`. Cannot be combined with `--from`/`--to`.", + "in": "query", + "name": "since", + "required": false, + "schema": { + "pattern": "^[1-9]\\d*(s|m|h|d)$", + "type": "string" + } + }, + { + "description": "Range end as an ISO 8601 timestamp with seconds and a time zone, for example `2026-11-18T09:30:00Z`, no later than server time. Requires `--from`; cannot be combined with `--since`. The service tolerates up to 60 seconds of request delay or clock skew.", + "in": "query", + "name": "to", + "required": false, + "schema": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseCapacityResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "validation_failed: Invalid measurement selection, range, interval, or query parameter" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Project not found" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "warehouse_metrics_unavailable: Metrics query capacity is temporarily unavailable; retry after a short delay. warehouse_setup_unavailable: Warehouse feature or project metadata unavailable." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Inspect Warehouse capacity diagnostics", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.inspect", + "method": "capacity" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "Public Warehouse capacity metrics generate warehouse inspect capacity." } ] diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 169abe1535..cc2bbca132 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -14320,6 +14320,161 @@ export const V2GetProjectConfigOutput = Schema.Struct({ }), }), }); +export const V2GetWarehouseCapacityInput = Schema.Struct({ + attributes: Schema.optionalKey(Schema.String), + from: Schema.optionalKey(Schema.String.annotate({ format: "date-time" })), + interval: Schema.optionalKey(Schema.Literals(["10m", "1d", "1h", "1m", "30m", "5m"])), + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + since: Schema.optionalKey( + Schema.String.check( + Schema.isPattern(new RegExp("^[1-9]\\d*(s|m|h|d)$", "u")).annotate({ + expected: "a string matching the RegExp ^[1-9]\\d*(s|m|h|d)$", + }), + ), + ), + to: Schema.optionalKey(Schema.String.annotate({ format: "date-time" })), +}); +export const V2GetWarehouseCapacityOutput = Schema.Struct({ + data: Schema.Array( + Schema.Struct({ + attributes: Schema.Struct({ + aggregation: Schema.Union([ + Schema.Literals(["mean", "occupied", "p50", "p95", "p99", "rate", "sum"]), + OpenString, + ]), + availability: Schema.Union([ + Schema.Literals([ + "disabled", + "insufficient_data", + "no_data", + "not_provisioned", + "ok", + "partial", + "stale", + "unavailable", + ]), + OpenString, + ]), + definition: Schema.String, + effective: Schema.Struct({ + end: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + rate_window_seconds: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + start: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + step: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + }), + last_sample_at: Schema.Union([ + Schema.Number.annotate({ + description: + "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", + }).check(Schema.isFinite().annotate({ expected: "a finite number" })), + Schema.Null, + ]), + metric: Schema.Union([ + Schema.Literals([ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ]), + OpenString, + ]), + project_ref: Schema.String, + requested: Schema.Struct({ + end: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + metric: Schema.Union([ + Schema.Literals([ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ]), + OpenString, + ]), + start: Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + step: Schema.optionalKey( + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + ), + }), + scrape_interval_seconds: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + series: Schema.Array( + Schema.Struct({ + coverage: Schema.Struct({ + expected_points: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + returned_points: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + }).annotate({ + description: "Grid point coverage, not proof that every worker was scraped.", + }), + labels: Schema.Record(Schema.String, Schema.String), + points: Schema.Array( + Schema.Struct({ + timestamp: Schema.Number.check( + Schema.isFinite().annotate({ expected: "a finite number" }), + ), + value: Schema.Union([ + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })), + Schema.Null, + ]), + }), + ), + }), + ), + unit: Schema.Union([ + Schema.Literals(["grants", "per_second", "queries", "seconds"]), + OpenString, + ]), + }), + id: Schema.Union([ + Schema.Literals([ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending", + ]), + OpenString, + ]), + type: Schema.Literal("warehouse_metric").annotate({ description: "Resource type." }), + }), + ), +}); export const V2GetWarehouseConnectionInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -20971,6 +21126,7 @@ export const openApiOperationIdMap = { "v2-get-a-compute-instance": "v2GetAComputeInstance", "v2-get-notebook": "v2GetNotebook", "v2-get-project-config": "v2GetProjectConfig", + "v2-get-warehouse-capacity": "v2GetWarehouseCapacity", "v2-get-warehouse-connection": "v2GetWarehouseConnection", "v2-get-warehouse-query-stats": "v2GetWarehouseQueryStats", "v2-get-warehouse-setup": "v2GetWarehouseSetup", @@ -24152,6 +24308,20 @@ export const operationDefinitions = { inputSchema: V2GetProjectConfigInput, outputSchema: V2GetProjectConfigOutput, }, + v2GetWarehouseCapacity: { + id: "v2GetWarehouseCapacity", + description: + "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "GET", + path: "/v2/projects/{ref}/warehouse/capacity", + pathParams: ["ref"], + queryParams: ["attributes", "from", "interval", "since", "to"], + headerParams: [], + requestBody: { kind: "none" }, + response: { kind: "json" }, + inputSchema: V2GetWarehouseCapacityInput, + outputSchema: V2GetWarehouseCapacityOutput, + }, v2GetWarehouseConnection: { id: "v2GetWarehouseConnection", description: diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index c014161cb9..b1a8cd3e65 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -3092,6 +3092,22 @@ export const versionedEffectOperations = { options, ); }), + getWarehouseCapacity: ( + input: typeof operationDefinitions.v2GetWarehouseCapacity.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2GetWarehouseCapacity.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2GetWarehouseCapacity">( + operationDefinitions.v2GetWarehouseCapacity, + input, + options, + ); + }), getWarehouseConnection: ( input: typeof operationDefinitions.v2GetWarehouseConnection.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index 4fea2b2f5e..11dab8f078 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -33553,6 +33553,190 @@ }, "x-scalar-stability": "experimental" } + }, + "/v2/projects/{ref}/warehouse/capacity": { + "get": { + "description": "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-get-warehouse-capacity", + "parameters": [ + { + "description": "Up to eight distinct measurements. Defaults to `query_in_flight`, `worker_admission_limit`, `worker_admission_active`, `worker_admission_pending`, `worker_admission_occupied`, `admission_rejection_rate`, `assignment_wait_p95`, `activation_duration_p95`. Supply a comma-separated list. Allowed measurements: `query_in_flight`, `worker_admission_limit`, `worker_admission_active`, `worker_admission_pending`, `worker_admission_occupied`, `admission_rejection_rate`, `assignment_wait_mean`, `assignment_wait_p95`, `activation_rate`, `activation_duration_mean`, `activation_duration_p95`.", + "in": "query", + "name": "attributes", + "required": false, + "schema": { + "type": "string" + } + }, + { + "description": "Range start as an ISO 8601 timestamp with seconds and a time zone, for example `2026-11-18T09:30:00Z`, within the last 30 days. Requires `--to`; cannot be combined with `--since`.", + "in": "query", + "name": "from", + "required": false, + "schema": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + }, + { + "description": "Defaults to `1m`. The effective step increases to stay within 1,441 points per series. Rate and latency windows are at least `5m`.", + "in": "query", + "name": "interval", + "required": false, + "schema": { + "enum": ["10m", "1d", "1h", "1m", "30m", "5m"], + "type": "string" + } + }, + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + }, + { + "description": "Look back from server time, for example `30m`, `2h`, or `1d`. Defaults to `30m` when `--from`/`--to` are omitted. Maximum `30d`. Cannot be combined with `--from`/`--to`.", + "in": "query", + "name": "since", + "required": false, + "schema": { + "pattern": "^[1-9]\\d*(s|m|h|d)$", + "type": "string" + } + }, + { + "description": "Range end as an ISO 8601 timestamp with seconds and a time zone, for example `2026-11-18T09:30:00Z`, no later than server time. Requires `--from`; cannot be combined with `--since`. The service tolerates up to 60 seconds of request delay or clock skew.", + "in": "query", + "name": "to", + "required": false, + "schema": { + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseCapacityResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "validation_failed: Invalid measurement selection, range, interval, or query parameter" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Project not found" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "warehouse_metrics_unavailable: Metrics query capacity is temporarily unavailable; retry after a short delay. warehouse_setup_unavailable: Warehouse feature or project metadata unavailable." + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Inspect Warehouse capacity diagnostics", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:read", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_read"]], + "x-oauth-scope": "database:read", + "x-operation": { + "group": "warehouse.inspect", + "method": "capacity" + }, + "x-scalar-stability": "experimental" + } } }, "components": { @@ -50710,6 +50894,204 @@ }, "required": ["data"], "type": "object" + }, + "V2WarehouseCapacityResponse_Output": { + "properties": { + "data": { + "items": { + "properties": { + "attributes": { + "properties": { + "aggregation": { + "enum": ["mean", "occupied", "p50", "p95", "p99", "rate", "sum"], + "type": "string" + }, + "availability": { + "enum": [ + "disabled", + "insufficient_data", + "no_data", + "not_provisioned", + "ok", + "partial", + "stale", + "unavailable" + ], + "type": "string" + }, + "definition": { + "type": "string" + }, + "effective": { + "properties": { + "end": { + "type": "number" + }, + "rate_window_seconds": { + "type": "number" + }, + "start": { + "type": "number" + }, + "step": { + "type": "number" + } + }, + "required": ["end", "rate_window_seconds", "start", "step"], + "type": "object" + }, + "last_sample_at": { + "description": "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", + "nullable": true, + "type": "number" + }, + "metric": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "project_ref": { + "type": "string" + }, + "requested": { + "properties": { + "end": { + "type": "number" + }, + "metric": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "start": { + "type": "number" + }, + "step": { + "type": "number" + } + }, + "required": ["end", "metric", "start"], + "type": "object" + }, + "scrape_interval_seconds": { + "type": "number" + }, + "series": { + "items": { + "properties": { + "coverage": { + "description": "Grid point coverage, not proof that every worker was scraped.", + "properties": { + "expected_points": { + "type": "number" + }, + "returned_points": { + "type": "number" + } + }, + "required": ["expected_points", "returned_points"], + "type": "object" + }, + "labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "points": { + "items": { + "properties": { + "timestamp": { + "type": "number" + }, + "value": { + "nullable": true, + "type": "number" + } + }, + "required": ["timestamp", "value"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["coverage", "labels", "points"], + "type": "object" + }, + "type": "array" + }, + "unit": { + "enum": ["grants", "per_second", "queries", "seconds"], + "type": "string" + } + }, + "required": [ + "aggregation", + "availability", + "definition", + "effective", + "last_sample_at", + "metric", + "project_ref", + "requested", + "scrape_interval_seconds", + "series", + "unit" + ], + "type": "object" + }, + "id": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_metric"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["data"], + "type": "object" } } } diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index fc787e4a6e..59ffaf69a7 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -458,4 +458,5 @@ export const operationPermissions: Readonly oauthScope: "database:write", }, "v2-get-warehouse-query-stats": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-get-warehouse-capacity": { fga: [["database_read"]], oauthScope: "database:read" }, }; From 1c748530175244661d4fa663960721ada13aae91 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 13:51:17 +0100 Subject: [PATCH 28/45] feat(cli): accept JSON values for nested body fields in generated API commands A body field that is not a scalar or an array of scalars now gets a flag that takes a JSON value for that field, so warehouse tables layout update accepts --sort-by and --partition-by without a --body envelope. The value is validated against the operation schema before consent. --- apps/cli/scripts/api-command-derive.ts | 51 +++++--------- .../scripts/api-command-derive.unit.test.ts | 46 +++++++++---- apps/cli/scripts/api-command-reference.ts | 5 +- apps/cli/src/commands/api/SIDE_EFFECTS.md | 2 + .../api-command-bindings.integration.test.ts | 66 +++++++++++------- .../cli/src/commands/api/api-command-flags.ts | 5 +- .../src/commands/api/api-command-request.ts | 21 +++++- .../api-command-shapes.integration.test.ts | 18 +++-- .../cli/src/commands/api/api-command.model.ts | 3 +- .../api/api-commands.integration.test.ts | 69 +++++++++++++++++++ apps/cli/src/commands/api/generated.md | 8 ++- apps/cli/src/commands/api/generated.ts | 30 ++++++++ 12 files changed, 238 insertions(+), 86 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 38a180ef32..74fd33dbdb 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -824,7 +824,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { readonly writeOnly: boolean; }> = []; - const fileOnlyFields: Array = []; const pathBindings: Array = []; const pathNames: Array = []; const positionals: Array<{ @@ -948,34 +947,26 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { ? { contentType: "application/json", kind: "json-envelope", type: envelopeType } : { contentType: "application/json", kind: "json-object" }; for (const [field, schema] of Object.entries(fieldProperties ?? {})) { - const shape = describeFlagSchema(spec, schema); + const scalarShape = describeFlagSchema(spec, schema); + const secret = findSecret(spec, schema, field); if (field === "dry_run") { fail('unsupported in this runtime: server-side "dry_run" body field'); - } else if (shape === undefined) { - const secret = findSecret(spec, schema, field); - if (secret !== undefined) { - fail( - `unsupported in this runtime: body field "${field}" ${secret === field ? "is a secret" : `holds the secret "${secret}"`} without a flag, and the dry-run preview masks only flag-bound fields`, - ); - } else if (credentialLike(field)) { - fail( - `body field "${field}" looks like a credential; mark its schema writeOnly, format: password or x-sensitive`, - ); - } - fileOnlyFields.push(field); - } else { - fields.push({ - location: "body", - key: field, - pointer: isEnvelope - ? `/data/attributes/${escapePointer(field)}` - : `/${escapePointer(field)}`, - shape, - required: required.includes(field), - description: schemaDescription(spec, schema), - writeOnly: findSecret(spec, schema, field) !== undefined, - }); + } else if (scalarShape === undefined && secret !== undefined) { + fail( + `unsupported in this runtime: body field "${field}" ${secret === field ? "is a secret" : `holds the secret "${secret}"`}, and the dry-run preview masks only scalar flag values`, + ); } + fields.push({ + location: "body", + key: field, + pointer: isEnvelope + ? `/data/attributes/${escapePointer(field)}` + : `/${escapePointer(field)}`, + shape: scalarShape ?? { type: "json", repeatable: false }, + required: required.includes(field), + description: schemaDescription(spec, schema), + writeOnly: secret !== undefined, + }); } } } @@ -1003,14 +994,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const bindings: Array = [...pathBindings]; const seenNames = new Set(); const seenKeys = new Set(pathNames); - for (const key of fileOnlyFields) { - if (seenKeys.has(key)) { - fail( - `"${key}" is used by more than one of: path parameter, header parameter, query parameter, body field`, - ); - } - seenKeys.add(key); - } for (const field of fields) { const flagName = field.location === "body" && field.shape.repeatable diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 49635b262f..7809de4789 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -217,24 +217,40 @@ describe("deriveApiCommands", () => { expect(result.problems.join("\n")).toContain("binary or streaming"); }); - describe("body fields without a flag", () => { + describe("nested body fields", () => { const writeOnlyString = { type: "string", writeOnly: true }; const nestedBody = (nested: Record) => derive({ "create-thing": operation({ ...create, requestBody: envelope({ nested }) }), }); - it("keeps the operation and describes the field in the request schema without a flag or binding", () => { - const result = nestedBody({ type: "object", properties: { size: { type: "string" } } }); + it("binds an object and an array of objects to JSON flags named after the field", () => { + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: envelope({ + name: { type: "string" }, + nested: { type: "object", properties: { size: { type: "string" } } }, + rules: { type: "array", items: { type: "object", properties: {} } }, + }), + }), + }); expect(result.problems).toEqual([]); const [entry] = result.entries; - expect(entry?.flags.map((flag) => flag.name)).toEqual(["name"]); - expect(entry?.bindings.filter((binding) => binding.location === "body")).toHaveLength(1); - expect(JSON.stringify(result.schemas["create-thing"]?.request)).toContain('"nested"'); + expect(entry?.flags).toMatchObject([ + { name: "name", type: "string" }, + { name: "nested", type: "json", repeatable: false }, + { name: "rules", type: "json", repeatable: false }, + ]); + expect(entry?.bindings.filter((binding) => binding.location === "body")).toMatchObject([ + { pointer: "/data/attributes/name", flag: "name" }, + { pointer: "/data/attributes/nested", flag: "nested" }, + { pointer: "/data/attributes/rules", flag: "rules" }, + ]); }); - it("rejects a sensitive field that has no flag", () => { + it("rejects a sensitive nested field", () => { const result = nestedBody({ type: "object", writeOnly: true, @@ -243,11 +259,11 @@ describe("deriveApiCommands", () => { expect(result.entries).toEqual([]); expect(result.problems.join("\n")).toContain( - 'unsupported in this runtime: body field "nested" is a secret without a flag', + 'unsupported in this runtime: body field "nested" is a secret', ); }); - it("rejects an unmarked credential-like field that has no flag", () => { + it("rejects an unmarked credential-like nested field", () => { const result = derive({ "create-thing": operation({ ...create, @@ -287,16 +303,16 @@ describe("deriveApiCommands", () => { { anyOf: [{ type: "object", properties: { pin: writeOnlyString } }, { type: "null" }] }, "nested.pin", ], - ])("rejects a file-only field that holds %s", (_label, nested, secretPath) => { + ])("rejects a nested field that holds %s", (_label, nested, secretPath) => { const result = nestedBody(nested); expect(result.entries).toEqual([]); expect(result.problems).toEqual([ - `create-thing: unsupported in this runtime: body field "nested" holds the secret "${secretPath}" without a flag, and the dry-run preview masks only flag-bound fields`, + `create-thing: unsupported in this runtime: body field "nested" holds the secret "${secretPath}", and the dry-run preview masks only scalar flag values`, ]); }); - it("rejects a file-only field whose patternProperties value is a secret", () => { + it("rejects a nested field whose patternProperties value is a secret", () => { const result = nestedBody({ type: "object", patternProperties: { ".*": { type: "string", format: "password" } }, @@ -304,11 +320,11 @@ describe("deriveApiCommands", () => { expect(result.entries).toEqual([]); expect(result.problems).toEqual([ - 'create-thing: unsupported in this runtime: body field "nested" is a secret without a flag, and the dry-run preview masks only flag-bound fields', + 'create-thing: unsupported in this runtime: body field "nested" is a secret, and the dry-run preview masks only scalar flag values', ]); }); - it("accepts a file-only field whose schema refers back to itself when it holds no secret", () => { + it("accepts a nested field whose schema refers back to itself when it holds no secret", () => { const node = { type: "object", properties: { label: { type: "string" }, child: { $ref: "#/components/schemas/Node" } }, @@ -1481,7 +1497,7 @@ describe("deriveApiCommands", () => { 'create-thing: unsupported in this runtime: server-side "dry_run" body field', ], [ - "a file-only body field named like a path parameter", + "a nested body field named like a path parameter", { "create-thing": operation({ ...create, diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts index 58e6beee2b..d85a6d04fd 100644 --- a/apps/cli/scripts/api-command-reference.ts +++ b/apps/cli/scripts/api-command-reference.ts @@ -46,7 +46,10 @@ const bindsTo = (entry: ApiCommandEntry, flag: ApiCommandFlag): string => { const flagRows = (entry: ApiCommandEntry): ReadonlyArray => entry.flags.map((flag) => { - const label = flag.type === "boolean" ? `--${flag.name}` : `--${flag.name} <${flag.name}>`; + const label = + flag.type === "boolean" + ? `--${flag.name}` + : `--${flag.name} <${flag.type === "json" ? "json" : flag.name}>`; const notes = flag.sensitive === true ? " Sensitive: never echoed or recorded." : ""; return `| ${code(label)} | ${cell(flagType(flag))} | ${flag.required ? "yes" : "no"} | ${flag.repeatable ? "yes" : "no"} | ${bindsTo(entry, flag)}${notes} |`; }); diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index bf9a10356e..52c6d6de3f 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -67,6 +67,8 @@ With `--wait`, the command also polls the read operation named in its reference ### Request input - `--body` or `--file` supply the whole body; a flag replaces its own field and nothing else. +- A flag for a nested body field (an object, an array of objects or a union) takes a JSON value for + that field, `null` included; text that is not JSON is a usage error naming the flag. - The input is validated before consent and before the command request: a top-level body key outside the declared request-body fields, an unknown nested field or a missing required flag fails with no command request sent. Target resolution runs first, so the project picker and diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index dde6292d6b..caac7d7466 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -149,7 +149,16 @@ const sampleOf = (schema: unknown): unknown => { } }; +/** Samples for the body fields that take a JSON value; a field without one fails loudly. */ +const JSON_SAMPLES: Readonly> = { + "v2-update-warehouse-table-layout.sort_by": { kind: "primary_key" }, + "v2-update-warehouse-table-layout.partition_by": [ + { column: "id", transform: { kind: "identity" } }, + ], +}; + interface Input { + readonly json: boolean; readonly location: "query" | "body"; readonly field: string; readonly flag: string; @@ -159,10 +168,11 @@ interface Input { } /** - * Every scalar or scalar-array non-path input, read from openapi.json; the flag spelling comes from the - * command's declared binding, since naming is the derivation's contract. + * Every non-path input, read from openapi.json; the flag spelling comes from the command's declared + * binding, since naming is the derivation's contract. */ const inputsOf = ( + operationId: string, operation: SpecOperation, bindings: ApiCommandEntry["bindings"], ): ReadonlyArray => { @@ -175,6 +185,7 @@ const inputsOf = ( .map((parameter): Input => { const field = String(parameter["name"]); return { + json: false, location: "query", field, flag: flagFor("query", field), @@ -194,26 +205,25 @@ const inputsOf = ( const container = envelope ? attributes : operation.requestSchema; const required = asList(container["required"]); const scalarTypes = ["boolean", "integer", "number", "string"]; - const fields = Object.entries(asRecord(container["properties"])) - .filter(([, schema]) => { - const node = resolveRef(schema); - return ( - scalarTypes.includes(String(node["type"])) || - (node["type"] === "array" && - scalarTypes.includes(String(resolveRef(node["items"])["type"]))) - ); - }) - .map(([field, schema]): Input => { - const sample = sampleOf(schema); - return { - location: "body", - field, - flag: flagFor("body", field), - pointer: `${envelope ? "/data/attributes" : ""}/${field}`, - required: required.includes(field), - sample, - }; - }); + const fields = Object.entries(asRecord(container["properties"])).map(([field, schema]): Input => { + const node = resolveRef(schema); + const scalar = + scalarTypes.includes(String(node["type"])) || + (node["type"] === "array" && scalarTypes.includes(String(resolveRef(node["items"])["type"]))); + const key = `${operationId}.${field}`; + if (!scalar && !Object.hasOwn(JSON_SAMPLES, key)) { + throw new Error(`no JSON sample for body field ${key}`); + } + return { + json: !scalar, + location: "body", + field, + flag: flagFor("body", field), + pointer: `${envelope ? "/data/attributes" : ""}/${field}`, + required: required.includes(field), + sample: scalar ? sampleOf(schema) : JSON_SAMPLES[key], + }; + }); return [...queries, ...fields]; }; @@ -226,11 +236,15 @@ const positionalsOf = (operation: SpecOperation) => sample: String(sampleOf(parameter["schema"])), })); +const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); + const argvOf = (inputs: ReadonlyArray): ReadonlyArray => inputs.flatMap((input) => - Array.isArray(input.sample) - ? input.sample.flatMap((item) => [`--${input.flag}`, String(item)]) - : [`--${input.flag}`, String(input.sample)], + input.json + ? [`--${input.flag}`, encodeJson(input.sample)] + : Array.isArray(input.sample) + ? input.sample.flatMap((item) => [`--${input.flag}`, String(item)]) + : [`--${input.flag}`, String(input.sample)], ); const expectedQuery = (inputs: ReadonlyArray): Readonly> => @@ -357,7 +371,7 @@ describe("generated command bindings", () => { for (const row of rows) { const { operationId } = row.api; const operation = operationOf(operationId); - const inputs = inputsOf(operation, row.api.bindings); + const inputs = inputsOf(operationId, operation, row.api.bindings); const positionals = positionalsOf(operation); const expectedPath = positionals.reduce( (path, { name, sample }) => path.replace(`{${name}}`, sample), diff --git a/apps/cli/src/commands/api/api-command-flags.ts b/apps/cli/src/commands/api/api-command-flags.ts index 59ae878337..1dfff13153 100644 --- a/apps/cli/src/commands/api/api-command-flags.ts +++ b/apps/cli/src/commands/api/api-command-flags.ts @@ -13,6 +13,8 @@ const scalarFlag = (flag: ApiCommandFlag): Flag.Flag switch (flag.type) { case "string": return Flag.String(flag.name); + case "json": + return Flag.String(flag.name).pipe(Flag.withMetavar("json")); case "integer": return Flag.Int(flag.name); case "number": @@ -26,7 +28,8 @@ const scalarFlag = (flag: ApiCommandFlag): Flag.Flag export type ApiFlagLocation = "query" | "header" | "body"; const describedFlag = (flag: ApiCommandFlag, location: ApiFlagLocation): string => { - const description = flag.description ?? `Set ${flag.name}.`; + const base = flag.description ?? `Set ${flag.name}.`; + const description = flag.type === "json" ? `${base} Takes a JSON value.` : base; if (!flag.required) return description; return location === "body" ? `${description} Required unless the field is in --body or --file.` diff --git a/apps/cli/src/commands/api/api-command-request.ts b/apps/cli/src/commands/api/api-command-request.ts index fcb3233463..59607a07c2 100644 --- a/apps/cli/src/commands/api/api-command-request.ts +++ b/apps/cli/src/commands/api/api-command-request.ts @@ -88,6 +88,17 @@ const initialBody = (entry: ApiCommandEntry): Readonly> return {}; }; +const parseJsonFlag = (flag: string, text: ApiFlagValue) => + Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe( + Effect.mapError( + () => + new ApiCommandUsageError({ + message: `--${flag} is not valid JSON.`, + hint: `Pass a JSON value and quote it for the shell, e.g. --${flag} '{"key":"value"}'.`, + }), + ), + ); + /** * The flat operation input `{...bodyFields, ...query, ...headers, ref, }`. A body * override is the starting point when given, else the synthesized envelope; only flags that were @@ -116,6 +127,9 @@ export const assembleInput = Effect.fnUntraced(function* ( }); } } + const jsonFlagNames = new Set( + entry.flags.filter((flag) => flag.type === "json").map((flag) => flag.name), + ); let body: unknown = Option.getOrElse(bodyOverride, () => initialBody(entry)); const query: Record = {}; const headers: Record = {}; @@ -138,7 +152,12 @@ export const assembleInput = Effect.fnUntraced(function* ( if (value === undefined || Option.isNone(value)) continue; if (binding.location === "query") query[binding.name] = value.value; if (binding.location === "header") headers[binding.name] = value.value; - if (binding.location === "body") body = writePointer(body, binding.pointer, value.value); + if (binding.location === "body") { + const parsed = jsonFlagNames.has(binding.flag) + ? yield* parseJsonFlag(binding.flag, value.value) + : value.value; + body = writePointer(body, binding.pointer, parsed); + } } return { ...(isRecord(body) ? body : {}), ...query, ...headers, ref, ...positional }; }); diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts index afa3b79499..0d17ad9e3e 100644 --- a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts @@ -277,7 +277,7 @@ describe("generated command shapes", () => { }); }); - describe("a body field without a flag", () => { + describe("a nested body field", () => { const USER_ID = "55555555-5555-4555-8555-555555555555"; const roles = [ { role: "postgres", allowed_networks: { allowed_cidrs: [{ cidr: "10.0.0.0/8" }] } }, @@ -318,15 +318,25 @@ describe("generated command shapes", () => { }).pipe(Effect.provide(BunServices.layer)); }); - it.effect("has no flag in --help while its scalar sibling has one", () => { + it.effect("is a JSON-valued flag in --help, named after the field", () => { const { help, effect } = run([...update, "--help"]); return Effect.gen(function* () { yield* effect; - expect(help()).toContain("--user-id"); - expect(help()).not.toContain("--roles"); + const rolesLine = help() + .split("\n") + .find((line) => line.includes("--roles ")); + expect(rolesLine).toContain("Takes a JSON value."); expect(help()).not.toContain("--role "); }); }); + + it.effect("is sent from its own flag", () => { + const { sent, effect } = run([...update, "--user-id", USER_ID, "--roles", encodeJson(roles)]); + return Effect.gen(function* () { + yield* effect; + expect(sent.map((request) => request.body)).toEqual([{ user_id: USER_ID, roles }]); + }); + }); }); describe("a required query flag", () => { diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index 9d09648f34..ce0b12547e 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -46,7 +46,8 @@ export type ApiCommandBinding = export interface ApiCommandFlag { /** Kebab-case flag name without the leading dashes. */ readonly name: string; - readonly type: "string" | "integer" | "number" | "boolean"; + /** `json` takes a JSON value for a body field that is not a scalar or an array of scalars. */ + readonly type: "string" | "integer" | "number" | "boolean" | "json"; readonly choices?: readonly string[]; readonly repeatable: boolean; readonly required: boolean; diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 0ca827c87f..5736aa2e70 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -907,6 +907,75 @@ describe("generated warehouse commands", () => { }, ); + it.effect("sends the JSON values of --sort-by and --partition-by in the envelope", () => { + const { sent, run } = setup( + [...argv, "--sort-by", '{"kind":"none"}', "--partition-by", "[]"], + { yes: true, route: accepted }, + ); + return Effect.gen(function* () { + yield* run; + expect(bodiesOf(sent)).toEqual([ + { + data: { + type: "warehouse_table_layout", + attributes: { sort_by: { kind: "none" }, partition_by: [] }, + }, + }, + ]); + }); + }); + + it.effect("keeps a JSON null from --sort-by as unmanaged sorting", () => { + const { sent, out, run } = setup([...argv, "--sort-by", "null", "--dry-run"], { + route: accepted, + }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([]); + expect(decodeJson(out.stdoutText)).toMatchObject({ + body: { data: { attributes: { sort_by: null } } }, + }); + }); + }); + + it.effect("lets a JSON flag replace only its own field of --body", () => { + const { sent, run } = setup([...argv, "--body", encodeJson(body), "--sort-by", "null"], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + yield* run; + expect(bodiesOf(sent)).toEqual([ + { + data: { + type: "warehouse_table_layout", + attributes: { sort_by: null, partition_by: [] }, + }, + }, + ]); + }); + }); + + it.effect("rejects --sort-by text that is not JSON, naming the flag, and sends nothing", () => { + const { sent, run } = setup([...argv, "--sort-by", "{"], { yes: true, route: accepted }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(failure).toBeInstanceOf(ApiCommandUsageError); + expect(failure).toMatchObject({ message: "--sort-by is not valid JSON." }); + expect(sent).toEqual([]); + }); + }); + + it.effect("rejects a --sort-by value outside the field schema before consent", () => { + const { sent, run } = setup([...argv, "--sort-by", '{"kind":"bogus"}'], { + route: accepted, + }); + return Effect.gen(function* () { + expect(failureOf(yield* Effect.exit(run))).toBeInstanceOf(ApiCommandUsageError); + expect(sent).toEqual([]); + }); + }); + it.effect("rejects a non-boolean reset before making a hosted request", () => { const reset = { data: { type: "warehouse_table_layout", attributes: { reset_table: "true" } }, diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index ff1837604a..f0870e5eef 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -161,9 +161,11 @@ Updates saved sorting and partitioning rules for one source table object identif ### Flags -| Flag | Type | Required | Repeatable | Binds to | -| --------------- | ------- | -------- | ---------- | ----------------------------------- | -| `--reset-table` | boolean | no | no | body `/data/attributes/reset_table` | +| Flag | Type | Required | Repeatable | Binds to | +| ----------------------- | ------- | -------- | ---------- | ------------------------------------ | +| `--partition-by ` | json | no | no | body `/data/attributes/partition_by` | +| `--reset-table` | boolean | no | no | body `/data/attributes/reset_table` | +| `--sort-by ` | json | no | no | body `/data/attributes/sort_by` | ## `supabase warehouse tables list` diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 30ff3dc771..946bd3e493 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -499,6 +499,14 @@ export const apiCommands = [ description: "Source Postgres table OID from the Warehouse tables list.", }, flags: [ + { + name: "partition-by", + type: "json", + repeatable: false, + required: false, + description: + "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + }, { name: "reset-table", type: "boolean", @@ -507,6 +515,14 @@ export const apiCommands = [ description: "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", }, + { + name: "sort-by", + type: "json", + repeatable: false, + required: false, + description: + "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + }, ], bindings: [ { @@ -520,6 +536,13 @@ export const apiCommands = [ source: "argument", argument: "table-id", }, + { + location: "body", + name: "partition_by", + pointer: "/data/attributes/partition_by", + source: "flag", + flag: "partition-by", + }, { location: "body", name: "reset_table", @@ -527,6 +550,13 @@ export const apiCommands = [ source: "flag", flag: "reset-table", }, + { + location: "body", + name: "sort_by", + pointer: "/data/attributes/sort_by", + source: "flag", + flag: "sort-by", + }, ], }, { From b4079fb9b479945c7e2680b716e9a31e66bdf115 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 14:08:43 +0100 Subject: [PATCH 29/45] fix(api): align Warehouse layout overrides with the platform contract Layout reads require application_status, pipeline_id and reset_table, as the platform does, and the update response reuses the read schema. The capacity schema override gets the comment the override loader requires. --- .../cli/src/commands/api/generated.schemas.ts | 11 +- packages/api/scripts/openapi-overrides.json | 294 +----------------- packages/api/src/effect.unit.test.ts | 34 -- packages/api/src/generated/contracts.ts | 26 +- packages/api/src/generated/openapi.json | 282 +---------------- 5 files changed, 47 insertions(+), 600 deletions(-) diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index 7503a81041..ff78ab5865 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -1884,7 +1884,16 @@ export const apiCommandSchemas = { type: "string", }, }, - required: ["desired", "name", "observation_status", "observed", "schema"], + required: [ + "application_status", + "desired", + "name", + "observation_status", + "observed", + "pipeline_id", + "reset_table", + "schema", + ], type: "object", }, id: { diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index e5cd825c21..a4192db319 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -1837,7 +1837,16 @@ "type": "string" } }, - "required": ["desired", "name", "observation_status", "observed", "schema"], + "required": [ + "application_status", + "desired", + "name", + "observation_status", + "observed", + "pipeline_id", + "reset_table", + "schema" + ], "type": "object" }, "id": { @@ -1940,7 +1949,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/V2WarehouseTableLayoutUpdateResponse_Output" + "$ref": "#/components/schemas/V2WarehouseTableLayoutResponse_Output" } } }, @@ -2255,280 +2264,6 @@ }, "$comment": "The Warehouse layout update contract is not yet in the deployed Management API specification." }, - { - "op": "add", - "path": "/components/schemas/V2WarehouseTableLayoutUpdateResponse_Output", - "value": { - "properties": { - "data": { - "properties": { - "attributes": { - "properties": { - "application_status": { - "description": "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", - "type": "string" - }, - "desired": { - "description": "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", - "properties": { - "partition_by": { - "description": "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", - "items": { - "properties": { - "column": { - "description": "Source column name.", - "type": "string" - }, - "transform": { - "oneOf": [ - { - "properties": { - "kind": { - "enum": ["identity"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["year"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["month"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["day"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["hour"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "count": { - "description": "Number of hash buckets.", - "exclusiveMinimum": true, - "maximum": 2147483647, - "minimum": 0, - "type": "integer" - }, - "kind": { - "enum": ["bucket"], - "type": "string" - } - }, - "required": ["count", "kind"], - "type": "object" - } - ] - } - }, - "required": ["column", "transform"], - "type": "object" - }, - "nullable": true, - "type": "array" - }, - "sort_by": { - "description": "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", - "oneOf": [ - { - "properties": { - "kind": { - "enum": ["none"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["primary_key"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "columns": { - "items": { - "properties": { - "direction": { - "enum": ["asc", "desc"], - "type": "string" - }, - "name": { - "description": "Source column name.", - "type": "string" - }, - "nulls": { - "description": "Null placement. Null uses DuckLake's default placement.", - "enum": ["first", "last", null], - "nullable": true, - "type": "string" - } - }, - "required": ["direction", "name", "nulls"], - "type": "object" - }, - "type": "array" - }, - "kind": { - "enum": ["columns"], - "type": "string" - } - }, - "required": ["columns", "kind"], - "type": "object" - }, - { - "type": "object", - "nullable": true, - "enum": [null] - } - ] - } - }, - "required": ["partition_by", "sort_by"], - "type": "object" - }, - "name": { - "description": "Source PostgreSQL table name.", - "type": "string" - }, - "observation_status": { - "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", - "enum": ["not_requested", "observed", "table_missing", "unavailable"], - "type": "string" - }, - "observed": { - "description": "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", - "nullable": true, - "properties": { - "observed_at": { - "description": "Time the catalog metadata was read.", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - "type": "string" - }, - "partition_by": { - "description": "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", - "items": { - "properties": { - "column": { - "type": "string" - }, - "transform": { - "type": "string" - } - }, - "required": ["column", "transform"], - "type": "object" - }, - "type": "array" - }, - "sort_by": { - "description": "Active sort expressions in key order, as the catalog reports them.", - "items": { - "properties": { - "direction": { - "type": "string" - }, - "expression": { - "type": "string" - }, - "nulls": { - "type": "string" - } - }, - "required": ["direction", "expression", "nulls"], - "type": "object" - }, - "type": "array" - } - }, - "required": ["observed_at", "partition_by", "sort_by"], - "type": "object" - }, - "pipeline_id": { - "description": "Warehouse replication pipeline identity.", - "type": "string" - }, - "reset_table": { - "description": "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", - "type": "boolean" - }, - "schema": { - "description": "Source PostgreSQL schema of the table.", - "type": "string" - } - }, - "required": [ - "application_status", - "desired", - "name", - "observation_status", - "observed", - "pipeline_id", - "reset_table", - "schema" - ], - "type": "object" - }, - "id": { - "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", - "example": "16385", - "maxLength": 10, - "pattern": "^[1-9]\\d*$", - "type": "string" - }, - "type": { - "description": "Resource type.", - "enum": ["warehouse_table_layout"], - "type": "string" - } - }, - "required": ["attributes", "id", "type"], - "type": "object" - } - }, - "required": ["data"], - "type": "object" - }, - "$comment": "Layout updates return orchestration fields that older layout reads do not include." - }, { "op": "add", "path": "/components/schemas/V2WarehouseQueryStatsResponse_Output", @@ -2773,7 +2508,7 @@ "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1query-stats", "value": { "get": { - "description": "Returns aggregate workload measurements over a bounded time range, using the project\u2019s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.\n\nThis endpoint is currently in its **Alpha** stage.", + "description": "Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.\n\nThis endpoint is currently in its **Alpha** stage.", "operationId": "v2-get-warehouse-query-stats", "parameters": [ { @@ -3157,14 +2892,15 @@ }, "required": ["data"], "type": "object" - } + }, + "$comment": "The Warehouse capacity contract is not yet in the deployed Management API specification." }, { "op": "add", "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1capacity", "value": { "get": { - "description": "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project\u2019s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.\n\nThis endpoint is currently in its **Alpha** stage.", + "description": "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.\n\nThis endpoint is currently in its **Alpha** stage.", "operationId": "v2-get-warehouse-capacity", "parameters": [ { diff --git a/packages/api/src/effect.unit.test.ts b/packages/api/src/effect.unit.test.ts index c6cc2eda89..61098ed1c4 100644 --- a/packages/api/src/effect.unit.test.ts +++ b/packages/api/src/effect.unit.test.ts @@ -146,40 +146,6 @@ describe("database OpenAPI response contract", () => { }); describe("makeApiClient", () => { - test("decodes Warehouse layout reads without update orchestration fields", () => - Effect.runPromise( - Effect.gen(function* () { - const body = { - data: { - type: "warehouse_table_layout", - id: "16385", - attributes: { - schema: "public", - name: "events", - desired: { sort_by: null, partition_by: [] }, - observation_status: "observed", - observed: { - sort_by: [], - partition_by: [], - observed_at: "2026-11-18T09:30:00Z", - }, - }, - }, - }; - const client = yield* makeApiClient(config).pipe( - Effect.provide( - httpClientLayer((request) => Effect.succeed(jsonResponse(request, 200, body))), - ), - ); - - const result = yield* client.v2.getWarehouseTableLayout({ - ref: "abcdefghijklmnopqrst", - table_id: "16385", - }); - expect(result).toEqual(body); - }), - )); - test("allows raw operations to override generated request headers", () => Effect.runPromise( Effect.gen(function* () { diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index cc2bbca132..164cca4dea 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -15560,12 +15560,10 @@ export const V2GetWarehouseTableLayoutInput = Schema.Struct({ export const V2GetWarehouseTableLayoutOutput = Schema.Struct({ data: Schema.Struct({ attributes: Schema.Struct({ - application_status: Schema.optionalKey( - Schema.String.annotate({ - description: - "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", - }), - ), + application_status: Schema.String.annotate({ + description: + "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", + }), desired: Schema.Struct({ partition_by: Schema.Union([ Schema.Array( @@ -15666,15 +15664,13 @@ export const V2GetWarehouseTableLayoutOutput = Schema.Struct({ }), Schema.Null, ]), - pipeline_id: Schema.optionalKey( - Schema.String.annotate({ description: "Warehouse replication pipeline identity." }), - ), - reset_table: Schema.optionalKey( - Schema.Boolean.annotate({ - description: - "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", - }), - ), + pipeline_id: Schema.String.annotate({ + description: "Warehouse replication pipeline identity.", + }), + reset_table: Schema.Boolean.annotate({ + description: + "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", + }), schema: Schema.String.annotate({ description: "Source PostgreSQL schema of the table." }), }), id: Schema.String.annotate({ diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index 11dab8f078..a17cb486c8 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -33251,7 +33251,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/V2WarehouseTableLayoutUpdateResponse_Output" + "$ref": "#/components/schemas/V2WarehouseTableLayoutResponse_Output" } } }, @@ -50179,7 +50179,16 @@ "type": "string" } }, - "required": ["desired", "name", "observation_status", "observed", "schema"], + "required": [ + "application_status", + "desired", + "name", + "observation_status", + "observed", + "pipeline_id", + "reset_table", + "schema" + ], "type": "object" }, "id": { @@ -50392,275 +50401,6 @@ "required": ["data"], "type": "object" }, - "V2WarehouseTableLayoutUpdateResponse_Output": { - "properties": { - "data": { - "properties": { - "attributes": { - "properties": { - "application_status": { - "description": "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", - "type": "string" - }, - "desired": { - "description": "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", - "properties": { - "partition_by": { - "description": "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", - "items": { - "properties": { - "column": { - "description": "Source column name.", - "type": "string" - }, - "transform": { - "oneOf": [ - { - "properties": { - "kind": { - "enum": ["identity"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["year"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["month"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["day"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["hour"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "count": { - "description": "Number of hash buckets.", - "exclusiveMinimum": true, - "maximum": 2147483647, - "minimum": 0, - "type": "integer" - }, - "kind": { - "enum": ["bucket"], - "type": "string" - } - }, - "required": ["count", "kind"], - "type": "object" - } - ] - } - }, - "required": ["column", "transform"], - "type": "object" - }, - "nullable": true, - "type": "array" - }, - "sort_by": { - "description": "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", - "oneOf": [ - { - "properties": { - "kind": { - "enum": ["none"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "kind": { - "enum": ["primary_key"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "properties": { - "columns": { - "items": { - "properties": { - "direction": { - "enum": ["asc", "desc"], - "type": "string" - }, - "name": { - "description": "Source column name.", - "type": "string" - }, - "nulls": { - "description": "Null placement. Null uses DuckLake's default placement.", - "enum": ["first", "last", null], - "nullable": true, - "type": "string" - } - }, - "required": ["direction", "name", "nulls"], - "type": "object" - }, - "type": "array" - }, - "kind": { - "enum": ["columns"], - "type": "string" - } - }, - "required": ["columns", "kind"], - "type": "object" - }, - { - "type": "object", - "nullable": true, - "enum": [null] - } - ] - } - }, - "required": ["partition_by", "sort_by"], - "type": "object" - }, - "name": { - "description": "Source PostgreSQL table name.", - "type": "string" - }, - "observation_status": { - "description": "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", - "enum": ["not_requested", "observed", "table_missing", "unavailable"], - "type": "string" - }, - "observed": { - "description": "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", - "nullable": true, - "properties": { - "observed_at": { - "description": "Time the catalog metadata was read.", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - "type": "string" - }, - "partition_by": { - "description": "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", - "items": { - "properties": { - "column": { - "type": "string" - }, - "transform": { - "type": "string" - } - }, - "required": ["column", "transform"], - "type": "object" - }, - "type": "array" - }, - "sort_by": { - "description": "Active sort expressions in key order, as the catalog reports them.", - "items": { - "properties": { - "direction": { - "type": "string" - }, - "expression": { - "type": "string" - }, - "nulls": { - "type": "string" - } - }, - "required": ["direction", "expression", "nulls"], - "type": "object" - }, - "type": "array" - } - }, - "required": ["observed_at", "partition_by", "sort_by"], - "type": "object" - }, - "pipeline_id": { - "description": "Warehouse replication pipeline identity.", - "type": "string" - }, - "reset_table": { - "description": "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", - "type": "boolean" - }, - "schema": { - "description": "Source PostgreSQL schema of the table.", - "type": "string" - } - }, - "required": [ - "application_status", - "desired", - "name", - "observation_status", - "observed", - "pipeline_id", - "reset_table", - "schema" - ], - "type": "object" - }, - "id": { - "description": "Source PostgreSQL table OID, as returned by the Warehouse tables list.", - "example": "16385", - "maxLength": 10, - "pattern": "^[1-9]\\d*$", - "type": "string" - }, - "type": { - "description": "Resource type.", - "enum": ["warehouse_table_layout"], - "type": "string" - } - }, - "required": ["attributes", "id", "type"], - "type": "object" - } - }, - "required": ["data"], - "type": "object" - }, "V2WarehouseQueryStatsResponse_Output": { "properties": { "data": { From 3d0f0ca4f2ed749164472e9c0b50847dea538f86 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 14:25:53 +0100 Subject: [PATCH 30/45] fix(api): reject Warehouse layout patches without a layout setting The layout update attributes are now a union of two closed objects, one requiring sort_by and one requiring partition_by, so an empty or reset-only patch fails locally before dry-run, consent and the request, as the server rejects it. Generated commands derive their flags from union attributes whose branches share their properties, and a missing choice reports "Pass at least one of --sort-by, --partition-by". --- apps/cli/scripts/api-command-derive.ts | 74 ++- .../scripts/api-command-derive.unit.test.ts | 75 +++ apps/cli/src/commands/api/SIDE_EFFECTS.md | 2 + .../api-command-bindings.integration.test.ts | 4 +- .../src/commands/api/api-command-request.ts | 58 ++- .../api/api-commands.integration.test.ts | 20 + .../cli/src/commands/api/generated.schemas.ts | 471 ++++++++++++------ packages/api/scripts/openapi-overrides.json | 368 ++++++++------ packages/api/src/generated/contracts.ts | 159 +++--- packages/api/src/generated/openapi.json | 356 +++++++------ 10 files changed, 1018 insertions(+), 569 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 74fd33dbdb..b8f6bda4ef 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -1,4 +1,5 @@ import type { OperationId } from "@supabase/api/effect"; +import { isDeepStrictEqual } from "node:util"; import { Cause, Exit, Predicate, Schema } from "effect"; import type { ApiNoun } from "../src/commands/api/api-command-policy.ts"; import type { @@ -191,6 +192,56 @@ const resolve = (spec: JsonObject, value: unknown): unknown => { return undefined; }; +const COMPOSITION_KEYWORDS = ["anyOf", "oneOf", "allOf"]; + +/** + * The fields of an envelope's attributes: a plain object, or an `anyOf` of closed objects that + * share identical properties and differ only in what they require. A field is required only when + * every branch requires it. + */ +const deriveAttributeFields = ( + spec: JsonObject, + attributes: JsonObject | undefined, +): { readonly properties: JsonObject; readonly required: ReadonlyArray } | undefined => { + if (attributes === undefined) return undefined; + const properties = asRecord(attributes.properties); + const composed = COMPOSITION_KEYWORDS.filter((keyword) => keyword in attributes); + if (composed.length === 0) { + return attributes.type === "object" && properties !== undefined + ? { properties, required: asArray(attributes.required) } + : undefined; + } + if (composed.length !== 1 || composed[0] !== "anyOf" || properties !== undefined) { + return undefined; + } + const branches = asArray(attributes.anyOf).map((branch) => asRecord(resolve(spec, branch))); + const resolvedProperties = (branch: JsonObject | undefined) => + Object.entries(asRecord(branch?.properties) ?? {}).map( + ([field, schema]) => [field, resolve(spec, schema)] as const, + ); + const [first] = branches; + const firstProperties = asRecord(first?.properties); + if ( + first === undefined || + firstProperties === undefined || + branches.length < 2 || + !branches.every( + (branch) => + branch?.type === "object" && + branch.additionalProperties === false && + isDeepStrictEqual(resolvedProperties(branch), resolvedProperties(first)), + ) + ) { + return undefined; + } + return { + properties: firstProperties, + required: asArray(first.required).filter((field) => + branches.every((branch) => asArray(branch?.required).includes(field)), + ), + }; +}; + const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"; const DROPPED_KEYWORDS: ReadonlySet = new Set(["discriminator", "xml", "externalDocs"]); const DATA_KEYWORDS: ReadonlySet = new Set([ @@ -934,14 +985,25 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const typeEnum = asArray(asRecord(resolve(spec, dataProperties?.type))?.enum); const attributes = asRecord(resolve(spec, dataProperties?.attributes)); const envelopeType = asString(typeEnum[0]); - const isEnvelope = + const hasEnvelopeShape = Object.keys(properties).length === 1 && typeEnum.length === 1 && - envelopeType !== undefined && - attributes?.type === "object" && - asRecord(attributes.properties) !== undefined; - const fieldProperties = isEnvelope ? asRecord(attributes?.properties) : properties; - const required = asArray(isEnvelope ? asRecord(attributes)?.required : bodySchema.required); + envelopeType !== undefined; + const attributeFields = hasEnvelopeShape + ? deriveAttributeFields(spec, attributes) + : undefined; + if ( + hasEnvelopeShape && + attributeFields === undefined && + COMPOSITION_KEYWORDS.some((keyword) => attributes !== undefined && keyword in attributes) + ) { + fail( + "unsupported in this runtime: envelope attributes use a schema composition other than an anyOf of closed objects over identical properties", + ); + } + const isEnvelope = hasEnvelopeShape && attributeFields !== undefined; + const fieldProperties = isEnvelope ? attributeFields.properties : properties; + const required = isEnvelope ? attributeFields.required : asArray(bodySchema.required); requestSchema = asRecord(content["application/json"])?.schema; body = isEnvelope ? { contentType: "application/json", kind: "json-envelope", type: envelopeType } diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 7809de4789..39becf5d36 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -39,6 +39,32 @@ const envelope = (attributes: Record) => ({ }, }); +const unionEnvelope = (branches: ReadonlyArray>) => ({ + content: { + "application/json": { + schema: { + type: "object", + properties: { + data: { + type: "object", + properties: { + type: { type: "string", enum: ["thing"] }, + attributes: { anyOf: branches }, + }, + }, + }, + }, + }, + }, +}); + +const closedBranch = (properties: Record, required: ReadonlyArray) => ({ + type: "object", + additionalProperties: false, + properties, + required, +}); + const thingNoun: ApiNoun = { description: "Manage things", feature: "warehouse", @@ -138,6 +164,55 @@ describe("deriveApiCommands", () => { ]); }); + it("derives envelope fields from an anyOf of closed objects and requires only what every branch requires", () => { + const properties = { name: { type: "string" }, a: { type: "string" }, b: { type: "string" } }; + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: unionEnvelope([ + closedBranch(properties, ["name", "a"]), + closedBranch(properties, ["name", "b"]), + ]), + }), + }); + + expect(result.problems).toEqual([]); + const [entry] = result.entries; + expect(entry?.body).toEqual({ + contentType: "application/json", + kind: "json-envelope", + type: "thing", + }); + expect(entry?.flags.map((flag) => [flag.name, flag.required])).toEqual([ + ["name", true], + ["a", false], + ["b", false], + ]); + expect(entry?.bindings).toContainEqual({ + location: "body", + name: "a", + pointer: "/data/attributes/a", + source: "flag", + flag: "a", + }); + }); + + it("rejects envelope attributes whose anyOf branches differ in properties", () => { + const result = derive({ + "create-thing": operation({ + ...create, + requestBody: unionEnvelope([ + closedBranch({ a: { type: "string" } }, ["a"]), + closedBranch({ c: { type: "string" } }, ["c"]), + ]), + }), + }); + + expect(result.problems.join("\n")).toContain( + "unsupported in this runtime: envelope attributes use a schema composition", + ); + }); + it("binds plain body fields at the body root and inlines referenced schemas", () => { const result = derive({ "create-thing": operation({ diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index 52c6d6de3f..0d5ae197c0 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -73,6 +73,8 @@ With `--wait`, the command also polls the read operation named in its reference outside the declared request-body fields, an unknown nested field or a missing required flag fails with no command request sent. Target resolution runs first, so the project picker and branch lookups in the table above can still run. +- A body whose fields form alternatives (the request needs one of several fields) reports a missing + choice as `Pass at least one of --a, --b`. - `--dry-run` prints `{method, path, query, headers, body}` and sends no command request, before consent. The linked-project cache read in the table above can still run. It shows the local request, not a server-resolved impact. diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index caac7d7466..1ec3fcffa9 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -202,7 +202,9 @@ const inputsOf = ( "attributes", ]); const envelope = Object.keys(attributes).length > 0; - const container = envelope ? attributes : operation.requestSchema; + // Union attributes share their properties across branches; the first branch is one valid choice. + const [firstBranch] = asList(attributes["anyOf"]).map(resolveRef); + const container = firstBranch ?? (envelope ? attributes : operation.requestSchema); const required = asList(container["required"]); const scalarTypes = ["boolean", "integer", "number", "string"]; const fields = Object.entries(asRecord(container["properties"])).map(([field, schema]): Input => { diff --git a/apps/cli/src/commands/api/api-command-request.ts b/apps/cli/src/commands/api/api-command-request.ts index 59607a07c2..fbcb939b28 100644 --- a/apps/cli/src/commands/api/api-command-request.ts +++ b/apps/cli/src/commands/api/api-command-request.ts @@ -164,25 +164,47 @@ export const assembleInput = Effect.fnUntraced(function* ( type Path = ReadonlyArray; -/** Paths of the required keys an issue tree reports missing; `undefined` when it holds any other failure. */ -const missingKeyPaths = (issue: SchemaIssue.Issue, path: Path): ReadonlyArray | undefined => { +/** Input fields of which a request needs at least one; a single path means that field is required. */ +type Requirement = ReadonlyArray; + +const pathKey = (path: Path) => path.map(String).join("/"); + +/** + * Requirements an issue tree reports missing: every required key is one requirement, and a union + * whose branches each miss one key is one requirement of alternatives. `undefined` when the tree + * holds any other failure. + */ +const missingKeyPaths = ( + issue: SchemaIssue.Issue, + path: Path, +): ReadonlyArray | undefined => { switch (issue._tag) { case "MissingKey": - return [path]; + return [[path]]; case "Pointer": return missingKeyPaths(issue.issue, [...path, ...issue.path]); case "Filter": case "Encoding": return missingKeyPaths(issue.issue, path); - case "Composite": + case "Composite": { + const requirements: Requirement[] = []; + for (const child of issue.issues) { + const childRequirements = missingKeyPaths(child, path); + if (childRequirements === undefined) return undefined; + requirements.push(...childRequirements); + } + return requirements.length === 0 ? undefined : requirements; + } case "AnyOf": { - const paths: Path[] = []; + const alternatives = new Map(); for (const child of issue.issues) { - const childPaths = missingKeyPaths(child, path); - if (childPaths === undefined) return undefined; - paths.push(...childPaths); + const childRequirements = missingKeyPaths(child, path); + if (childRequirements?.length !== 1) return undefined; + for (const alternative of childRequirements[0]!) { + alternatives.set(pathKey(alternative), alternative); + } } - return paths.length === 0 ? undefined : paths; + return alternatives.size === 0 ? undefined : [[...alternatives.values()]]; } default: return undefined; @@ -207,7 +229,23 @@ const flagAt = (entry: ApiCommandEntry, path: Path) => { }; const invalidRequest = (entry: ApiCommandEntry, error: Schema.SchemaError) => { - const paths = missingKeyPaths(error.issue, []); + const requirements = missingKeyPaths(error.issue, []); + const alternatives = requirements?.length === 1 ? requirements[0]! : undefined; + if (alternatives !== undefined && alternatives.length > 1) { + const bindings = alternatives.map((path) => flagAt(entry, path)); + if (bindings.every((binding) => binding !== undefined)) { + const names = bindings.map((binding) => `--${binding.flag}`).join(", "); + return new ApiCommandUsageError({ + message: `Pass at least one of ${names}`, + hint: bindings.every((binding) => binding.location === "body") + ? "Pass one of the flags, or include one of the fields in --body/--file." + : "Pass one of the flags.", + }); + } + } + const paths = requirements?.every((requirement) => requirement.length === 1) + ? requirements.map((requirement) => requirement[0]!) + : undefined; const missing = paths?.map((path) => flagAt(entry, path)); if (missing !== undefined && missing.every((binding) => binding !== undefined)) { const names = missing.map((binding) => `--${binding.flag}`).join(", "); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 5736aa2e70..b608125e95 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -976,6 +976,26 @@ describe("generated warehouse commands", () => { }); }); + it.effect.each([ + { flags: ["--reset-table"] }, + { flags: ["--reset-table", "--dry-run"] }, + { flags: [] }, + ])( + "rejects a patch with neither --sort-by nor --partition-by ($flags) and sends nothing", + ({ flags }) => { + const { sent, run } = setup([...argv, ...flags], { yes: true, route: accepted }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(failure).toBeInstanceOf(ApiCommandUsageError); + expect(failure).toMatchObject({ + message: "Pass at least one of --sort-by, --partition-by", + hint: "Pass one of the flags, or include one of the fields in --body/--file.", + }); + expect(sent).toEqual([]); + }); + }, + ); + it.effect("rejects a non-boolean reset before making a hosted request", () => { const reset = { data: { type: "warehouse_table_layout", attributes: { reset_table: "true" } }, diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index ff78ab5865..c4a39cb9dc 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -2116,177 +2116,356 @@ export const apiCommandSchemas = { data: { properties: { attributes: { - additionalProperties: false, - properties: { - partition_by: { - description: - "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", - items: { - additionalProperties: false, - properties: { - column: { - description: "Source column name.", - minLength: 1, - type: "string", - }, - transform: { - oneOf: [ - { - additionalProperties: false, - properties: { - kind: { - enum: ["identity"], - type: "string", - }, - }, - required: ["kind"], - type: "object", + anyOf: [ + { + additionalProperties: false, + properties: { + partition_by: { + description: + "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + items: { + additionalProperties: false, + properties: { + column: { + description: "Source column name.", + minLength: 1, + type: "string", }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["year"], - type: "string", + transform: { + oneOf: [ + { + additionalProperties: false, + properties: { + kind: { + enum: ["identity"], + type: "string", + }, + }, + required: ["kind"], + type: "object", }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["month"], - type: "string", + { + additionalProperties: false, + properties: { + kind: { + enum: ["year"], + type: "string", + }, + }, + required: ["kind"], + type: "object", }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["day"], - type: "string", + { + additionalProperties: false, + properties: { + kind: { + enum: ["month"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["day"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["hour"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + count: { + description: "Number of hash buckets.", + maximum: 2147483647, + type: "integer", + exclusiveMinimum: 0, + }, + kind: { + enum: ["bucket"], + type: "string", + }, + }, + required: ["count", "kind"], + type: "object", }, + ], + }, + }, + required: ["column", "transform"], + type: "object", + }, + type: ["array", "null"], + }, + reset_table: { + description: + "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + type: "boolean", + }, + sort_by: { + description: + "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + oneOf: [ + { + additionalProperties: false, + properties: { + kind: { + enum: ["none"], + type: "string", }, - required: ["kind"], - type: "object", }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["hour"], - type: "string", - }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["primary_key"], + type: "string", }, - required: ["kind"], - type: "object", }, - { - additionalProperties: false, - properties: { - count: { - description: "Number of hash buckets.", - maximum: 2147483647, - type: "integer", - exclusiveMinimum: 0, - }, - kind: { - enum: ["bucket"], - type: "string", + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + columns: { + items: { + additionalProperties: false, + properties: { + direction: { + enum: ["asc", "desc"], + type: "string", + }, + name: { + description: "Source column name.", + minLength: 1, + type: "string", + }, + nulls: { + description: + "Null placement. Null uses DuckLake's default placement.", + enum: ["first", "last", null], + type: ["string", "null"], + }, + }, + required: ["direction", "name"], + type: "object", }, + minItems: 1, + type: "array", + }, + kind: { + enum: ["columns"], + type: "string", }, - required: ["count", "kind"], - type: "object", }, - ], - }, + required: ["columns", "kind"], + type: "object", + }, + { + type: ["object", "null"], + enum: [null], + }, + ], }, - required: ["column", "transform"], - type: "object", }, - type: ["array", "null"], - }, - reset_table: { - description: - "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", - type: "boolean", + required: ["sort_by"], + type: "object", }, - sort_by: { - description: - "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", - oneOf: [ - { - additionalProperties: false, - properties: { - kind: { - enum: ["none"], - type: "string", + { + additionalProperties: false, + properties: { + partition_by: { + description: + "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + items: { + additionalProperties: false, + properties: { + column: { + description: "Source column name.", + minLength: 1, + type: "string", + }, + transform: { + oneOf: [ + { + additionalProperties: false, + properties: { + kind: { + enum: ["identity"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["year"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["month"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["day"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["hour"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + count: { + description: "Number of hash buckets.", + maximum: 2147483647, + type: "integer", + exclusiveMinimum: 0, + }, + kind: { + enum: ["bucket"], + type: "string", + }, + }, + required: ["count", "kind"], + type: "object", + }, + ], + }, }, + required: ["column", "transform"], + type: "object", }, - required: ["kind"], - type: "object", + type: ["array", "null"], }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["primary_key"], - type: "string", - }, - }, - required: ["kind"], - type: "object", + reset_table: { + description: + "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + type: "boolean", }, - { - additionalProperties: false, - properties: { - columns: { - items: { - additionalProperties: false, - properties: { - direction: { - enum: ["asc", "desc"], - type: "string", - }, - name: { - description: "Source column name.", - minLength: 1, - type: "string", - }, - nulls: { - description: - "Null placement. Null uses DuckLake's default placement.", - enum: ["first", "last", null], - type: ["string", "null"], + sort_by: { + description: + "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + oneOf: [ + { + additionalProperties: false, + properties: { + kind: { + enum: ["none"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + kind: { + enum: ["primary_key"], + type: "string", + }, + }, + required: ["kind"], + type: "object", + }, + { + additionalProperties: false, + properties: { + columns: { + items: { + additionalProperties: false, + properties: { + direction: { + enum: ["asc", "desc"], + type: "string", + }, + name: { + description: "Source column name.", + minLength: 1, + type: "string", + }, + nulls: { + description: + "Null placement. Null uses DuckLake's default placement.", + enum: ["first", "last", null], + type: ["string", "null"], + }, + }, + required: ["direction", "name"], + type: "object", }, + minItems: 1, + type: "array", + }, + kind: { + enum: ["columns"], + type: "string", }, - required: ["direction", "name"], - type: "object", }, - minItems: 1, - type: "array", + required: ["columns", "kind"], + type: "object", }, - kind: { - enum: ["columns"], - type: "string", + { + type: ["object", "null"], + enum: [null], }, - }, - required: ["columns", "kind"], - type: "object", - }, - { - type: ["object", "null"], - enum: [null], + ], }, - ], + }, + required: ["partition_by"], + type: "object", }, - }, - type: "object", + ], }, type: { description: "Resource type.", diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index a4192db319..d4064ff9d3 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -2069,6 +2069,179 @@ }, "$comment": "The Warehouse layout update contract is not yet in the deployed Management API specification." }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseTableLayoutPartitionBy", + "value": { + "description": "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + "items": { + "additionalProperties": false, + "properties": { + "column": { + "description": "Source column name.", + "minLength": 1, + "type": "string" + }, + "transform": { + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["identity"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["year"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["month"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["day"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["hour"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "count": { + "description": "Number of hash buckets.", + "exclusiveMinimum": true, + "maximum": 2147483647, + "minimum": 0, + "type": "integer" + }, + "kind": { + "enum": ["bucket"], + "type": "string" + } + }, + "required": ["count", "kind"], + "type": "object" + } + ] + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "nullable": true, + "type": "array" + }, + "$comment": "The Warehouse layout update contract is not yet in the deployed Management API specification. Shared by both attribute branches of the update request." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseTableLayoutSortBy", + "value": { + "description": "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["none"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["primary_key"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "columns": { + "items": { + "additionalProperties": false, + "properties": { + "direction": { + "enum": ["asc", "desc"], + "type": "string" + }, + "name": { + "description": "Source column name.", + "minLength": 1, + "type": "string" + }, + "nulls": { + "description": "Null placement. Null uses DuckLake's default placement.", + "enum": ["first", "last", null], + "nullable": true, + "type": "string" + } + }, + "required": ["direction", "name"], + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "kind": { + "enum": ["columns"], + "type": "string" + } + }, + "required": ["columns", "kind"], + "type": "object" + }, + { + "type": "object", + "nullable": true, + "enum": [null] + } + ] + }, + "$comment": "The Warehouse layout update contract is not yet in the deployed Management API specification. Shared by both attribute branches of the update request." + }, { "op": "add", "path": "/components/schemas/V2WarehouseTableLayoutUpdateRequest", @@ -2077,177 +2250,42 @@ "data": { "properties": { "attributes": { - "additionalProperties": false, - "properties": { - "partition_by": { - "description": "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", - "items": { - "additionalProperties": false, - "properties": { - "column": { - "description": "Source column name.", - "minLength": 1, - "type": "string" - }, - "transform": { - "oneOf": [ - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["identity"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["year"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["month"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["day"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["hour"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "count": { - "description": "Number of hash buckets.", - "exclusiveMinimum": true, - "maximum": 2147483647, - "minimum": 0, - "type": "integer" - }, - "kind": { - "enum": ["bucket"], - "type": "string" - } - }, - "required": ["count", "kind"], - "type": "object" - } - ] - } + "anyOf": [ + { + "additionalProperties": false, + "properties": { + "partition_by": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutPartitionBy" }, - "required": ["column", "transform"], - "type": "object" + "reset_table": { + "description": "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + "type": "boolean" + }, + "sort_by": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutSortBy" + } }, - "nullable": true, - "type": "array" - }, - "reset_table": { - "description": "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", - "type": "boolean" + "required": ["sort_by"], + "type": "object" }, - "sort_by": { - "description": "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", - "oneOf": [ - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["none"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["primary_key"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" + { + "additionalProperties": false, + "properties": { + "partition_by": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutPartitionBy" }, - { - "additionalProperties": false, - "properties": { - "columns": { - "items": { - "additionalProperties": false, - "properties": { - "direction": { - "enum": ["asc", "desc"], - "type": "string" - }, - "name": { - "description": "Source column name.", - "minLength": 1, - "type": "string" - }, - "nulls": { - "description": "Null placement. Null uses DuckLake's default placement.", - "enum": ["first", "last", null], - "nullable": true, - "type": "string" - } - }, - "required": ["direction", "name"], - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "kind": { - "enum": ["columns"], - "type": "string" - } - }, - "required": ["columns", "kind"], - "type": "object" + "reset_table": { + "description": "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + "type": "boolean" }, - { - "type": "object", - "nullable": true, - "enum": [null] + "sort_by": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutSortBy" } - ] + }, + "required": ["partition_by"], + "type": "object" } - }, - "type": "object" + ] }, "type": { "description": "Resource type.", @@ -2262,7 +2300,7 @@ "required": ["data"], "type": "object" }, - "$comment": "The Warehouse layout update contract is not yet in the deployed Management API specification." + "$comment": "The Warehouse layout update contract is not yet in the deployed Management API specification. Its attributes are a union of two branches so a patch with neither sort_by nor partition_by is rejected as the platform does." }, { "op": "add", diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 164cca4dea..12aa997d93 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -357,6 +357,68 @@ export const ThirdPartyAuth_Output = Schema.Struct({ updated_at: Schema.String, resolved_at: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])), }).annotate({ identifier: "ThirdPartyAuth_Output" }); +export const V2WarehouseTableLayoutPartitionBy = Schema.Union([ + Schema.Array( + Schema.Struct({ + column: Schema.String.annotate({ description: "Source column name." }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + transform: Schema.Union( + [ + Schema.Struct({ kind: Schema.Literal("identity") }), + Schema.Struct({ kind: Schema.Literal("year") }), + Schema.Struct({ kind: Schema.Literal("month") }), + Schema.Struct({ kind: Schema.Literal("day") }), + Schema.Struct({ kind: Schema.Literal("hour") }), + Schema.Struct({ + count: Schema.Number.annotate({ description: "Number of hash buckets." }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(2147483647).annotate({ + expected: "a value less than or equal to 2147483647", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + kind: Schema.Literal("bucket"), + }), + ], + { mode: "oneOf" }, + ), + }), + ).annotate({ + description: + "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + }), + Schema.Null, +]).annotate({ identifier: "V2WarehouseTableLayoutPartitionBy" }); +export const V2WarehouseTableLayoutSortBy = Schema.Union( + [ + Schema.Struct({ kind: Schema.Literal("none") }), + Schema.Struct({ kind: Schema.Literal("primary_key") }), + Schema.Struct({ + columns: Schema.Array( + Schema.Struct({ + direction: Schema.Literals(["asc", "desc"]), + name: Schema.String.annotate({ description: "Source column name." }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + nulls: Schema.optionalKey( + Schema.Union([Schema.Literals(["first", "last"]), Schema.Null]).annotate({ + description: "Null placement. Null uses DuckLake's default placement.", + }), + ), + }), + ).check(Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" })), + kind: Schema.Literal("columns"), + }), + Schema.Null, + ], + { mode: "oneOf" }, +).annotate({ + description: + "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + identifier: "V2WarehouseTableLayoutSortBy", +}); // recursive definitions export type JsonValue_Output = | string @@ -20669,85 +20731,28 @@ export const V2UpdateWarehouseTableLayoutInput = Schema.Struct({ }), ), data: Schema.Struct({ - attributes: Schema.Struct({ - partition_by: Schema.optionalKey( - Schema.Union([ - Schema.Array( - Schema.Struct({ - column: Schema.String.annotate({ description: "Source column name." }).check( - Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), - ), - transform: Schema.Union( - [ - Schema.Struct({ kind: Schema.Literal("identity") }), - Schema.Struct({ kind: Schema.Literal("year") }), - Schema.Struct({ kind: Schema.Literal("month") }), - Schema.Struct({ kind: Schema.Literal("day") }), - Schema.Struct({ kind: Schema.Literal("hour") }), - Schema.Struct({ - count: Schema.Number.annotate({ description: "Number of hash buckets." }) - .check(Schema.isInt().annotate({ expected: "an integer" })) - .check( - Schema.isLessThanOrEqualTo(2147483647).annotate({ - expected: "a value less than or equal to 2147483647", - }), - ) - .check( - Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" }), - ), - kind: Schema.Literal("bucket"), - }), - ], - { mode: "oneOf" }, - ), - }), - ).annotate({ + attributes: Schema.Union([ + Schema.Struct({ + partition_by: Schema.optionalKey(V2WarehouseTableLayoutPartitionBy), + reset_table: Schema.optionalKey( + Schema.Boolean.annotate({ description: - "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", }), - Schema.Null, - ]), - ), - reset_table: Schema.optionalKey( - Schema.Boolean.annotate({ - description: - "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", - }), - ), - sort_by: Schema.optionalKey( - Schema.Union( - [ - Schema.Struct({ kind: Schema.Literal("none") }), - Schema.Struct({ kind: Schema.Literal("primary_key") }), - Schema.Struct({ - columns: Schema.Array( - Schema.Struct({ - direction: Schema.Literals(["asc", "desc"]), - name: Schema.String.annotate({ description: "Source column name." }).check( - Schema.isMinLength(1).annotate({ - expected: "a value with a length of at least 1", - }), - ), - nulls: Schema.optionalKey( - Schema.Union([Schema.Literals(["first", "last"]), Schema.Null]).annotate({ - description: "Null placement. Null uses DuckLake's default placement.", - }), - ), - }), - ).check( - Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), - ), - kind: Schema.Literal("columns"), - }), - Schema.Null, - ], - { mode: "oneOf" }, - ).annotate({ - description: - "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", - }), - ), - }), + ), + sort_by: V2WarehouseTableLayoutSortBy, + }), + Schema.Struct({ + partition_by: V2WarehouseTableLayoutPartitionBy, + reset_table: Schema.optionalKey( + Schema.Boolean.annotate({ + description: + "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + }), + ), + sort_by: Schema.optionalKey(V2WarehouseTableLayoutSortBy), + }), + ]), type: Schema.Literal("warehouse_table_layout").annotate({ description: "Resource type." }), }), }); diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index a17cb486c8..ae80cc2b1c 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -50211,182 +50211,210 @@ "required": ["data"], "type": "object" }, + "V2WarehouseTableLayoutPartitionBy": { + "description": "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", + "items": { + "additionalProperties": false, + "properties": { + "column": { + "description": "Source column name.", + "minLength": 1, + "type": "string" + }, + "transform": { + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["identity"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["year"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["month"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["day"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["hour"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "count": { + "description": "Number of hash buckets.", + "exclusiveMinimum": true, + "maximum": 2147483647, + "minimum": 0, + "type": "integer" + }, + "kind": { + "enum": ["bucket"], + "type": "string" + } + }, + "required": ["count", "kind"], + "type": "object" + } + ] + } + }, + "required": ["column", "transform"], + "type": "object" + }, + "nullable": true, + "type": "array" + }, + "V2WarehouseTableLayoutSortBy": { + "description": "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["none"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "kind": { + "enum": ["primary_key"], + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "columns": { + "items": { + "additionalProperties": false, + "properties": { + "direction": { + "enum": ["asc", "desc"], + "type": "string" + }, + "name": { + "description": "Source column name.", + "minLength": 1, + "type": "string" + }, + "nulls": { + "description": "Null placement. Null uses DuckLake's default placement.", + "enum": ["first", "last", null], + "nullable": true, + "type": "string" + } + }, + "required": ["direction", "name"], + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "kind": { + "enum": ["columns"], + "type": "string" + } + }, + "required": ["columns", "kind"], + "type": "object" + }, + { + "type": "object", + "nullable": true, + "enum": [null] + } + ] + }, "V2WarehouseTableLayoutUpdateRequest": { "properties": { "data": { "properties": { "attributes": { - "additionalProperties": false, - "properties": { - "partition_by": { - "description": "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", - "items": { - "additionalProperties": false, - "properties": { - "column": { - "description": "Source column name.", - "minLength": 1, - "type": "string" - }, - "transform": { - "oneOf": [ - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["identity"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["year"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["month"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["day"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["hour"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "count": { - "description": "Number of hash buckets.", - "exclusiveMinimum": true, - "maximum": 2147483647, - "minimum": 0, - "type": "integer" - }, - "kind": { - "enum": ["bucket"], - "type": "string" - } - }, - "required": ["count", "kind"], - "type": "object" - } - ] - } + "anyOf": [ + { + "additionalProperties": false, + "properties": { + "partition_by": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutPartitionBy" }, - "required": ["column", "transform"], - "type": "object" + "reset_table": { + "description": "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + "type": "boolean" + }, + "sort_by": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutSortBy" + } }, - "nullable": true, - "type": "array" - }, - "reset_table": { - "description": "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", - "type": "boolean" + "required": ["sort_by"], + "type": "object" }, - "sort_by": { - "description": "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", - "oneOf": [ - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["none"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" - }, - { - "additionalProperties": false, - "properties": { - "kind": { - "enum": ["primary_key"], - "type": "string" - } - }, - "required": ["kind"], - "type": "object" + { + "additionalProperties": false, + "properties": { + "partition_by": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutPartitionBy" }, - { - "additionalProperties": false, - "properties": { - "columns": { - "items": { - "additionalProperties": false, - "properties": { - "direction": { - "enum": ["asc", "desc"], - "type": "string" - }, - "name": { - "description": "Source column name.", - "minLength": 1, - "type": "string" - }, - "nulls": { - "description": "Null placement. Null uses DuckLake's default placement.", - "enum": ["first", "last", null], - "nullable": true, - "type": "string" - } - }, - "required": ["direction", "name"], - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "kind": { - "enum": ["columns"], - "type": "string" - } - }, - "required": ["columns", "kind"], - "type": "object" + "reset_table": { + "description": "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", + "type": "boolean" }, - { - "type": "object", - "nullable": true, - "enum": [null] + "sort_by": { + "$ref": "#/components/schemas/V2WarehouseTableLayoutSortBy" } - ] + }, + "required": ["partition_by"], + "type": "object" } - }, - "type": "object" + ] }, "type": { "description": "Resource type.", From a7b14b9b63b0d272e223b5a4faee0e312c01945e Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 14:53:10 +0100 Subject: [PATCH 31/45] test(cli): send only valid inputs in the generated binding matrix Metrics commands get one range form instead of combining since with from/to, the metadata assertion that mirrored the surface under test is gone, and commands whose inputs are all required no longer repeat the same request. --- .../api-command-bindings.integration.test.ts | 78 ++++++------------- 1 file changed, 25 insertions(+), 53 deletions(-) diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 1ec3fcffa9..a1b425ff40 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -162,7 +162,6 @@ interface Input { readonly location: "query" | "body"; readonly field: string; readonly flag: string; - readonly pointer: string | undefined; readonly required: boolean; readonly sample: unknown; } @@ -189,7 +188,6 @@ const inputsOf = ( location: "query", field, flag: flagFor("query", field), - pointer: undefined, required: parameter["required"] === true, sample: sampleOf(parameter["schema"]), }; @@ -221,7 +219,6 @@ const inputsOf = ( location: "body", field, flag: flagFor("body", field), - pointer: `${envelope ? "/data/attributes" : ""}/${field}`, required: required.includes(field), sample: scalar ? sampleOf(schema) : JSON_SAMPLES[key], }; @@ -360,9 +357,6 @@ const rows = [ .flatMap((entry) => (entry.api === undefined ? [] : [{ ...entry, api: entry.api }])) .toSorted((a, b) => a.api.operationId.localeCompare(b.api.operationId)); -const bindingKey = (binding: { readonly location: string; readonly name: string }): string => - JSON.stringify(binding); - describe("generated command bindings", () => { it("covers every generated command", () => { expect(rows.map((row) => row.api.operationId)).toEqual( @@ -373,7 +367,14 @@ describe("generated command bindings", () => { for (const row of rows) { const { operationId } = row.api; const operation = operationOf(operationId); - const inputs = inputsOf(operationId, operation, row.api.bindings); + // The API rejects `since` combined with `from`/`to`; the relative form is the one sent here. + const inputs = inputsOf(operationId, operation, row.api.bindings).filter( + (input, _, all) => + input.location !== "query" || + (input.field !== "from" && input.field !== "to") || + !all.some((other) => other.field === "since"), + ); + const required = inputs.filter((input) => input.required); const positionals = positionalsOf(operation); const expectedPath = positionals.reduce( (path, { name, sample }) => path.replace(`{${name}}`, sample), @@ -381,36 +382,6 @@ describe("generated command bindings", () => { ); describe(row.path.join(" "), () => { - it("binds the path reference and every other input to the spec's location", () => { - expect(operation.template.match(/\{[^}]+\}/g)).toEqual([ - "{ref}", - ...positionals.map(({ name }) => `{${name}}`), - ]); - const expected = [ - { location: "path", name: "ref", source: "target" }, - ...positionals.map(({ name }) => ({ - location: "path", - name, - source: "argument", - argument: generated.find((entry) => entry.operationId === operationId)?.argument?.name, - })), - ...inputs.map((input) => - input.location === "query" - ? { location: "query", name: input.field, source: "flag", flag: input.flag } - : { - location: "body", - name: input.field, - pointer: input.pointer, - source: "flag", - flag: input.flag, - }, - ), - ]; - expect(row.api.bindings.map(bindingKey).toSorted()).toEqual( - expected.map(bindingKey).toSorted(), - ); - }); - it.effect("sends every input at its binding", () => Effect.gen(function* () { const requests = yield* send( @@ -429,22 +400,23 @@ describe("generated command bindings", () => { }), ); - it.effect("sends only the inputs the spec requires when no other flag is given", () => - Effect.gen(function* () { - const required = inputs.filter((input) => input.required); - const requests = yield* send( - row.path, - [...positionals.map(({ sample }) => sample), ...argvOf(required)], - operation.responseStatus, - ); - expect(requests).toHaveLength(1); - const [request] = requests; - expect(Object.fromEntries(new URLSearchParams(request?.search))).toEqual( - expectedQuery(required), - ); - expect(request?.body).toEqual(expectedBody(operation, required)); - }), - ); + if (required.length < inputs.length) { + it.effect("sends only the inputs the spec requires when no other flag is given", () => + Effect.gen(function* () { + const requests = yield* send( + row.path, + [...positionals.map(({ sample }) => sample), ...argvOf(required)], + operation.responseStatus, + ); + expect(requests).toHaveLength(1); + const [request] = requests; + expect(Object.fromEntries(new URLSearchParams(request?.search))).toEqual( + expectedQuery(required), + ); + expect(request?.body).toEqual(expectedBody(operation, required)); + }), + ); + } it("declares the operation's success response as the response result", () => { expect(Object.keys(apiCommandSchemas)).toContain(operationId); From 4d64866fc9db68ab1e19c2f19e16eb46b3c6f49d Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 15:00:52 +0100 Subject: [PATCH 32/45] fix(cli): reject -o in generated API commands and list request values in consent Generated commands now take their presentation from --output-format and the TTY alone, the same rule failures use, and reject -o/--output with a pointer to --output-format. YAML output goes away with it. Consent lists the validated request's path, query and body values, so destructive options such as --delete-data and --reset-table show in the prompt. A passed --timeout is validated even without --wait. --- apps/cli/src/commands/api/SIDE_EFFECTS.md | 43 +-- .../src/commands/api/api-command-execute.ts | 37 +-- .../src/commands/api/api-command-request.ts | 27 ++ .../src/commands/api/api-command.format.ts | 2 +- .../api/api-command.format.unit.test.ts | 2 +- .../src/commands/api/api-commands.e2e.test.ts | 18 +- .../api/api-commands.integration.test.ts | 264 ++++++++---------- apps/cli/src/commands/api/runtime.ts | 58 ++-- apps/cli/src/shared/cli/agent-output.ts | 5 - apps/cli/src/shared/cli/standard-errors.ts | 9 +- 10 files changed, 227 insertions(+), 238 deletions(-) diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index 0d5ae197c0..4eb66d9334 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -71,20 +71,25 @@ With `--wait`, the command also polls the read operation named in its reference that field, `null` included; text that is not JSON is a usage error naming the flag. - The input is validated before consent and before the command request: a top-level body key outside the declared request-body fields, an unknown nested field or a missing required flag - fails with no command request sent. Target resolution runs first, so the project picker and + fails with no command request sent. `-o`/`--output` and an invalid `--timeout` fail first, before + target resolution; for other input errors target resolution runs first, so the project picker and branch lookups in the table above can still run. - A body whose fields form alternatives (the request needs one of several fields) reports a missing choice as `Pass at least one of --a, --b`. - `--dry-run` prints `{method, path, query, headers, body}` and sends no command request, before consent. The linked-project cache read in the table above can still run. It shows the local request, not a server-resolved impact. -- Consent uses the command's summary as the action; it does not render an impact plan. +- Consent uses the command's summary as the action and lists what the validated request does: one + `name: value` line per non-ref path parameter, query parameter and body field (for an envelope + body, the fields under `data.attributes`). Scalars print as is; objects and arrays print as + compact JSON. ## `--wait` A command whose reference entry has a Wait section accepts `--wait` and `--timeout ` (a duration such as `90s` or `10m`; default `10m`; an invalid or non-positive value is a usage -error). +error). `--timeout` is validated whenever it is passed, even without `--wait`, before consent and +before any command request. - A mutation first sends its request, then reads the identity the wait needs from the response by the pointers in its reference entry. A missing value is a defect in the response and ends the wait @@ -148,20 +153,18 @@ and `--wait` record `true`. Generated field flags, `--body`, `--file` and `--tim ## Output -Text rendering applies on a terminal by default, with `--output-format text` (also when piped), and -with `-o pretty`. Piped runs, agent runs, `--output-format json|stream-json` and `-o json` keep the -API's JSON bytes. `-o` takes precedence over `--output-format`. - -| Mode | stdout | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| text presentation | the response as labelled fields and tables, nested objects as indented blocks; a collection prints its scalar fields as a table, with each item's nested fields, null shown as `-`, in a block below it, and a `points` sample series shows its last 10 samples in response order with an omission notice (`-o json` shows all of them), `-` for null or empty values; with `--wait` the final read response; an empty response prints `Done.` and an empty collection `No results` | -| JSON presentation | the API's JSON response bytes, unchanged, preserving unknown and null fields; with `--wait` the final read response | -| `-o json` | the same bytes; no `target` key is added | -| `-o yaml` | the same document as YAML; `-o pretty` selects text; other `-o` values are a usage error | -| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview in the selected JSON or YAML presentation | - -When the presentation is text and `--output-format` is `text`, each request, and with `--wait` the -whole polling phase, runs under a task that shows the polled status after 200 ms. On a terminal it -is a spinner; when stdout is not a terminal (for example `--output-format text` piped) the task -message prints as a step line on stdout before the response. JSON and YAML output show no progress. +The presentation is text only when `--output-format` is `text` and stdout is a terminal; successes +and failures follow the same rule. Piped runs (even with `--output-format text`), agent runs and +`--output-format json|stream-json` keep the API's JSON bytes. `-o`/`--output` is a usage error that +points to `--output-format`, raised before target resolution, consent or any request. + +| Mode | stdout | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| text presentation | the response as labelled fields and tables, nested objects as indented blocks; a collection prints its scalar fields as a table, with each item's nested fields, null shown as `-`, in a block below it, and a `points` sample series shows its last 10 samples in response order with an omission notice (`--output-format json` shows all of them), `-` for null or empty values; with `--wait` the final read response; an empty response prints `Done.` and an empty collection `No results` | +| JSON presentation | the API's JSON response bytes, unchanged, preserving unknown and null fields; with `--wait` the final read response | +| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | +| `--dry-run` otherwise | the request preview in the selected JSON presentation | + +With the text presentation, each request, and with `--wait` the whole polling phase, runs under a +task that shows the polled status after 200 ms, as a spinner on the terminal. JSON output shows no +progress. diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index f724f0111f..696da3f7b7 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -7,7 +7,6 @@ import type * as HttpClientResponse from "effect/http/HttpClientResponse"; import { CommandPlatformApi } from "../../auth/command-platform-api.service.ts"; import { parsePlanGateEnvelope, sanitizeErrorBody } from "../../command-internal/http-errors.ts"; -import { encodeStructYaml, shapeAny } from "../../command-internal/struct-output.encoders.ts"; import { Output } from "../../shared/output/output.service.ts"; import { readPointer } from "./api-command-pointer.ts"; import { definitionOf, type ApiRequestPreview } from "./api-command-request.ts"; @@ -27,30 +26,18 @@ const decodeJsonText = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.U const textDecoder = new TextDecoder(); const encodeJsonValue = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); -/** - * How a generated command prints its result: the API's JSON untouched, the same document as - * YAML, or a human-readable rendering. - */ -export type ApiOutputFormat = "text" | "json" | "yaml"; - -type ApiDocumentFormat = Exclude; - -/** Writes `value` as one document in `format`. */ -const writeDocument = Effect.fnUntraced(function* (value: unknown, format: ApiDocumentFormat) { - const output = yield* Output; - return yield* output.raw( - format === "yaml" ? encodeStructYaml(value, shapeAny) : `${encodeJsonValue(value)}\n`, - ); -}); +/** How a generated command prints its result: the API's JSON untouched, or a human-readable rendering. */ +export type ApiOutputFormat = "text" | "json"; -/** Writes the request a dry run would send, as text or as a document. */ +/** Writes the request a dry run would send, as text or as a JSON document. */ export const writeDryRun = Effect.fnUntraced(function* ( preview: ApiRequestPreview, format: ApiOutputFormat, ) { - if (format !== "text") return yield* writeDocument(preview, format); const output = yield* Output; - return yield* output.raw(renderDryRunText(preview)); + return yield* output.raw( + format === "text" ? renderDryRunText(preview) : `${encodeJsonValue(preview)}\n`, + ); }); const stringField = (source: unknown, key: string): string | undefined => { @@ -164,34 +151,30 @@ const parseResponse = (response: ApiCommandResponse): unknown => /** * Writes a success response. `json` passes JSON bytes through untouched, prints text as a JSON - * string and an empty body as `null`; `yaml` encodes that same document; `text` renders it for a - * person. + * string and an empty body as `null`; `text` renders the response for a person. */ export const writeApiResponse = Effect.fnUntraced(function* ( entry: Pick, response: ApiCommandResponse, format: ApiOutputFormat, ) { + const output = yield* Output; const hasBody = response.bytes.length > 0; const text = textDecoder.decode(response.bytes); if (format === "text") { - const output = yield* Output; if (!hasBody || entry.response.kind === "empty") return yield* output.raw("Done.\n"); const parsed = entry.response.kind === "json" ? decodeJsonText(text) : Option.none(); if (Option.isNone(parsed)) return yield* output.raw(text.endsWith("\n") ? text : `${text}\n`); return yield* output.raw(renderResponseText(parsed.value)); } - if (format === "json" && entry.response.kind === "json" && hasBody) { - const output = yield* Output; - return yield* output.rawBytes(response.bytes); - } + if (entry.response.kind === "json" && hasBody) return yield* output.rawBytes(response.bytes); const document = !hasBody || entry.response.kind === "empty" ? null : entry.response.kind === "text" ? text : Option.getOrElse(decodeJsonText(text), () => text); - return yield* writeDocument(document, format); + return yield* output.raw(`${encodeJsonValue(document)}\n`); }); interface WaitInput { diff --git a/apps/cli/src/commands/api/api-command-request.ts b/apps/cli/src/commands/api/api-command-request.ts index fbcb939b28..895c0ae3ce 100644 --- a/apps/cli/src/commands/api/api-command-request.ts +++ b/apps/cli/src/commands/api/api-command-request.ts @@ -318,3 +318,30 @@ export const previewRequest = (entry: ApiCommandEntry, decoded: object): ApiRequ body, }; }; + +const detailLine = (name: string, value: unknown): string => + `${name}: ${typeof value === "string" ? value : (JSON.stringify(value) ?? "null")}`; + +/** + * The `name: value` lines a consent prompt lists for a validated request: each path parameter + * other than the project ref, each query parameter and each body field, with an envelope body + * listing the fields of its `data.attributes`. Sensitive flag values stay masked. + */ +export const consentDetails = (entry: ApiCommandEntry, decoded: object): ReadonlyArray => { + const { pathParams } = definitionOf(entry); + const preview = previewRequest(entry, decoded); + const attributes = readPointer(preview.body, "/data/attributes"); + const bodyFields = + entry.body?.kind === "json-envelope" && isRecord(attributes) + ? attributes + : isRecord(preview.body) + ? preview.body + : {}; + return [ + ...pathParams + .filter((name) => name !== "ref") + .map((name) => detailLine(name, Reflect.get(decoded, name))), + ...Object.entries(preview.query).map(([name, value]) => detailLine(name, value)), + ...Object.entries(bodyFields).map(([name, value]) => detailLine(name, value)), + ]; +}; diff --git a/apps/cli/src/commands/api/api-command.format.ts b/apps/cli/src/commands/api/api-command.format.ts index 950ac967f7..e957e853bb 100644 --- a/apps/cli/src/commands/api/api-command.format.ts +++ b/apps/cli/src/commands/api/api-command.format.ts @@ -133,7 +133,7 @@ const arrayLines = ( offset === 0 ? [] : [ - `${indent}${INDENT}Showing last ${preview.length} of ${items.length} samples; ${offset} omitted; use -o json for all samples.`, + `${indent}${INDENT}Showing last ${preview.length} of ${items.length} samples; ${offset} omitted; use --output-format json for all samples.`, ]; if (isFlatObjectArray(preview)) { return [...notice, ...objectTable(preview, unionKeys(preview), indent)]; diff --git a/apps/cli/src/commands/api/api-command.format.unit.test.ts b/apps/cli/src/commands/api/api-command.format.unit.test.ts index 01089d8cb7..68b1f2784c 100644 --- a/apps/cli/src/commands/api/api-command.format.unit.test.ts +++ b/apps/cli/src/commands/api/api-command.format.unit.test.ts @@ -48,7 +48,7 @@ describe("renderResponseText", () => { expect(output.indexOf("sample-2")).toBeGreaterThanOrEqual(0); expect(output.indexOf("sample-2")).toBeLessThan(output.indexOf("sample-11")); expect(output).toContain( - "Showing last 10 of 12 samples; 2 omitted; use -o json for all samples.", + "Showing last 10 of 12 samples; 2 omitted; use --output-format json for all samples.", ); expect(renderResponseText({ points: points.slice(2) })).not.toContain("omitted"); }); diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index b3b26d860f..4c93e3ee8c 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -150,7 +150,7 @@ it.live.each([ it.live("warehouse status reports a 409 as a conflict failure document on stderr", () => Effect.gen(function* () { - const { result } = yield* runWarehouse(["status", "-o", "json"], () => + const { result } = yield* runWarehouse(["status", "--output-format", "json"], () => json(409, { error: { code: "selection_conflict", @@ -220,7 +220,7 @@ it.live("warehouse enable --wait --output-format text renders the final response it.live("warehouse enable without --yes refuses to run when stdin is piped", () => Effect.gen(function* () { const { result, requests } = yield* runWarehouse( - ["enable", "--schema", "public", "-o", "json"], + ["enable", "--schema", "public", "--output-format", "json"], () => json(202, {}), { stdin: "" }, ); @@ -239,7 +239,17 @@ it.live("warehouse enable without --yes refuses to run when stdin is piped", () it.live("warehouse enable --wait prints the final status read", () => Effect.gen(function* () { const { result, requests } = yield* runWarehouse( - ["enable", "--schema", "public", "--yes", "--wait", "--timeout", "30s", "-o", "json"], + [ + "enable", + "--schema", + "public", + "--yes", + "--wait", + "--timeout", + "30s", + "--output-format", + "json", + ], ({ method }) => { if (method === "POST") return json(202, { data: { attributes: { selection_id: SEL } } }); return statusBody("succeeded"); @@ -257,7 +267,7 @@ it.live("warehouse enable --file - reads the request body piped on stdin", () => const accepted = `{"data":{"type":"warehouse_setup","attributes":{"selection_id":"${SEL}","status":"pending","future_field":{"nested":[1, 2]}}}}`; const body = '{"data":{"type":"warehouse_setup","attributes":{"schema":"public"}}}'; const { result, requests, bodies } = yield* runWarehouse( - ["enable", "--file", "-", "--yes", "-o", "json"], + ["enable", "--file", "-", "--yes", "--output-format", "json"], () => ({ status: 202, body: accepted }), { stdin: body }, ); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index b608125e95..b5ae8a94b9 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -1,7 +1,6 @@ import { BunServices } from "@effect/platform-bun"; import { describe, expect, it } from "@effect/vitest"; import type { OperationOutput } from "@supabase/api/effect"; -import { parse as parseYaml } from "yaml"; import { Cause, Console, @@ -23,7 +22,7 @@ import { respondToComplete } from "../../cli/complete.ts"; import { rootCommandForFeatures } from "../../cli/root.ts"; import { ExperimentalFlag, ROOT_GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; import { HostedMutationConsentRequiredError } from "../../command-internal/hosted-consent/hosted-consent.errors.ts"; -import { InvalidOutputFormatError } from "../../command-internal/output-formats.ts"; +import { unsupportedOutputFlagMessage } from "../../command-internal/output-formats.ts"; import { ExperimentalFeatureFlagError } from "../../shared/config/experimental-feature.ts"; import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; import type { OutputFormat } from "../../shared/output/types.ts"; @@ -59,7 +58,7 @@ import { apiCommands } from "./generated.ts"; import { readApiCommand } from "./api-command.annotation.ts"; import { readCommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; import { withApiCommands } from "./runtime.ts"; -import { standardFailureFor } from "../../shared/cli/standard-errors.ts"; +import { isMachineFailureMode, standardFailureFor } from "../../shared/cli/standard-errors.ts"; import { EventUpgradeSuggested } from "../../shared/telemetry/event-catalog.ts"; import { resolveApiCommandFeatures } from "./api-command-features.ts"; @@ -264,6 +263,8 @@ interface CliOpts { readonly outputFormat?: OutputFormat; /** Whether stdout is a terminal; defaults to a pipe. */ readonly stdoutIsTty?: boolean; + /** Runs on an interactive terminal that answers the consent prompt with these responses. */ + readonly confirmResponses?: ReadonlyArray; } /** @@ -281,7 +282,12 @@ const execute = (argv: ReadonlyArray, opts: CliOpts) => { }; const setup = (argv: ReadonlyArray, opts: CliOpts) => { - const out = mockOutput({ format: opts.outputFormat ?? "text" }); + const interactive = opts.confirmResponses !== undefined; + const out = mockOutput({ + format: opts.outputFormat ?? "text", + interactive, + ...(interactive ? { promptConfirmResponses: opts.confirmResponses } : {}), + }); const { args, sent, run } = execute(argv, opts); const layer = Layer.mergeAll( buildTestRuntime({ @@ -289,13 +295,13 @@ const setup = (argv: ReadonlyArray, opts: CliOpts) => { api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), ...(opts.analytics === undefined ? {} : { analytics: opts.analytics }), cliSettings: mockCommandSettings({ workdir: tempRoot.current }), - tty: mockTty({ stdinIsTty: false, stdoutIsTty: opts.stdoutIsTty ?? false }), + tty: mockTty({ stdinIsTty: interactive, stdoutIsTty: opts.stdoutIsTty ?? interactive }), stdin: mockStdin(false), cliArgs: args, }), cliServices(tempRoot.current, args), ); - return { out, sent, run: run.pipe(Effect.provide(layer)) }; + return { args, out, sent, run: run.pipe(Effect.provide(layer)) }; }; const failureOf = (exit: Exit.Exit): unknown => @@ -355,30 +361,22 @@ describe("generated warehouse commands", () => { }, }; - it.effect.each(["json", "yaml"] as const)( - "preserves zero targets, capabilities and unavailable observations as %s", - (format) => { - const { out, sent, run } = setup( - ["warehouse", "status", ...(format === "yaml" ? ["-o", "yaml"] : [])], - { route: ok(body) }, - ); - return Effect.gen(function* () { - yield* run; - expect(sent).toEqual([ - { - method: "GET", - path: `/v2/projects/${VALID_REF}/warehouse/status`, - search: "", - body: undefined, - }, - ]); - expect( - format === "yaml" ? Bun.YAML.parse(out.stdoutText) : decodeJson(out.stdoutText), - ).toEqual(body); - expect(out.progressEvents).toEqual([]); - }); - }, - ); + it.effect("preserves zero targets, capabilities and unavailable observations as JSON", () => { + const { out, sent, run } = setup(["warehouse", "status"], { route: ok(body) }); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([ + { + method: "GET", + path: `/v2/projects/${VALID_REF}/warehouse/status`, + search: "", + body: undefined, + }, + ]); + expect(decodeJson(out.stdoutText)).toEqual(body); + expect(out.progressEvents).toEqual([]); + }); + }); it.effect("labels configured readiness and unavailable observations in terminal output", () => { const { out, run } = setup(["warehouse", "status"], { route: ok(body), stdoutIsTty: true }); @@ -491,7 +489,7 @@ describe("generated warehouse commands", () => { }); it.effect("passes the document, including replication feedback, through as JSON", () => { - const { out, run } = setup(["warehouse", "tables", "list", "-o", "json"], { + const { out, run } = setup(["warehouse", "tables", "list"], { route: ok(body), }); return Effect.gen(function* () { @@ -565,7 +563,7 @@ describe("generated warehouse commands", () => { return Effect.gen(function* () { yield* run; expect(out.stdoutText).toContain( - "Showing last 10 of 12 samples; 2 omitted; use -o json for all samples.", + "Showing last 10 of 12 samples; 2 omitted; use --output-format json for all samples.", ); expect(out.stdoutText).not.toContain("1001"); expect(out.stdoutText).not.toContain("1002"); @@ -584,12 +582,9 @@ describe("generated warehouse commands", () => { "query_rate,query_duration_p95", "--interval", "5m", - "-o", - "json", ], { route: ok(response), - stdoutIsTty: true, }, ); return Effect.gen(function* () { @@ -609,28 +604,26 @@ describe("generated warehouse commands", () => { }); }); - it.effect("forwards fixed timestamps unchanged and preserves null samples in YAML", () => { + it.effect("forwards fixed timestamps unchanged and preserves null samples in JSON", () => { const from = "2026-11-18T09:30:00+01:00"; const to = "2026-11-18T10:00:00+01:00"; - const { sent, out, run } = setup([...argv, "--from", from, "--to", to, "-o", "yaml"], { + const { sent, out, run } = setup([...argv, "--from", from, "--to", to], { route: ok(response), - stdoutIsTty: true, }); return Effect.gen(function* () { yield* run; expect(Object.fromEntries(new URLSearchParams(sent[0]?.search))).toEqual({ from, to }); - expect(parseYaml(out.stdoutText)).toEqual(response); + expect(decodeJson(out.stdoutText)).toEqual(response); }); }); it.effect.each([ - { name: "terminal default", flags: [], stdoutIsTty: true }, - { name: "explicit text", flags: ["--output-format", "text"], stdoutIsTty: false }, - { name: "pretty alias", flags: ["-o", "pretty"], stdoutIsTty: false }, - ])("shows ranges, dimensions, and sample values with $name", ({ flags, stdoutIsTty }) => { + { name: "terminal default", flags: [] }, + { name: "explicit text on a terminal", flags: ["--output-format", "text"] }, + ])("shows ranges, dimensions, and sample values with $name", ({ flags }) => { const { out, run } = setup([...argv, ...flags], { route: ok(response), - stdoutIsTty, + stdoutIsTty: true, }); return Effect.gen(function* () { yield* run; @@ -723,14 +716,14 @@ describe("generated warehouse commands", () => { ); it.effect( - "forwards fixed timestamps and metric selection and keeps all dimensions in YAML", + "forwards fixed timestamps and metric selection and keeps all dimensions in JSON", () => { const from = "2026-11-18T09:30:00+01:00"; const to = "2026-11-18T10:00:00+01:00"; const selection = "activation_duration_p95,worker_admission_occupied"; const { sent, out, run } = setup( - [...argv, "--from", from, "--to", to, "--attributes", selection, "-o", "yaml"], - { route: ok(response), stdoutIsTty: true }, + [...argv, "--from", from, "--to", to, "--attributes", selection], + { route: ok(response) }, ); return Effect.gen(function* () { yield* run; @@ -740,7 +733,7 @@ describe("generated warehouse commands", () => { to, attributes: selection, }); - expect(parseYaml(out.stdoutText)).toEqual(response); + expect(decodeJson(out.stdoutText)).toEqual(response); }); }, ); @@ -1464,31 +1457,20 @@ describe("generated warehouse commands", () => { }); }); - it.effect("prints the dry-run preview as YAML under -o yaml", () => { - const { out, run } = setup( - ["warehouse", "enable", "--schema", "public", "--dry-run", "-o", "yaml"], - { route: accepted }, - ); - return Effect.gen(function* () { - yield* run; - expect(Bun.YAML.parse(out.stdoutText)).toEqual({ - method: "POST", - path: ENABLE_PATH, - query: {}, - headers: {}, - body: { data: { type: "warehouse_setup", attributes: { schema: "public" } } }, - }); - }); - }); - it.effect.each([ { name: "a send", argv: ["warehouse", "enable", "--schema", "public"] }, { name: "a dry run", argv: ["warehouse", "enable", "--schema", "public", "--dry-run"] }, { name: "a read", argv: ["warehouse", "status"] }, - ])("rejects -o env for $name as a usage error and sends nothing", ({ argv }) => { - const { sent, run } = setup([...argv, "-o", "env"], { yes: true, route: accepted }); + ])("rejects -o json for $name as a usage error and sends nothing", ({ argv }) => { + const { sent, run } = setup([...argv, "-o", "json"], { yes: true, route: accepted }); return Effect.gen(function* () { - expect(failureOf(yield* Effect.exit(run))).toBeInstanceOf(InvalidOutputFormatError); + const exit = yield* Effect.exit(run); + expect(failureOf(exit)).toEqual( + new ApiCommandUsageError({ + message: unsupportedOutputFlagMessage(argv.slice(0, 2).join(" ")), + }), + ); + expect(Exit.isFailure(exit) && standardFailureFor(exit.cause).exitCode).toBe(2); expect(sent).toEqual([]); }); }); @@ -1669,17 +1651,6 @@ describe("generated warehouse commands", () => { expect(analytics.captured.some((c) => c.event === EventUpgradeSuggested)).toBe(false); }); }); - - it.effect("prints a JSON response as YAML of the parsed document under -o yaml", () => { - const { out, run } = setup(["warehouse", "enable", "--schema", "public", "-o", "yaml"], { - yes: true, - route: accepted, - }); - return Effect.gen(function* () { - yield* run; - expect(Bun.YAML.parse(out.stdoutText)).toEqual(ACCEPTED); - }); - }); }); describe("help", () => { @@ -1876,30 +1847,14 @@ describe("generated warehouse commands", () => { }, ); - it.effect("prints the final status read as YAML under -o yaml", () => { - const { out, run } = setup( - ["warehouse", "enable", "--schema", "public", "--wait", "-o", "yaml"], - { - yes: true, - route: enableThenPoll([ - { status: 200, body: statusBody("pending") }, - { status: 200, body: statusBody("succeeded") }, - ]), - }, - ); - return Effect.gen(function* () { - const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); - yield* driveClock(fiber); - yield* Fiber.join(fiber); - expect(Bun.YAML.parse(out.stdoutText)).toEqual(statusBody("succeeded")); - }); - }); - - it.effect("rejects an invalid --timeout before sending anything", () => { - const { sent, run } = setup( - ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "soon"], - { yes: true, route: accepted }, - ); + it.effect.each([ + { + name: "with --wait", + argv: ["warehouse", "enable", "--schema", "public", "--wait", "--timeout", "soon"], + }, + { name: "without --wait", argv: ["warehouse", "disable", "--timeout", "soon"] }, + ])("rejects an invalid --timeout $name before sending anything", ({ argv }) => { + const { sent, run } = setup(argv, { yes: true, route: accepted }); return Effect.gen(function* () { expect(failureOf(yield* Effect.exit(run))).toBeInstanceOf(ApiCommandUsageError); expect(sent).toEqual([]); @@ -1963,53 +1918,47 @@ describe("generated warehouse commands", () => { }); }); - it.effect("renders text through a pipe when --output-format text is explicit", () => { + it.effect("keeps JSON for success and failure when --output-format text is piped", () => { + const piped = ["--output-format", "text"]; + const succeeded = setup(["warehouse", "enable", "--schema", "public", "--wait", ...piped], { + yes: true, + route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), + }); + const failed = setup(["warehouse", "status", ...piped], { + route: () => ({ status: 401, body: { message: "bad token" } }), + }); + return Effect.gen(function* () { + yield* succeeded.run; + expect(succeeded.out.stdoutText).toBe(encodeJson(RICH_STATUS)); + expect(succeeded.out.progressEvents).toEqual([]); + + const exit = yield* Effect.exit(failed.run); + expect(failureOf(exit)).toBeInstanceOf(ApiCommandStatusError); + expect(failed.out.stdoutText).toBe(""); + expect(isMachineFailureMode(failed.args, false, "text")).toBe(true); + }); + }); + + it.effect("keeps the API bytes and shows no progress for stream-json on a terminal", () => { const { out, run } = setup( - ["warehouse", "enable", "--schema", "public", "--wait", "--output-format", "text"], + ["warehouse", "enable", "--schema", "public", "--wait", "--output-format", "stream-json"], { yes: true, route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), + outputFormat: "stream-json", + stdoutIsTty: true, }, ); return Effect.gen(function* () { yield* run; - expect(out.stdoutText).toBe(STATUS_TEXT); + expect(out.stdoutText).toBe(encodeJson(RICH_STATUS)); + expect(out.progressEvents).toEqual([]); }); }); - it.effect( - "prints only the text rendering for -o pretty under --output-format stream-json", - () => { - const { out, run } = setup( - [ - "warehouse", - "enable", - "--schema", - "public", - "--wait", - "-o", - "pretty", - "--output-format", - "stream-json", - ], - { - yes: true, - route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), - outputFormat: "stream-json", - stdoutIsTty: true, - }, - ); - return Effect.gen(function* () { - yield* run; - expect(out.stdoutText).toBe(STATUS_TEXT); - expect(out.progressEvents).toEqual([]); - }); - }, - ); - - it.effect("keeps the API bytes for -o json on a terminal", () => { + it.effect("renders text on a terminal when --output-format text is explicit", () => { const { out, run } = setup( - ["warehouse", "enable", "--schema", "public", "--wait", "-o", "json"], + ["warehouse", "enable", "--schema", "public", "--wait", "--output-format", "text"], { yes: true, route: enableThenPoll([{ status: 200, body: RICH_STATUS }]), @@ -2018,7 +1967,7 @@ describe("generated warehouse commands", () => { ); return Effect.gen(function* () { yield* run; - expect(out.stdoutText).toBe(encodeJson(RICH_STATUS)); + expect(out.stdoutText).toBe(STATUS_TEXT); }); }); @@ -2110,7 +2059,7 @@ describe("generated warehouse commands", () => { "--output-format", "text", ], - { route: ok({}) }, + { route: ok({}), stdoutIsTty: true }, ); return Effect.gen(function* () { yield* run; @@ -2323,6 +2272,41 @@ describeHostedConsent("warehouse enable", { }, }); +describe("hosted consent details", () => { + it.effect.each([ + { + name: "a disable that deletes data", + argv: ["warehouse", "disable", "--delete-data"], + shown: ["delete_data: true"], + }, + { + name: "a layout update with a reset", + argv: [ + "warehouse", + "tables", + "layout", + "update", + "16385", + "--body", + encodeJson({ + data: { + type: "warehouse_table_layout", + attributes: { sort_by: null, reset_table: true }, + }, + }), + ], + shown: ["table_id: 16385", "sort_by: null", "reset_table: true"], + }, + ])("lists what $name will send before asking", ({ argv, shown }) => { + const { out, sent, run } = setup(argv, { route: accepted, confirmResponses: [false] }); + return Effect.gen(function* () { + yield* Effect.exit(run); + for (const line of shown) expect(out.stderrText).toContain(line); + expect(sent.filter((request) => request.method !== "GET")).toEqual([]); + }); + }); +}); + const disableConsentCommand = commandTreeFor({ apiFeatures: ["warehouse"] }).get( "warehouse disable", )?.command; diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 06fe703d3a..1001a37ba8 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -10,18 +10,17 @@ import { withCommandStage, } from "../../command-internal/command-stage/command-stage.annotation.ts"; import { parseDuration } from "../../command-internal/duration.ts"; -import { OutputFlag } from "../../command-internal/global-flags.ts"; +import { GLOBAL_OUTPUT_FORMATS, OutputFlag } from "../../command-internal/global-flags.ts"; import { requireHostedMutationConsent } from "../../command-internal/hosted-consent/hosted-consent.ts"; +import { unsupportedOutputFlagMessage } from "../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../command-internal/management-api-runtime.layer.ts"; import { branchResolution } from "../../command-internal/target/branch-resolution.ts"; import { resolveProjectTarget } from "../../command-internal/target/resolve-project-target.ts"; import { projectTargetFlags } from "../../command-internal/target/target-flags.ts"; import { withTargetPolicy } from "../../command-internal/target/target-policy.ts"; import { projectRefPicker } from "../../config/project-ref.layer.ts"; -import { CliArgs } from "../../shared/cli/cli-args.service.ts"; -import { readExplicitOutputFormat } from "../../shared/cli/agent-output.ts"; +import { isMachineOutput } from "../../shared/cli/standard-errors.ts"; import { Output } from "../../shared/output/output.service.ts"; -import type { OutputFormat } from "../../shared/output/types.ts"; import { stdinLayer } from "../../shared/runtime/stdin.layer.ts"; import { Tty } from "../../shared/runtime/tty.service.ts"; import { withCommandTelemetry } from "../../telemetry/command-telemetry.ts"; @@ -40,6 +39,7 @@ import { type ApiFlagLocation, apiFlag } from "./api-command-flags.ts"; import { type ApiNoun, nouns } from "./api-command-policy.ts"; import { assembleInput, + consentDetails, decodeInput, previewRequest, readBodyOverride, @@ -159,27 +159,6 @@ const parseTimeoutMillis = (value: string) => const summaryText = (entry: Pick): string => entry.summary.replace(/\.$/, ""); -const OUTPUT_FORMATS: ReadonlyArray = ["json", "yaml", "pretty"]; - -/** - * How the result prints: `-o` decides first, then an explicit `--output-format`, then text only - * for a text-mode run on a terminal; everything else keeps the API's JSON. - */ -const presentationOf = (input: { - readonly outputFlag: Option.Option; - readonly args: ReadonlyArray; - readonly outputFormat: OutputFormat; - readonly stdoutIsTty: boolean; -}): ApiOutputFormat => { - const flag = Option.getOrUndefined(input.outputFlag); - if (flag === "yaml") return "yaml"; - if (flag === "json") return "json"; - if (flag === "pretty") return "text"; - const explicit = readExplicitOutputFormat(input.args); - if (Option.isSome(explicit)) return explicit.value === "text" ? "text" : "json"; - return input.outputFormat === "text" && input.stdoutIsTty ? "text" : "json"; -}; - /** * Runs `use` under a progress task when `visible`, handing it the task's message updater; the * task is cleared on success and marked failed or cancelled otherwise. @@ -227,21 +206,23 @@ const handle = Effect.fn("api-command.run")(function* ( const telemetryState = yield* TelemetryState; const cache = yield* LinkedProjectCache; const output = yield* Output; - const format = presentationOf({ - outputFlag: yield* OutputFlag, - args: (yield* CliArgs).args, - outputFormat: output.format, - stdoutIsTty: (yield* Tty).stdoutIsTty, - }); - const progress = format === "text" && output.format === "text"; + const outputFlag = yield* OutputFlag; + const format: ApiOutputFormat = isMachineOutput((yield* Tty).stdoutIsTty, output.format) + ? "json" + : "text"; + const progress = format === "text"; yield* Effect.annotateCurrentSpan("output.presentation", format); yield* Effect.gen(function* () { + if (Option.isSome(outputFlag)) { + return yield* new ApiCommandUsageError({ + message: unsupportedOutputFlagMessage(entry.command.join(" ")), + }); + } + const timeoutMillis = + flags.timeout === undefined ? 0 : yield* parseTimeoutMillis(flags.timeout); const ref = yield* resolveProjectTarget(flags); yield* Effect.gen(function* () { const waiting = resolved !== undefined && flags.wait === true; - const timeoutMillis = waiting - ? yield* parseTimeoutMillis(flags.timeout ?? DEFAULT_WAIT_TIMEOUT) - : 0; const override = yield* readBodyOverride({ body: flags.body ?? Option.none(), file: flags.file ?? Option.none(), @@ -254,7 +235,10 @@ const handle = Effect.fn("api-command.run")(function* ( return yield* writeDryRun(previewRequest(entry, decoded), format); } if (!entry.readOnly) { - yield* requireHostedMutationConsent({ action: summaryText(entry) }); + yield* requireHostedMutationConsent({ + action: summaryText(entry), + details: consentDetails(entry, decoded), + }); } if (waiting) { @@ -358,7 +342,7 @@ const leafOf = (entry: ApiCommandEntry, entries: ReadonlyArray) Command.withHandler((flags) => { const { api: _generated, argument: _argument, ...recorded } = flags; return handle(entry, resolved, flags).pipe( - withCommandTelemetry({ flags: recorded, outputFormats: OUTPUT_FORMATS }), + withCommandTelemetry({ flags: recorded, outputFormats: GLOBAL_OUTPUT_FORMATS }), ); }), // `stdinLayer`: `--file -` reads the request body from piped stdin. diff --git a/apps/cli/src/shared/cli/agent-output.ts b/apps/cli/src/shared/cli/agent-output.ts index 0b6ae41155..0807730cbf 100644 --- a/apps/cli/src/shared/cli/agent-output.ts +++ b/apps/cli/src/shared/cli/agent-output.ts @@ -65,11 +65,6 @@ function outputFormatFromArg(value: string | undefined): Option.Option): Option.Option { - return outputFormatFromArg(readLongFlag(args, "--output-format")); -} - function outputFlagFormatFromArg(value: string | undefined): Option.Option { switch (value) { case "env": diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index 25baf1ff73..b159352918 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -245,14 +245,17 @@ export const errorsContractForRun = ( return node === undefined ? "legacy" : readCommandErrorsContract(node); }; -/** Whether failures render as the JSON document: a machine `-o`, a resolved non-text output format, or stdout that is not a TTY. */ +/** Whether output is machine-readable: stdout is not a TTY or the resolved output format is not text. */ +export const isMachineOutput = (stdoutIsTty: boolean, outputFormat: OutputFormat): boolean => + !stdoutIsTty || outputFormat !== "text"; + +/** Whether failures render as the JSON document: a machine `-o` or machine output. */ export const isMachineFailureMode = ( args: ReadonlyArray, stdoutIsTty: boolean, outputFormat: OutputFormat, ): boolean => - !stdoutIsTty || - outputFormat !== "text" || + isMachineOutput(stdoutIsTty, outputFormat) || isMachineResourceFormat(Option.fromNullishOr(readOutputFlag(args))); /** Renders the failure as the stderr text: a leading blank line plus JSON, or a human message and hint. */ From 4a4f962f76fd85a08bc6018bb4b5135ee3439cef Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 15:09:38 +0100 Subject: [PATCH 33/45] fix(cli): build the API client lazily in generated commands A dry run against a literal ref now needs no access token, sends no request and leaves the linked-project cache untouched. Generated commands build the Management API client through the lazy factory, so the client exists only once a request is about to be sent. The lazy runtime layer has a new name that fits both of its consumers. A --wait poll now parses each response once. --- .../src/command-internal/db-config.layer.ts | 16 ++--- .../management-api-runtime.layer.ts | 17 +++--- apps/cli/src/commands/api/SIDE_EFFECTS.md | 32 +++++----- .../src/commands/api/api-command-execute.ts | 44 +++++++------ .../api/api-commands.integration.test.ts | 61 ++++++++++++++++--- apps/cli/src/commands/api/runtime.ts | 23 +++++-- apps/cli/src/commands/db/diff/diff.layers.ts | 4 +- apps/cli/src/commands/db/pull/pull.layers.ts | 4 +- .../cli/src/commands/db/query/query.layers.ts | 6 +- .../declarative/generate/generate.layers.ts | 4 +- apps/cli/src/commands/logs/logs.command.ts | 6 +- .../commands/migration/migration.layers.ts | 4 +- apps/cli/src/commands/pull/pull.layers.ts | 2 +- 13 files changed, 147 insertions(+), 76 deletions(-) diff --git a/apps/cli/src/command-internal/db-config.layer.ts b/apps/cli/src/command-internal/db-config.layer.ts index 7e4fef1339..957b9898ab 100644 --- a/apps/cli/src/command-internal/db-config.layer.ts +++ b/apps/cli/src/command-internal/db-config.layer.ts @@ -42,8 +42,8 @@ import { import { DbConnection, type PgConnInput } from "./db-connection.service.ts"; import { IdentityStitch } from "./identity-stitch.ts"; import { - linkedDbResolverRuntimeLayer, - type LinkedDbResolverRuntimeRequirements, + lazyManagementApiRuntimeLayer, + type LazyManagementApiRuntimeRequirements, } from "./management-api-runtime.layer.ts"; import * as Errors from "./db-config.errors.ts"; import { @@ -736,7 +736,7 @@ export const dbConfigResolverLayer = Layer.effect( // directly from its own ambient context). Calling them from here would otherwise leak those // services into `resolveConnection`/`resolvePoolerFallback`'s R (the interface promises // `never`), so every call site below re-closes the gap by additionally providing this layer of - // already-resolved values alongside `linkedDbResolverRuntimeLayer`. + // already-resolved values alongside `lazyManagementApiRuntimeLayer`. const localAmbientServices = Layer.mergeAll( Layer.succeed(FileSystem.FileSystem, fs), Layer.succeed(Path.Path, path), @@ -767,7 +767,7 @@ export const dbConfigResolverLayer = Layer.effect( Layer.succeed(WorkdirFlag, yield* WorkdirFlag), Layer.succeed(OutputFlag, yield* OutputFlag), Layer.succeed(DebugFlag, yield* DebugFlag), - // `linkedDbResolverRuntimeLayer`'s platform-API factory provides a DoH fetch layer that + // `lazyManagementApiRuntimeLayer`'s platform-API factory provides a DoH fetch layer that // reads `DnsResolverFlag`; snapshot it so the lazily built linked stack stays fully // self-provided (`resolveConnection`'s R stays `never`). Layer.succeed(DnsResolverFlag, yield* DnsResolverFlag), @@ -790,12 +790,12 @@ export const dbConfigResolverLayer = Layer.effect( BunServices.layer, BunCrypto.layerSecureRandom, ); - // Compile-time guard: if `linkedDbResolverRuntimeLayer`'s requirements ever + // Compile-time guard: if `lazyManagementApiRuntimeLayer`'s requirements ever // grow a service not captured above, this assignment fails to type-check (the // lazy `Effect.provide` in the `--linked` branch would otherwise leak that // service into `resolveConnection`'s R and only surface as a runtime panic). Mirrors the // `_serviceCoverageCheck` pattern in `management-api-runtime.layer.ts`. - const _ambientCoverageCheck: Layer.Layer = + const _ambientCoverageCheck: Layer.Layer = ambientLayer; void _ambientCoverageCheck; @@ -961,7 +961,7 @@ export const dbConfigResolverLayer = Layer.effect( effect.pipe( Effect.provide( Layer.mergeAll( - linkedDbResolverRuntimeLayer(["test", "db"]).pipe(Layer.provide(ambientLayer)), + lazyManagementApiRuntimeLayer(["test", "db"]).pipe(Layer.provide(ambientLayer)), localAmbientServices, ), ), @@ -1054,7 +1054,7 @@ export const dbConfigResolverLayer = Layer.effect( }).pipe( Effect.provide( Layer.mergeAll( - linkedDbResolverRuntimeLayer(["db", "dump"]).pipe(Layer.provide(ambientLayer)), + lazyManagementApiRuntimeLayer(["db", "dump"]).pipe(Layer.provide(ambientLayer)), localAmbientServices, ), ), diff --git a/apps/cli/src/command-internal/management-api-runtime.layer.ts b/apps/cli/src/command-internal/management-api-runtime.layer.ts index 419311f577..6ea308910b 100644 --- a/apps/cli/src/command-internal/management-api-runtime.layer.ts +++ b/apps/cli/src/command-internal/management-api-runtime.layer.ts @@ -121,12 +121,13 @@ type ManagementApiServices = | DebugLogger; /** - * Runtime layer for the `--linked` db-config resolver path (`db dump`, `db query`, - * `db schema declarative generate/sync`). Identical to `managementApiRuntimeLayer`, except the - * access token resolves lazily via `CommandPlatformApiFactory` on first use instead of eagerly, so - * `--linked --password …` invocations succeed without requiring a login. + * Management API runtime for commands that may finish without an access token (`--linked + * --password …` db commands, generated API commands under `--dry-run`). Identical to + * `managementApiRuntimeLayer`, except the token resolves lazily through `CommandPlatformApiFactory` + * on first use instead of at layer build. It requires `IdentityStitch` from the caller so the + * factory's client and the linked-project cache share one stitcher. */ -export function linkedDbResolverRuntimeLayer(subcommand: ReadonlyArray) { +export function lazyManagementApiRuntimeLayer(subcommand: ReadonlyArray) { const cliSettings = commandSettingsLayer.pipe(Layer.provide(debugLoggerLayer)); const httpClient = httpClientLayer.pipe(Layer.provide(debugLoggerLayer)); const credentials = commandCredentialsLayer.pipe( @@ -155,6 +156,6 @@ export function linkedDbResolverRuntimeLayer(subcommand: ReadonlyArray) return built; } -type LinkedDbResolverRuntime = ReturnType; -export type LinkedDbResolverRuntimeRequirements = - LinkedDbResolverRuntime extends Layer.Layer ? R : never; +type LazyManagementApiRuntime = ReturnType; +export type LazyManagementApiRuntimeRequirements = + LazyManagementApiRuntime extends Layer.Layer ? R : never; diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index 4eb66d9334..517e0a70d5 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -31,23 +31,23 @@ subcommand: a `Command.provide` on the group itself would be bypassed for every ## Files Read -| Path | Format | When | -| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- | -| `/supabase/config.json` | JSON | when present, to resolve `experimental.` before the command tree is built | -| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | -| `` | JSON | only with `--file `: the whole request body (`--file -` reads stdin) | -| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential | -| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | -| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | +| Path | Format | When | +| --------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `/supabase/config.json` | JSON | when present, to resolve `experimental.` before the command tree is built | +| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | +| `` | JSON | only with `--file `: the whole request body (`--file -` reads stdin) | +| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential, unless `--dry-run` | +| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | +| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | Commands never write project configuration, execute SQL locally or read stdin, except `--file -`. ## Files Written -| Path | Format | When | -| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | -| `/telemetry.json` | JSON | always, flushed on success and on failure | -| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref | +| Path | Format | When | +| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- | +| `/telemetry.json` | JSON | always, flushed on success and on failure | +| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref; never with `--dry-run` | ## API Routes @@ -58,7 +58,7 @@ can add: | Method | Path | Auth | Request body | Response (used fields) | | ------ | -------------------------------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive (project picker) | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}`; linked-project cache miss only (best-effort, after the command) | +| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}`; linked-project cache miss only (best-effort, after the command, never with `--dry-run`) | | `GET` | `/v1/projects/{parent}/branches` | Bearer token | none | `[{id, name, project_ref, is_default}]` — only for `--remote=`, and for a bare `--remote` followed by a word that could name a branch; `{parent}` is `SUPABASE_PROJECT_ID`, else the linked project | | `GET` | `/v1/branches/{id}` | Bearer token | none | `{ref, status, …}` — only for `--remote=` when no project is linked | @@ -77,8 +77,10 @@ With `--wait`, the command also polls the read operation named in its reference - A body whose fields form alternatives (the request needs one of several fields) reports a missing choice as `Pass at least one of --a, --b`. - `--dry-run` prints `{method, path, query, headers, body}` and sends no command request, before - consent. The linked-project cache read in the table above can still run. It shows the local - request, not a server-resolved impact. + consent. A literal ref target (`--remote=`, `--project-ref`) needs no access token, sends no + request and writes no linked-project cache; only local files are read. A branch name, a bare + `--remote` or the project picker still call the API as listed above. It shows the local request, + not a server-resolved impact. - Consent uses the command's summary as the action and lists what the validated request does: one `name: value` line per non-ref path parameter, query parameter and body field (for an envelope body, the fields under `data.attributes`). Scalars print as is; objects and arrays print as diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index 696da3f7b7..7ba3ae45ba 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -1,11 +1,10 @@ -import type { OperationId, OperationInput } from "@supabase/api/effect"; +import type { ApiClient, OperationId, OperationInput } from "@supabase/api/effect"; import { operationPermissions } from "@supabase/api/permissions"; import { Duration, Effect, Option, Predicate, Ref, Schedule, Schema } from "effect"; import * as HttpClientError from "effect/http/HttpClientError"; import * as Headers from "effect/http/Headers"; import type * as HttpClientResponse from "effect/http/HttpClientResponse"; -import { CommandPlatformApi } from "../../auth/command-platform-api.service.ts"; import { parsePlanGateEnvelope, sanitizeErrorBody } from "../../command-internal/http-errors.ts"; import { Output } from "../../shared/output/output.service.ts"; import { readPointer } from "./api-command-pointer.ts"; @@ -126,14 +125,14 @@ export interface ApiCommandResponse { } /** - * Sends the decoded input of `entry` and returns the 2xx response; any other status fails with - * the API's own message, code and hint. + * Sends the decoded input of `entry` through `api` and returns the 2xx response; any other status + * fails with the API's own message, code and hint. */ export const sendApiRequest = Effect.fnUntraced(function* ( + api: ApiClient, entry: Pick, decoded: OperationInput, ) { - const api = yield* CommandPlatformApi; const response = yield* api.executeRaw(definitionOf(entry), decoded); if (response.status < 200 || response.status >= 300) { return yield* statusError(entry.operationId, response); @@ -178,6 +177,7 @@ export const writeApiResponse = Effect.fnUntraced(function* ( }); interface WaitInput { + readonly api: ApiClient; readonly wait: ApiCommandWait; /** The operation the wait polls; its decoded input is `readInput`. */ readonly readEntry: ApiPollRead; @@ -223,10 +223,22 @@ const failureReason = (reason: unknown): string | undefined => { return sanitizeErrorBody(typeof reason === "string" ? reason : encodeJsonValue(reason)); }; -const classify = (wait: ApiCommandWait, response: ApiCommandResponse, statusHint: string) => { +/** One poll read: the response, its decoded JSON body and the status the wait reads from it. */ +interface PollRead { + readonly response: ApiCommandResponse; + readonly body: unknown; + readonly status: string | undefined; +} + +const readPoll = (wait: ApiCommandWait, response: ApiCommandResponse): PollRead => { const body = parseResponse(response); const status = readPointer(body, wait.status); - if (typeof status === "string" && wait.failed.includes(status)) { + return { response, body, status: typeof status === "string" ? status : undefined }; +}; + +const classify = (wait: ApiCommandWait, read: PollRead, statusHint: string) => { + const { response, body, status } = read; + if (status !== undefined && wait.failed.includes(status)) { const reason = wait.error === undefined ? undefined : failureReason(readPointer(body, wait.error)); return Effect.fail( @@ -237,7 +249,7 @@ const classify = (wait: ApiCommandWait, response: ApiCommandResponse, statusHint }), ); } - const done = typeof status === "string" && wait.succeeded.includes(status); + const done = status !== undefined && wait.succeeded.includes(status); return Effect.succeed({ done, response }); }; @@ -305,15 +317,13 @@ export const waitForOperation = Effect.fn("api-command.wait")(function* (input: const lastStatus = yield* Ref.make(null); const poll = Ref.update(attempts, (count) => count + 1).pipe( - Effect.andThen(sendApiRequest(readEntry, decoded)), - Effect.tap((response) => { - const status = readPointer(parseResponse(response), wait.status); - return Ref.set(lastStatus, typeof status === "string" ? status : null); - }), - Effect.flatMap((response) => classify(wait, response, hint)), - Effect.tap(({ response }) => { - const status = readPointer(parseResponse(response), wait.status); - return input.onPoll?.(typeof status === "string" ? status : undefined) ?? Effect.void; + Effect.andThen(sendApiRequest(input.api, readEntry, decoded)), + Effect.flatMap((response) => { + const read = readPoll(wait, response); + return Ref.set(lastStatus, read.status ?? null).pipe( + Effect.andThen(classify(wait, read, hint)), + Effect.tap(() => input.onPoll?.(read.status) ?? Effect.void), + ); }), Effect.withTracerEnabled(false), ); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index b5ae8a94b9..3c95de3ae9 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -203,10 +203,11 @@ const replyOf = (reply: Reply): Response => { }; /** Replaces `globalThis.fetch` while `body` runs: the one in-process seam under the real leaf. */ -const withApi = (route: Route, sent: Array) => { +const withApi = (route: Route, sent: Array, seen: Array) => { const stub = (input: string | URL | Request, init?: RequestInit): Promise => { const request = input instanceof Request ? input : new Request(String(input), init); const url = new URL(request.url); + seen.push(`${request.method} ${url.pathname}`); if (url.pathname === TARGET_LOOKUP_PATH) { return Promise.resolve(replyOf({ status: 200, body: {} })); } @@ -257,6 +258,8 @@ const cliServices = (workdir: string, args: ReadonlyArray) => interface CliOpts { readonly yes?: boolean; readonly route: Route; + /** Whether an access token is configured; defaults to true. */ + readonly token?: boolean; readonly root?: typeof warehouseRoot; readonly analytics?: ReturnType; /** The Output layer's resolved format; defaults to `text`. */ @@ -274,11 +277,14 @@ interface CliOpts { const execute = (argv: ReadonlyArray, opts: CliOpts) => { const args = [...argv, `--remote=${VALID_REF}`, ...(opts.yes === true ? ["--yes"] : [])]; const sent: Array = []; + const seen: Array = []; const run = withConfigEnv( - { SUPABASE_ACCESS_TOKEN: VALID_TOKEN, SUPABASE_NO_KEYRING: "1" }, + opts.token === false + ? { SUPABASE_ACCESS_TOKEN: "", SUPABASE_NO_KEYRING: "1", SUPABASE_HOME: tempRoot.current } + : { SUPABASE_ACCESS_TOKEN: VALID_TOKEN, SUPABASE_NO_KEYRING: "1" }, Command.runWith(opts.root ?? warehouseRoot, { version: "0.0.0-test" })(args), - ).pipe(withApi(opts.route, sent)); - return { args, sent, run }; + ).pipe(withApi(opts.route, sent, seen)); + return { args, sent, seen, run }; }; const setup = (argv: ReadonlyArray, opts: CliOpts) => { @@ -288,7 +294,7 @@ const setup = (argv: ReadonlyArray, opts: CliOpts) => { interactive, ...(interactive ? { promptConfirmResponses: opts.confirmResponses } : {}), }); - const { args, sent, run } = execute(argv, opts); + const { args, sent, seen, run } = execute(argv, opts); const layer = Layer.mergeAll( buildTestRuntime({ out, @@ -301,7 +307,7 @@ const setup = (argv: ReadonlyArray, opts: CliOpts) => { }), cliServices(tempRoot.current, args), ); - return { args, out, sent, run: run.pipe(Effect.provide(layer)) }; + return { args, out, sent, seen, run: run.pipe(Effect.provide(layer)) }; }; const failureOf = (exit: Exit.Exit): unknown => @@ -1399,13 +1405,14 @@ describe("generated warehouse commands", () => { describe("consent and dry run", () => { it.effect("prints exactly the request preview and sends nothing under --dry-run", () => { - const { out, sent, run } = setup( + const { out, sent, seen, run } = setup( ["warehouse", "enable", "--schema", "public", "--table", "a", "--dry-run"], { route: accepted }, ); return Effect.gen(function* () { yield* run; expect(sent).toEqual([]); + expect(seen).toEqual([]); expect(decodeJson(out.stdoutText)).toEqual({ method: "POST", path: ENABLE_PATH, @@ -1418,6 +1425,46 @@ describe("generated warehouse commands", () => { }); }); + it.effect( + "previews a mutation for a literal --remote ref with no access token, no request and no cache write", + () => { + const { out, seen, run } = setup( + ["warehouse", "enable", "--schema", "public", "--dry-run"], + { token: false, route: accepted }, + ); + return Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + + yield* run; + + expect(decodeJson(out.stdoutText)).toMatchObject({ method: "POST", path: ENABLE_PATH }); + expect(seen).toEqual([]); + expect( + yield* fs.exists( + path.join(tempRoot.current, "supabase", ".temp", "linked-project.json"), + ), + ).toBe(false); + }).pipe(Effect.provide(BunServices.layer)); + }, + ); + + it.effect("fails a send with no access token before any request", () => { + const { seen, run } = setup(["warehouse", "enable", "--schema", "public"], { + token: false, + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + const exit = yield* Effect.exit(run); + + expect(Exit.isFailure(exit) && Cause.pretty(exit.cause)).toContain( + "AccessTokenRequiredError", + ); + expect(seen).toEqual([]); + }); + }); + it.effect("masks a sensitive field supplied through --body in the preview", () => Effect.gen(function* () { const sensitiveEntry: ApiCommandEntry = { diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 1001a37ba8..6e5f0151d9 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -1,6 +1,7 @@ import { Array as Arr, Cause, Effect, Exit, Layer, Option } from "effect"; import { Argument, Command, Flag } from "effect/cli"; +import { CommandPlatformApiFactory } from "../../auth/command-platform-api-factory.service.ts"; import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; import { withStandardErrors } from "../../command-internal/command-errors/command-errors.annotation.ts"; import { withPermissions } from "../../command-internal/command-permissions/command-permissions.annotation.ts"; @@ -13,7 +14,8 @@ import { parseDuration } from "../../command-internal/duration.ts"; import { GLOBAL_OUTPUT_FORMATS, OutputFlag } from "../../command-internal/global-flags.ts"; import { requireHostedMutationConsent } from "../../command-internal/hosted-consent/hosted-consent.ts"; import { unsupportedOutputFlagMessage } from "../../command-internal/output-formats.ts"; -import { managementApiRuntimeLayer } from "../../command-internal/management-api-runtime.layer.ts"; +import { identityStitchLayer } from "../../command-internal/identity-stitch.ts"; +import { lazyManagementApiRuntimeLayer } from "../../command-internal/management-api-runtime.layer.ts"; import { branchResolution } from "../../command-internal/target/branch-resolution.ts"; import { resolveProjectTarget } from "../../command-internal/target/resolve-project-target.ts"; import { projectTargetFlags } from "../../command-internal/target/target-flags.ts"; @@ -234,6 +236,7 @@ const handle = Effect.fn("api-command.run")(function* ( yield* Effect.annotateCurrentSpan("run.outcome", "dry_run"); return yield* writeDryRun(previewRequest(entry, decoded), format); } + const api = yield* (yield* CommandPlatformApiFactory).make; if (!entry.readOnly) { yield* requireHostedMutationConsent({ action: summaryText(entry), @@ -251,12 +254,13 @@ const handle = Effect.fn("api-command.run")(function* ( changedOperationId: entry.operationId, ref, changed: yield* withTask(progress, summaryText(entry), () => - sendApiRequest(entry, decoded), + sendApiRequest(api, entry, decoded), ), }); const polling = summaryText(resolved.readEntry); const settled = yield* withTask(progress, polling, (update) => waitForOperation({ + api, wait: resolved.wait, readEntry: resolved.readEntry, statusEntry: resolved.statusEntry, @@ -271,11 +275,11 @@ const handle = Effect.fn("api-command.run")(function* ( return yield* writeApiResponse(resolved.readEntry, settled, format); } const response = yield* withTask(progress, summaryText(entry), () => - sendApiRequest(entry, decoded), + sendApiRequest(api, entry, decoded), ); yield* Effect.annotateCurrentSpan("run.outcome", "sent"); return yield* writeApiResponse(entry, response, format); - }).pipe(Effect.ensuring(cache.cache(ref))); + }).pipe(Effect.ensuring(flags.dryRun ? Effect.void : cache.cache(ref))); }).pipe(Effect.ensuring(telemetryState.flush)); }); @@ -345,8 +349,15 @@ const leafOf = (entry: ApiCommandEntry, entries: ReadonlyArray) withCommandTelemetry({ flags: recorded, outputFormats: GLOBAL_OUTPUT_FORMATS }), ); }), - // `stdinLayer`: `--file -` reads the request body from piped stdin. - Command.provide(Layer.mergeAll(managementApiRuntimeLayer(entry.command), stdinLayer)), + // `stdinLayer`: `--file -` reads the request body from piped stdin. `identityStitchLayer` is + // shared by the lazy runtime and the post-run telemetry. + Command.provide( + Layer.mergeAll( + lazyManagementApiRuntimeLayer(entry.command).pipe(Layer.provide(identityStitchLayer)), + identityStitchLayer, + stdinLayer, + ), + ), withTargetPolicy({ group: "hosted", consent: entry.readOnly ? "none" : "no" }), ); }; diff --git a/apps/cli/src/commands/db/diff/diff.layers.ts b/apps/cli/src/commands/db/diff/diff.layers.ts index b4a6774255..bc5aee8556 100644 --- a/apps/cli/src/commands/db/diff/diff.layers.ts +++ b/apps/cli/src/commands/db/diff/diff.layers.ts @@ -2,7 +2,7 @@ import { Layer } from "effect"; import { commandRuntimeLayer } from "../../../shared/runtime/command-runtime.layer.ts"; import { identityStitchLayer } from "../../../command-internal/identity-stitch.ts"; -import { linkedDbResolverRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; +import { lazyManagementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { telemetryStateLayer } from "../../../telemetry/telemetry-state.layer.ts"; import { migraRuntimeLayer, @@ -16,6 +16,6 @@ export const dbDiffRuntimeLayer = Layer.mergeAll( migraRuntimeLayer, identityStitchLayer, telemetryStateLayer, - linkedDbResolverRuntimeLayer(["db", "diff"]).pipe(Layer.provide(identityStitchLayer)), + lazyManagementApiRuntimeLayer(["db", "diff"]).pipe(Layer.provide(identityStitchLayer)), commandRuntimeLayer(["db", "diff"]), ); diff --git a/apps/cli/src/commands/db/pull/pull.layers.ts b/apps/cli/src/commands/db/pull/pull.layers.ts index b482763533..e72ecdcaf3 100644 --- a/apps/cli/src/commands/db/pull/pull.layers.ts +++ b/apps/cli/src/commands/db/pull/pull.layers.ts @@ -2,7 +2,7 @@ import { Layer } from "effect"; import { commandRuntimeLayer } from "../../../shared/runtime/command-runtime.layer.ts"; import { identityStitchLayer } from "../../../command-internal/identity-stitch.ts"; -import { linkedDbResolverRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; +import { lazyManagementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { telemetryStateLayer } from "../../../telemetry/telemetry-state.layer.ts"; import { migraRuntimeLayer, @@ -17,7 +17,7 @@ const dbSchemaPullRuntimeLayer = (command: ReadonlyArray) => migraRuntimeLayer, identityStitchLayer, telemetryStateLayer, - linkedDbResolverRuntimeLayer(command).pipe(Layer.provide(identityStitchLayer)), + lazyManagementApiRuntimeLayer(command).pipe(Layer.provide(identityStitchLayer)), commandRuntimeLayer(command), ); diff --git a/apps/cli/src/commands/db/query/query.layers.ts b/apps/cli/src/commands/db/query/query.layers.ts index d6d2376e1d..969a0627f8 100644 --- a/apps/cli/src/commands/db/query/query.layers.ts +++ b/apps/cli/src/commands/db/query/query.layers.ts @@ -5,7 +5,7 @@ import { dbConfigLayer } from "../../../command-internal/db-config.layer.ts"; import { dbConnectionLayer } from "../../../command-internal/db-connection.sql-pg.layer.ts"; import { debugLoggerLayer } from "../../../command-internal/debug-logger.layer.ts"; import { identityStitchLayer } from "../../../command-internal/identity-stitch.ts"; -import { linkedDbResolverRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; +import { lazyManagementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { telemetryOutputFormatLayer } from "../../../telemetry/telemetry-output-format.layer.ts"; import { aiToolLayer } from "../../../shared/telemetry/ai-tool.layer.ts"; import { randomLayer } from "../../../shared/runtime/random.layer.ts"; @@ -15,7 +15,7 @@ import { stdinLayer } from "../../../shared/runtime/stdin.layer.ts"; * Runtime layer for `supabase db query`. * * The `--local`/`--db-url` paths go through `DbConfigResolver` + `DbConnection` (auth-free). The - * `--linked` path POSTs to the Management API, supplied by `linkedDbResolverRuntimeLayer`, which + * `--linked` path POSTs to the Management API, supplied by `lazyManagementApiRuntimeLayer`, which * exposes the access token lazily so building the runtime resolves no token — `--local`/`--db-url` * run without a login, since only the handler's `--linked` branch checks `getAccessToken`. */ @@ -38,5 +38,5 @@ export const dbQueryRuntimeLayer = Layer.mergeAll( stdinLayer, telemetryOutputFormatLayer, identityStitchLayer, - linkedDbResolverRuntimeLayer(["db", "query"]).pipe(Layer.provide(identityStitchLayer)), + lazyManagementApiRuntimeLayer(["db", "query"]).pipe(Layer.provide(identityStitchLayer)), ); diff --git a/apps/cli/src/commands/db/schema/declarative/generate/generate.layers.ts b/apps/cli/src/commands/db/schema/declarative/generate/generate.layers.ts index 0d67151702..ce76493bf0 100644 --- a/apps/cli/src/commands/db/schema/declarative/generate/generate.layers.ts +++ b/apps/cli/src/commands/db/schema/declarative/generate/generate.layers.ts @@ -3,7 +3,7 @@ import { Layer } from "effect"; import { commandRuntimeLayer } from "../../../../../shared/runtime/command-runtime.layer.ts"; import { stdinLayer } from "../../../../../shared/runtime/stdin.layer.ts"; import { identityStitchLayer } from "../../../../../command-internal/identity-stitch.ts"; -import { linkedDbResolverRuntimeLayer } from "../../../../../command-internal/management-api-runtime.layer.ts"; +import { lazyManagementApiRuntimeLayer } from "../../../../../command-internal/management-api-runtime.layer.ts"; import { telemetryStateLayer } from "../../../../../telemetry/telemetry-state.layer.ts"; import { pgDeltaCommandRuntimeLayer, @@ -15,7 +15,7 @@ export const dbSchemaDeclarativeGenerateRuntimeLayer = Layer.mergeAll( pgDeltaCommandRuntimeLayer, identityStitchLayer, telemetryStateLayer, - linkedDbResolverRuntimeLayer(["db", "schema", "declarative", "generate"]).pipe( + lazyManagementApiRuntimeLayer(["db", "schema", "declarative", "generate"]).pipe( Layer.provide(identityStitchLayer), ), commandRuntimeLayer(["db", "schema", "declarative", "generate"]), diff --git a/apps/cli/src/commands/logs/logs.command.ts b/apps/cli/src/commands/logs/logs.command.ts index d4ddc3ffd8..b8eef1955a 100644 --- a/apps/cli/src/commands/logs/logs.command.ts +++ b/apps/cli/src/commands/logs/logs.command.ts @@ -13,7 +13,7 @@ import { targetFlags } from "../../command-internal/target/target-flags.ts"; import { withTargetPolicy } from "../../command-internal/target/target-policy.ts"; import { withCommandTelemetry } from "../../telemetry/command-telemetry.ts"; import { withJsonErrorHandling } from "../../shared/output/json-error-handling.ts"; -import { linkedDbResolverRuntimeLayer } from "../../command-internal/management-api-runtime.layer.ts"; +import { lazyManagementApiRuntimeLayer } from "../../command-internal/management-api-runtime.layer.ts"; import { stdinLayer } from "../../shared/runtime/stdin.layer.ts"; import { stackTargetResolverLayer, stackApiLayer } from "../../command-internal/stack-target.ts"; import { logsTerminalLayer } from "./logs.browser.ts"; @@ -176,7 +176,7 @@ export const logsCommandFor = () => Command.provide(stdinLayer), Command.provide(stackTargetResolverLayer.pipe(Layer.provideMerge(stackApiLayer))), Command.provide( - linkedDbResolverRuntimeLayer(["logs"]).pipe(Layer.provide(identityStitchLayer)), + lazyManagementApiRuntimeLayer(["logs"]).pipe(Layer.provide(identityStitchLayer)), ), withTargetPolicy({ group: "selectable", @@ -207,7 +207,7 @@ export const logsCommandFor = () => ), Command.provide(stackTargetResolverLayer.pipe(Layer.provideMerge(stackApiLayer))), Command.provide( - linkedDbResolverRuntimeLayer(["logs", "sources"]).pipe( + lazyManagementApiRuntimeLayer(["logs", "sources"]).pipe( Layer.provide(identityStitchLayer), ), ), diff --git a/apps/cli/src/commands/migration/migration.layers.ts b/apps/cli/src/commands/migration/migration.layers.ts index 564fc9115f..8a8eacfd2f 100644 --- a/apps/cli/src/commands/migration/migration.layers.ts +++ b/apps/cli/src/commands/migration/migration.layers.ts @@ -9,7 +9,7 @@ import { dbConnectionLayer } from "../../command-internal/db-connection.sql-pg.l import { debugLoggerLayer } from "../../command-internal/debug-logger.layer.ts"; import { dockerRunLayer } from "../../command-internal/docker-run.layer.ts"; import { identityStitchLayer } from "../../command-internal/identity-stitch.ts"; -import { linkedDbResolverRuntimeLayer } from "../../command-internal/management-api-runtime.layer.ts"; +import { lazyManagementApiRuntimeLayer } from "../../command-internal/management-api-runtime.layer.ts"; import { telemetryStateLayer } from "../../telemetry/telemetry-state.layer.ts"; import { stackApiLayer } from "../../command-internal/stack-api.ts"; import { bundledPostgresClientLayer } from "../../command-internal/bundled-postgres-client.ts"; @@ -51,7 +51,7 @@ export const migrationDbRuntimeLayer = (commandPath: ReadonlyArray) => identityStitchLayer, telemetryStateLayer, stdinLayer, - linkedDbResolverRuntimeLayer(commandPath).pipe(Layer.provide(identityStitchLayer)), + lazyManagementApiRuntimeLayer(commandPath).pipe(Layer.provide(identityStitchLayer)), commandRuntimeLayer(commandPath), ); diff --git a/apps/cli/src/commands/pull/pull.layers.ts b/apps/cli/src/commands/pull/pull.layers.ts index 691423306a..714d175f13 100644 --- a/apps/cli/src/commands/pull/pull.layers.ts +++ b/apps/cli/src/commands/pull/pull.layers.ts @@ -27,7 +27,7 @@ import { /** * Runtime layer for `supabase pull`: composes `db pull`'s db-specific pieces with the eager * Management API stack and `MachineErrorContext` for single-envelope machine failures. Excludes - * `dbSchemaPullRuntimeLayer`'s `linkedDbResolverRuntimeLayer` piece, which independently binds + * `dbSchemaPullRuntimeLayer`'s `lazyManagementApiRuntimeLayer` piece, which independently binds * the same services via a different (lazy) factory — merging both would race over which * factory wins, since concurrent layer builds settle a shared singleton in build order. */ From 344ea717c9ee37a82bc07cdbec03b36a67778ca7 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 15:14:14 +0100 Subject: [PATCH 34/45] refactor(cli): mount generated API nouns only as new groups Warehouse, the only generated noun, owns its whole subtree, so merging generated commands into hand-written groups had no consumer. The join path, its generator exemptions and its fixture tests are removed; a noun that collides with a hand-written root command still fails generation. The Stack group gets its single group-level layer provide back. --- apps/cli/scripts/api-command-derive.ts | 50 +---- .../scripts/api-command-derive.unit.test.ts | 105 ++------- apps/cli/scripts/generate-api-commands.ts | 34 +-- apps/cli/src/commands/api/SIDE_EFFECTS.md | 10 - .../api/api-command-join.integration.test.ts | 206 ------------------ .../src/commands/api/api-command-policy.ts | 9 +- .../api-command-shapes.integration.test.ts | 2 +- apps/cli/src/commands/api/runtime.ts | 71 ++---- .../experimental/stack/stack.command.ts | 14 +- knip.jsonc | 3 - 10 files changed, 56 insertions(+), 448 deletions(-) delete mode 100644 apps/cli/src/commands/api/api-command-join.integration.test.ts diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index b8f6bda4ef..6517f20170 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -115,14 +115,6 @@ const parseXOperation = (block: unknown): ParsedXOperation => { }; }; -/** The hand-written command tree, as space-joined command paths. */ -export interface HandWrittenCommands { - /** Paths of the commands that have subcommands. */ - readonly groups: ReadonlySet; - /** Paths of the commands that have none. */ - readonly leaves: ReadonlySet; -} - interface DeriveInput { /** The parsed OpenAPI document. */ readonly spec: JsonObject; @@ -131,8 +123,8 @@ interface DeriveInput { readonly nouns: Readonly>; /** Kebab-case operation id to the camelCase key of the typed client's `operationDefinitions`. */ readonly operationIdMap: Readonly>; - /** Generated commands join hand-written groups; only an actual path collision fails. */ - readonly handWritten: HandWrittenCommands; + /** Names of the hand-written root commands; a generated noun may not reuse one. */ + readonly handWrittenRoots: ReadonlySet; } interface DeriveResult { @@ -780,7 +772,7 @@ const linkedWait = ( /** Derives the generated commands from each operation's `x-operation` and collects every lint failure. */ export function deriveApiCommands(input: DeriveInput): DeriveResult { - const { spec, generated, nouns, operationIdMap, handWritten } = input; + const { spec, generated, nouns, operationIdMap, handWrittenRoots } = input; const operations = collectOperations(spec); const problems: Array = []; const metadata = readMetadata(operations, generated, problems); @@ -789,21 +781,10 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const schemas: Record = {}; const commandOwners = new Map(); const groupPaths = new Set(); - const describedNouns = new Set(); - for (const [noun, definition] of Object.entries(nouns)) { - if (handWritten.groups.has(noun) && definition.description !== undefined) { - problems.push( - `noun "${noun}" describes the hand-written group "${noun}"; drop its description`, - ); - } - for (const subGroup of Object.keys(definition.groups ?? {})) { - const groupKey = [noun, ...subGroup.split(".")].join(" "); - if (handWritten.groups.has(groupKey)) { - problems.push( - `noun "${noun}" describes the hand-written group "${groupKey}"; drop its description`, - ); - } + for (const noun of Object.keys(nouns)) { + if (handWrittenRoots.has(noun)) { + problems.push(`noun "${noun}" is already a hand-written command`); } } @@ -833,30 +814,13 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { if (owner !== undefined) fail(`command "${commandKey}" is already generated by ${owner}`); commandOwners.set(commandKey, operationId); if (groupPaths.has(commandKey)) fail(`command "${commandKey}" is both a command and a group`); - if (handWritten.leaves.has(commandKey)) { - fail(`command "${commandKey}" is already a hand-written command`); - } - if (handWritten.groups.has(commandKey)) { - fail(`command "${commandKey}" is already a hand-written group`); - } - if (!describedNouns.has(command[0] ?? "")) { - describedNouns.add(command[0] ?? ""); - if (noun.description === undefined && !handWritten.groups.has(command[0] ?? "")) { - fail(`noun "${command[0]}" has no description in the nouns table`); - } - } for (let depth = 1; depth < command.length; depth += 1) { const groupKey = command.slice(0, depth).join(" "); - if (handWritten.leaves.has(groupKey)) { - fail( - `command "${commandKey}" needs "${groupKey}" as a group, but it is a hand-written command`, - ); - } if (depth < 2) continue; if (commandOwners.has(groupKey)) fail(`command "${groupKey}" is both a command and a group`); groupPaths.add(groupKey); const subGroup = command.slice(1, depth).join("."); - if (noun.groups?.[subGroup] === undefined && !handWritten.groups.has(groupKey)) { + if (noun.groups?.[subGroup] === undefined) { fail(`group "${subGroup}" has no description in the nouns table`); } } diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 39becf5d36..b8e4c78946 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -82,16 +82,6 @@ const pathOf = (id: string, node: unknown): string => { return `/v1/projects/{ref}/${id}${extra.join("")}`; }; -const handWritten = ( - tree: { - groups?: ReadonlyArray; - leaves?: ReadonlyArray; - } = {}, -) => ({ - groups: new Set(tree.groups ?? ["db"]), - leaves: new Set(tree.leaves), -}); - const derive = ( operations: Record, generated: ReadonlyArray = Object.keys(operations), @@ -117,7 +107,7 @@ const derive = ( operationIdMap: Object.fromEntries( Object.keys(operations).map((id) => [id, "v2EnableWarehouse" as const]), ), - handWritten: handWritten(), + handWrittenRoots: new Set(), ...options.overrides, }); @@ -1603,93 +1593,26 @@ describe("deriveApiCommands", () => { }); describe("hand-written commands", () => { - const shallow = { "create-thing": operation(create) }; - const deep = { - "create-thing": operation({ "x-operation": { group: "thing.sub", method: "create" } }), - }; - - it("joins a hand-written group without describing it", () => { - const result = derive(shallow, undefined, { - overrides: { - handWritten: handWritten({ groups: ["thing"], leaves: ["thing list"] }), - nouns: { thing: { feature: "warehouse" } }, - }, + it("rejects a noun named like a hand-written root command", () => { + const result = derive({ "create-thing": operation(create) }, undefined, { + overrides: { handWrittenRoots: new Set(["thing"]) }, }); - expect(result.problems).toEqual([]); - expect(result.entries.map((entry) => entry.command)).toEqual([["thing", "create"]]); + expect(result.problems).toContain('noun "thing" is already a hand-written command'); }); - it("joins a hand-written sub-group without describing it", () => { - const result = derive(deep, undefined, { - overrides: { - handWritten: handWritten({ groups: ["thing", "thing sub"] }), - nouns: { thing: { feature: "warehouse" } }, + it("requires a description for each generated sub-group", () => { + const result = derive( + { + "create-thing": operation({ "x-operation": { group: "thing.sub", method: "create" } }), }, - }); - - expect(result.problems).toEqual([]); - expect(result.entries.map((entry) => entry.command)).toEqual([["thing", "sub", "create"]]); - }); - - it.each([ - [ - "a hand-written command of the same path", - shallow, - { leaves: ["thing create"] }, - 'create-thing: command "thing create" is already a hand-written command', - ], - [ - "a hand-written group of the same path", - shallow, - { groups: ["thing create"] }, - 'create-thing: command "thing create" is already a hand-written group', - ], - [ - "a group path that is a hand-written command", - deep, - { leaves: ["thing sub"] }, - 'create-thing: command "thing sub create" needs "thing sub" as a group, but it is a hand-written command', - ], - ])("rejects %s", (_label, operations, tree, problem) => { - const result = derive(operations, undefined, { - overrides: { handWritten: handWritten(tree) }, - }); - - expect(result.problems).toContain(problem); - }); + undefined, + { overrides: { nouns: { thing: { description: "Manage things", feature: "warehouse" } } } }, + ); - it.each([ - [ - "a noun without a description when no hand-written group exists", - { groups: [] }, - { feature: "warehouse" as const }, - 'create-thing: noun "thing" has no description in the nouns table', - ], - [ - "a sub-group without a description when no hand-written group exists", - { groups: ["thing"] }, - { feature: "warehouse" as const }, + expect(result.problems).toContain( 'create-thing: group "sub" has no description in the nouns table', - ], - [ - "a description on a hand-written noun group", - { groups: ["thing"] }, - thingNoun, - 'noun "thing" describes the hand-written group "thing"; drop its description', - ], - [ - "a description on a hand-written sub-group", - { groups: ["thing", "thing sub"] }, - { feature: "warehouse" as const, groups: { sub: "Manage sub things" } }, - 'noun "thing" describes the hand-written group "thing sub"; drop its description', - ], - ])("requires descriptions only for generated groups: %s", (_label, tree, noun, problem) => { - const result = derive(deep, undefined, { - overrides: { handWritten: handWritten(tree), nouns: { thing: noun } }, - }); - - expect(result.problems).toContain(problem); + ); }); }); diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index faf7bc252d..a27780b8f3 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -1,6 +1,5 @@ import { BunRuntime, BunServices } from "@effect/platform-bun"; import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; -import type { Command } from "effect/cli"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; import { rootCommandForFeatures } from "../src/cli/root.ts"; import { generatedOperations, nouns } from "../src/commands/api/api-command-policy.ts"; @@ -10,7 +9,6 @@ import { ApiCommandGenerationError, collectOperations, deriveApiCommands, - type HandWrittenCommands, } from "./api-command-derive.ts"; class ApiCommandFormatError extends Data.TaggedError("ApiCommandFormatError")<{ @@ -35,30 +33,16 @@ const ROOT_OPTIONS: ReadonlyArray[0]> { stackBackend: "stack", computeEnabled: true }, ]; -const walkHandWritten = ( - command: Command.Command.Any, - prefix: ReadonlyArray, - into: { readonly groups: Set; readonly leaves: Set }, -): void => { - for (const { commands } of command.subcommands) { - for (const child of commands) { - const path = [...prefix, child.name]; - const isGroup = child.subcommands.length > 0; - (isGroup ? into.groups : into.leaves).add(path.join(" ")); - if (isGroup) walkHandWritten(child, path, into); +/** The root command names: the union of the trees every backend and feature option builds. */ +const handWrittenRoots = Effect.fn("ApiCommands.collectHandWrittenRoots")(function* () { + const roots = new Set(); + for (const options of ROOT_OPTIONS) { + for (const { commands } of rootCommandForFeatures(options).subcommands) { + for (const command of commands) roots.add(command.name); } } -}; - -/** The hand-written command tree: the union of the trees every backend and feature option builds. */ -const handWrittenCommands = Effect.fn("ApiCommands.walkHandWritten")(function* () { - const found = { groups: new Set(), leaves: new Set() }; - for (const options of ROOT_OPTIONS) walkHandWritten(rootCommandForFeatures(options), [], found); - yield* Effect.annotateCurrentSpan({ - "handWritten.groups": found.groups.size, - "handWritten.leaves": found.leaves.size, - }); - return found satisfies HandWrittenCommands; + yield* Effect.annotateCurrentSpan({ "handWritten.roots": roots.size }); + return roots; }); /** Formats in memory with the repo's oxfmt config so the committed files match `pnpm fmt`. */ @@ -110,7 +94,7 @@ const main = Effect.gen(function* () { generated: generatedOperations, nouns, operationIdMap: openApiOperationIdMap, - handWritten: yield* handWrittenCommands(), + handWrittenRoots: yield* handWrittenRoots(), }); if (problems.length > 0) return yield* new ApiCommandGenerationError({ problems }); diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index 517e0a70d5..f6f619311a 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -19,16 +19,6 @@ is resolved before the command tree is built, so `--experimental` alone does not commands. When the feature is disabled the noun is absent from help, completion and the generated command documentation. -## Joining hand-written groups - -A generated command joins the hand-written group of the same name, at any depth, so a noun such as -`warehouse` can sit beside hand-written `warehouse` commands. The generator fails only when a -generated command path equals a hand-written command or group, or when a group on its path is a -hand-written command. A hand-written group is described by its own code, so the nouns table gives a -description only to groups the generator creates. Joining rebuilds the group, so a hand-written -group carries only metadata (descriptions, flags, subcommands) and provides layers on each -subcommand: a `Command.provide` on the group itself would be bypassed for every subcommand. - ## Files Read | Path | Format | When | diff --git a/apps/cli/src/commands/api/api-command-join.integration.test.ts b/apps/cli/src/commands/api/api-command-join.integration.test.ts deleted file mode 100644 index 9a7230ab63..0000000000 --- a/apps/cli/src/commands/api/api-command-join.integration.test.ts +++ /dev/null @@ -1,206 +0,0 @@ -import { BunServices } from "@effect/platform-bun"; -import { describe, expect, it } from "@effect/vitest"; -import { openApiOperationIdMap } from "@supabase/api/effect"; -import openApiSpec from "@supabase/api/openapi.json"; -import { Console, Effect, Layer, Predicate, Schema, Stdio } from "effect"; -import { CliOutput, Command } from "effect/cli"; - -import { deriveApiCommands } from "../../../scripts/api-command-derive.ts"; -import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; -import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; -import { - VALID_REF, - VALID_TOKEN, - buildTestRuntime, - mockCommandPlatformApi, - mockCommandSettings, - useTempWorkdir, - withConfigEnv, -} from "../../../tests/helpers/command-mocks.ts"; -import { - fakeConsole, - mockOutput, - mockRuntimeInfo, - mockStdin, - mockTelemetryRuntime, - mockTty, -} from "../../../tests/helpers/mocks.ts"; -import type { ApiNoun } from "./api-command-policy.ts"; -import { withApiCommands } from "./runtime.ts"; - -const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); - -const isRecord = (value: unknown): value is Record => - Predicate.isObject(value) && !Array.isArray(value); - -const OPERATIONS = { - "v1-list-migration-history": { group: "fixture", method: "list" }, - "v1-get-a-migration": { group: "fixture.inner", method: "get" }, - "v1-apply-a-migration": { group: "fixture.fresh", method: "create" }, -}; - -const fixtureSpec = () => { - const spec: Record = structuredClone(openApiSpec); - for (const item of Object.values(isRecord(spec["paths"]) ? spec["paths"] : {})) { - for (const operation of Object.values(isRecord(item) ? item : {})) { - if (!isRecord(operation)) continue; - const operationId = String(operation["operationId"]); - if (!Object.hasOwn(OPERATIONS, operationId)) continue; - operation["x-operation"] = Reflect.get(OPERATIONS, operationId); - operation["x-scalar-stability"] = "experimental"; - } - } - return spec; -}; - -/** `fixture` and `fixture inner` are hand-written; only `fixture fresh` needs a description. */ -const fixtureNoun: ApiNoun = { - feature: "warehouse", - groups: { fresh: "Fresh fixtures" }, -}; - -const derived = deriveApiCommands({ - spec: fixtureSpec(), - generated: Object.keys(OPERATIONS), - nouns: { fixture: fixtureNoun }, - operationIdMap: openApiOperationIdMap, - handWritten: { - groups: new Set(["fixture", "fixture inner"]), - leaves: new Set(["fixture ping", "fixture inner pong"]), - }, -}); - -const pong = Command.make("pong", {}, () => Console.log("handwritten pong")).pipe( - Command.withDescription("Answer from the inner group"), -); -const inner = Command.make("inner").pipe( - Command.withDescription("Hand-written inner group"), - Command.withSubcommands([pong]), -); -const ping = Command.make("ping", {}, () => Console.log("handwritten ping")).pipe( - Command.withDescription("Answer from the group"), -); -const fixtureGroup = Command.make("fixture").pipe( - Command.withDescription("Hand-written fixture group"), - Command.withSubcommands([ping, { group: "Nested", commands: [inner] }]), -); - -const MIGRATION_VERSION = "20250312000000"; -const MIGRATIONS_PATH = `/v1/projects/${VALID_REF}/database/migrations`; -const tempRoot = useTempWorkdir("supabase-api-join-int-"); - -const run = ( - args: ReadonlyArray, - enabledFeatures: ReadonlyArray = ["warehouse"], -) => { - const root = Command.make("supabase").pipe( - Command.withSubcommands( - withApiCommands([fixtureGroup], enabledFeatures, { - nouns: { fixture: fixtureNoun }, - entries: derived.entries, - }), - ), - Command.withGlobalFlags(GLOBAL_FLAGS), - ); - const out = mockOutput({ format: "text" }); - const { console, calls } = fakeConsole(); - const layer = Layer.mergeAll( - buildTestRuntime({ - out, - api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), - cliSettings: mockCommandSettings({ workdir: tempRoot.current }), - tty: mockTty({ stdinIsTty: false, stdoutIsTty: false }), - stdin: mockStdin(false), - cliArgs: args, - }), - BunServices.layer, - CliOutput.layer(textCliOutputFormatter()), - Layer.succeed(ExperimentalFlag, false), - mockTelemetryRuntime({ configDir: tempRoot.current }), - mockRuntimeInfo({ cwd: tempRoot.current, homeDir: tempRoot.current }), - Stdio.layerTest({ args: Effect.succeed(args) }), - ); - const effect = withConfigEnv( - { SUPABASE_ACCESS_TOKEN: VALID_TOKEN, SUPABASE_NO_KEYRING: "1" }, - Command.runWith(root, { version: "0.0.0-test" })(args), - ).pipe(Effect.provideService(Console.Console, console), Effect.provide(layer)); - return { out, output: () => calls.join("\n"), effect }; -}; - -describe("generated commands joining hand-written groups", () => { - it("derives the fixture commands without problems", () => { - expect(derived.problems).toEqual([]); - expect(derived.entries.map((entry) => entry.command.join(" "))).toEqual([ - "fixture fresh create", - "fixture inner get", - "fixture list", - ]); - }); - - it.effect.each([ - { argv: ["fixture", "ping"], expected: "handwritten ping" }, - { argv: ["fixture", "inner", "pong"], expected: "handwritten pong" }, - ])("still runs the hand-written command $argv", ({ argv, expected }) => { - const { output, effect } = run(argv); - return Effect.gen(function* () { - yield* effect; - expect(output()).toContain(expected); - }); - }); - - it.effect.each([ - { argv: ["fixture", "list"], method: "GET", path: MIGRATIONS_PATH }, - { - argv: ["fixture", "inner", "get", MIGRATION_VERSION], - method: "GET", - path: `${MIGRATIONS_PATH}/${MIGRATION_VERSION}`, - }, - { - argv: ["fixture", "fresh", "create", "--query", "select 1"], - method: "POST", - path: MIGRATIONS_PATH, - }, - ])("runs the generated command $argv beside the hand-written ones", ({ argv, method, path }) => { - const { out, effect } = run([...argv, `--remote=${VALID_REF}`, "--yes", "--dry-run"]); - return Effect.gen(function* () { - yield* effect; - expect(decodeJson(out.stdoutText)).toMatchObject({ method, path }); - }); - }); - - it.effect("lists generated and hand-written commands together in the group help", () => { - const { output, effect } = run(["fixture", "--help"]); - return Effect.gen(function* () { - yield* effect; - const help = output(); - expect(help).toContain("Hand-written fixture group"); - expect(help).toContain("ping"); - expect(help).toContain("list"); - expect(help).toContain("fresh"); - expect(help).toContain("Nested"); - expect(help).toContain("inner"); - }); - }); - - it.effect("lists generated and hand-written commands together in the nested group help", () => { - const { output, effect } = run(["fixture", "inner", "--help"]); - return Effect.gen(function* () { - yield* effect; - const help = output(); - expect(help).toContain("Hand-written inner group"); - expect(help).toContain("pong"); - expect(help).toContain("get"); - }); - }); - - it.effect("leaves the hand-written group alone while the feature is off", () => { - const { output, effect } = run(["fixture", "--help"], []); - return Effect.gen(function* () { - yield* effect; - const help = output(); - expect(help).toContain("ping"); - expect(help).not.toContain("list"); - expect(help).not.toContain("fresh"); - }); - }); -}); diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index b1a7925060..0aacd72cb0 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -2,14 +2,11 @@ import type { OpenApiOperationId } from "@supabase/api/effect"; import type { ExperimentalFeature } from "../../shared/config/experimental-feature.ts"; export interface ApiNoun { - /** Help text of the noun's group; set only when no hand-written group of that name exists. */ - readonly description?: string; + /** Help text of the noun's group. */ + readonly description: string; /** Feature that gates every command under the noun. */ readonly feature: ExperimentalFeature; - /** - * Help text of each sub-group the generator creates, keyed by its dotted path below the noun, - * e.g. `"tables.layout"`; a sub-group that exists in a hand-written group has no entry. - */ + /** Help text of each sub-group, keyed by its dotted path below the noun, e.g. `"tables.layout"`. */ readonly groups?: Readonly>; } diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts index 0d17ad9e3e..8724c20ad4 100644 --- a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts @@ -75,7 +75,7 @@ const derived = deriveApiCommands({ generated: Object.keys(FIXTURE_OPERATIONS), nouns: { fixture: fixtureNoun }, operationIdMap: openApiOperationIdMap, - handWritten: { groups: new Set(), leaves: new Set() }, + handWrittenRoots: new Set(), }); const fixtureRoot = Command.make("supabase").pipe( diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 6e5f0151d9..82ee1b4c72 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -1,4 +1,4 @@ -import { Array as Arr, Cause, Effect, Exit, Layer, Option } from "effect"; +import { Cause, Effect, Exit, Layer, Option } from "effect"; import { Argument, Command, Flag } from "effect/cli"; import { CommandPlatformApiFactory } from "../../auth/command-platform-api-factory.service.ts"; @@ -364,16 +364,8 @@ const leafOf = (entry: ApiCommandEntry, entries: ReadonlyArray) type ApiLeaf = ReturnType; -/** A command with generated commands merged in: it fails and requires what `C` and the generated leaves do. */ -type WithApi = Command.Command< - string, - {}, - {}, - Command.Error | Command.Error, - Command.Services | Command.Services ->; - -type Subcommands = ReadonlyArray; +/** A generated group: it fails and requires what its generated leaves do. */ +type ApiGroup = Command.Command, Command.Services>; /** The noun definitions and entries the generated commands are built from. */ interface ApiCommandSource { @@ -397,13 +389,12 @@ const cachedLeaf = (entry: ApiCommandEntry, entries: ReadonlyArray, noun: ApiNoun): string | undefined => path.length === 1 ? noun.description : noun.groups?.[path.slice(1).join(".")]; -/** The group at `path`, taking the generated commands below it; `existing` is the hand-written group it joins. */ +/** The group at `path`, holding the generated commands below it. */ const groupAt = ( - existing: Command.Command.Any | undefined, path: ReadonlyArray, noun: ApiNoun, entries: ReadonlyArray, -): Command.Command.Any => { +): ApiGroup => { const name = path[path.length - 1] ?? ""; const under = entries.filter((entry) => startsWith(entry.command, path)); const childNames = new Set( @@ -413,56 +404,36 @@ const groupAt = ( : [], ), ); - const existingChildren = existing?.subcommands ?? []; - const existingNames = new Set( - existingChildren.flatMap(({ commands }) => commands.map((child) => child.name)), - ); - const joined = existingChildren.flatMap(({ group, commands }): Subcommands => { - const children = Arr.map(commands, (child) => - childNames.has(child.name) ? groupAt(child, [...path, child.name], noun, entries) : child, - ); - return group === undefined ? children : [{ group, commands: children }]; - }); const leaves = under .filter((entry) => entry.command.length === path.length + 1) .map((entry) => cachedLeaf(entry, entries)); - const created = [...childNames] - .filter((child) => !existingNames.has(child)) - .map((child) => groupAt(undefined, [...path, child], noun, entries)); + const groups = [...childNames].map((child) => groupAt([...path, child], noun, entries)); const description = `${groupDescription(path, noun) ?? name} (experimental)`; - const base = - existing ?? - Command.make(name).pipe( - Command.withDescription(description), - Command.withShortDescription(description), - ); - return Command.withSubcommands(base, [...joined, ...leaves, ...created]); + return Command.make(name).pipe( + Command.withDescription(description), + Command.withShortDescription(description), + Command.withSubcommands([...leaves, ...groups]), + ); }; /** - * `handWritten` with the generated Management API commands of every enabled noun merged in: a - * noun named like a hand-written command adds its commands and sub-groups to that command at any - * depth, and any other noun becomes a new group in alphabetical position. + * `handWritten` with the generated Management API commands of every enabled noun added as a new + * group, in alphabetical position. */ export const withApiCommands = >( handWritten: C, enabledFeatures: ReadonlyArray, source: ApiCommandSource = { nouns, entries: apiCommands }, -): ReadonlyArray> => { - const merged: Array = [...handWritten]; +): ReadonlyArray => { + const merged: Array = [...handWritten]; for (const [name, noun] of Object.entries(source.nouns)) { if (!enabledFeatures.includes(noun.feature)) continue; - const index = merged.findIndex((command) => command.name === name); - if (index >= 0) { - merged[index] = groupAt(merged[index], [name], noun, source.entries); - } else { - const position = merged.findIndex((command) => command.name > name); - merged.splice( - position < 0 ? merged.length : position, - 0, - groupAt(undefined, [name], noun, source.entries), - ); - } + const position = merged.findIndex((command) => command.name > name); + merged.splice( + position < 0 ? merged.length : position, + 0, + groupAt([name], noun, source.entries), + ); } return merged; }; diff --git a/apps/cli/src/commands/experimental/stack/stack.command.ts b/apps/cli/src/commands/experimental/stack/stack.command.ts index 0f8aa7ddc2..ea8a90dc79 100644 --- a/apps/cli/src/commands/experimental/stack/stack.command.ts +++ b/apps/cli/src/commands/experimental/stack/stack.command.ts @@ -59,53 +59,40 @@ export const stackStartRuntimeLayer = Layer.mergeAll( identityStitchLayer, ); -// Layers sit on each subcommand: a generated command joining this group would bypass a group-level -// `Command.provide` (see src/commands/api/SIDE_EFFECTS.md). const stackStartCommand = stackStartCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "start"])), Command.provide(stackStartRuntimeLayer), - Command.provide(stackRuntimeLayer), ); const stackStopCommand = stackStopCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "stop"])), - Command.provide(stackRuntimeLayer), ); const stackStatusCommand = stackStatusCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "status"])), - Command.provide(stackRuntimeLayer), ); const stackDestroyCommand = stackDestroyCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "destroy"])), - Command.provide(stackRuntimeLayer), ); const stackLogsCommand = stackLogsCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "logs"])), - Command.provide(stackRuntimeLayer), ); const stackListCommand = stackListCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "list"])), - Command.provide(stackRuntimeLayer), ); const stackPruneCommand = stackPruneCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "prune"])), - Command.provide(stackRuntimeLayer), ); const stackRestartCommand = stackRestartCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "restart"])), - Command.provide(stackRuntimeLayer), ); const stackInstallCommand = stackInstallCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "install"])), - Command.provide(stackRuntimeLayer), ); const stackOutdatedCommand = stackOutdatedCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "outdated"])), - Command.provide(stackRuntimeLayer), ); const stackUpdateCommand = stackUpdateCommandBase.pipe( Command.provide(commandRuntimeLayer(["stack", "update"])), Command.provide(stackStartRuntimeLayer), - Command.provide(stackRuntimeLayer), ); export const stackCommand = Command.make("stack").pipe( @@ -126,4 +113,5 @@ export const stackCommand = Command.make("stack").pipe( stackStopCommand, stackUpdateCommand, ]), + Command.provide(stackRuntimeLayer), ); diff --git a/knip.jsonc b/knip.jsonc index 08f8c2e873..4e26102ccd 100644 --- a/knip.jsonc +++ b/knip.jsonc @@ -25,9 +25,6 @@ // Referenced from package.json#release.plugins; knip's Semantic Release plugin only // reads the root manifest. "scripts/analyze-commits-title.js", - // Data modules the generated command runtime and the contract extraction will consume. - "src/commands/api/generated.ts", - "src/commands/api/generated.schemas.ts", // tests/smoke-test.ts picks the platform file from a string map and spawns it. "tests/smoke-test-*.ts", ], From 2ab276a8189c80e968552cdc5816a7b97133158c Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 15:18:10 +0100 Subject: [PATCH 35/45] fix(cli): derive generated command facts from the generated table The command surface reads bindings and stage from the generated entry, so the mounted annotation carries only the operation id and the stage annotation is gone. Body-bound flags are no longer reported as required on the command line, and the side-effects doc covers stack-mode project state and the workdir order. --- apps/cli/scripts/api-command-reference.ts | 10 +++- .../command-surface.integration.test.ts | 51 +++++++++++------- .../cli/command-surface/command-surface.ts | 52 +++++++++++++++---- .../command-stage/command-stage.annotation.ts | 28 ---------- apps/cli/src/commands/api/SIDE_EFFECTS.md | 35 ++++++++----- .../commands/api/api-command.annotation.ts | 4 -- .../api/api-commands.integration.test.ts | 16 ------ apps/cli/src/commands/api/generated.md | 14 ++--- apps/cli/src/commands/api/runtime.ts | 16 +----- 9 files changed, 113 insertions(+), 113 deletions(-) delete mode 100644 apps/cli/src/command-internal/command-stage/command-stage.annotation.ts diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts index d85a6d04fd..18890446a2 100644 --- a/apps/cli/scripts/api-command-reference.ts +++ b/apps/cli/scripts/api-command-reference.ts @@ -44,6 +44,14 @@ const bindsTo = (entry: ApiCommandEntry, flag: ApiCommandFlag): string => { : `${binding.location} ${code(binding.name)}`; }; +const requiredCell = (entry: ApiCommandEntry, flag: ApiCommandFlag): string => { + if (!flag.required) return "no"; + const bodyBound = entry.bindings.some( + (binding) => binding.location === "body" && binding.flag === flag.name, + ); + return bodyBound ? `yes, unless ${code("--body")} or ${code("--file")} has the field` : "yes"; +}; + const flagRows = (entry: ApiCommandEntry): ReadonlyArray => entry.flags.map((flag) => { const label = @@ -51,7 +59,7 @@ const flagRows = (entry: ApiCommandEntry): ReadonlyArray => ? `--${flag.name}` : `--${flag.name} <${flag.type === "json" ? "json" : flag.name}>`; const notes = flag.sensitive === true ? " Sensitive: never echoed or recorded." : ""; - return `| ${code(label)} | ${cell(flagType(flag))} | ${flag.required ? "yes" : "no"} | ${flag.repeatable ? "yes" : "no"} | ${bindsTo(entry, flag)}${notes} |`; + return `| ${code(label)} | ${cell(flagType(flag))} | ${requiredCell(entry, flag)} | ${flag.repeatable ? "yes" : "no"} | ${bindsTo(entry, flag)}${notes} |`; }); const argumentLine = (entry: ApiCommandEntry): string | undefined => { diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index 0fa0dfb89c..e5bf4f0668 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -2,6 +2,7 @@ import { describe, expect, it } from "@effect/vitest"; import { Effect, Schema } from "effect"; import { commandSurface, commandSurfaceEntry, walkCommandSurface } from "./command-surface.ts"; +import { apiCommands } from "../../commands/api/generated.ts"; import { rootCommandForFeatures } from "../root.ts"; const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); @@ -134,26 +135,40 @@ describe("command surface", () => { }), ); - it.effect("describes a generated command from its annotations and operation schemas", () => + it.effect( + "describes a generated command from its operation and schemas; a body flag is not required on the command line", + () => + Effect.gen(function* () { + const warehouse = yield* warehouseVariant; + const enable = warehouse["warehouse enable"]; + expect(enable).toMatchObject({ + path: ["warehouse", "enable"], + target: { group: "hosted", consent: "no" }, + errors: "standard", + stage: { status: "experimental", feature: "warehouse" }, + api: { operationId: "v2-enable-warehouse", request: { contentType: "application/json" } }, + }); + expect(titlesOf(enable?.result)).toEqual(["response", "waited", "dryRun"]); + expect(enable?.flags["schema"]).toMatchObject({ required: false }); + expect(enable?.flags["table"]).toMatchObject({ + type: "string", + variadic: true, + required: false, + }); + expect(enable?.flags["dry-run"]).toMatchObject({ type: "boolean", default: false }); + expect(Object.keys(enable?.flags ?? {})).not.toContain("output"); + }), + ); + + it.effect("reports every generated command with its operation and experimental stage", () => Effect.gen(function* () { const warehouse = yield* warehouseVariant; - const enable = warehouse["warehouse enable"]; - expect(enable).toMatchObject({ - path: ["warehouse", "enable"], - target: { group: "hosted", consent: "no" }, - errors: "standard", - stage: { status: "experimental", feature: "warehouse" }, - api: { operationId: "v2-enable-warehouse", request: { contentType: "application/json" } }, - }); - expect(titlesOf(enable?.result)).toEqual(["response", "waited", "dryRun"]); - expect(enable?.flags["schema"]).toMatchObject({ required: true }); - expect(enable?.flags["table"]).toMatchObject({ - type: "string", - variadic: true, - required: false, - }); - expect(enable?.flags["dry-run"]).toMatchObject({ type: "boolean", default: false }); - expect(Object.keys(enable?.flags ?? {})).not.toContain("output"); + for (const entry of apiCommands) { + expect(warehouse[entry.command.join(" ")]).toMatchObject({ + stage: { status: "experimental", feature: entry.feature }, + api: { operationId: entry.operationId }, + }); + } }), ); diff --git a/apps/cli/src/cli/command-surface/command-surface.ts b/apps/cli/src/cli/command-surface/command-surface.ts index ac0ea556a6..0842d323f5 100644 --- a/apps/cli/src/cli/command-surface/command-surface.ts +++ b/apps/cli/src/cli/command-surface/command-surface.ts @@ -5,11 +5,8 @@ import { readApiCommand } from "../../commands/api/api-command.annotation.ts"; import type { ApiCommandBinding, ApiCommandEntry, - ApiCommandFlag, ApiCommandSchemas, } from "../../commands/api/api-command.model.ts"; -import { readCommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; -import type { CommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; import { nouns } from "../../commands/api/api-command-policy.ts"; import { apiCommands } from "../../commands/api/generated.ts"; import { rootCommandForFeatures } from "../root.ts"; @@ -57,6 +54,15 @@ interface SurfaceApi { readonly bindings: readonly ApiCommandBinding[]; } +/** + * How far a command's contract has settled. An experimental command is reachable only while its + * `feature` is enabled: the root mounts the command's family only then. + */ +interface CommandStage { + readonly status: "experimental"; + readonly feature: string; +} + /** One command or group of the mounted tree. Optional fields are omitted when the command declares nothing. */ interface CommandSurfaceEntry { readonly path: readonly string[]; @@ -150,11 +156,37 @@ const sortedRecord = ( ): Readonly> => Object.fromEntries([...entries].toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))); -const noApiFlags: ReadonlyMap = new Map(); +/** What a generated flag adds to its parsed definition. */ +interface ApiFlagFacts { + readonly required: boolean; + readonly sensitive: boolean; +} + +const noApiFlags: ReadonlyMap = new Map(); + +/** + * A body flag's requirement sits on the request body, which `--body` or `--file` can supply + * instead; a query or header flag has no other source, so it is required on the command line. + */ +const apiFlagFacts = (entry: ApiCommandEntry): ReadonlyMap => + new Map( + entry.flags.map((flag) => { + const bodyBound = entry.bindings.some( + (binding) => binding.location === "body" && binding.flag === flag.name, + ); + return [ + flag.name, + { + required: flag.required && !bodyBound, + sensitive: flag.sensitive === true, + }, + ]; + }), + ); const surfaceFlag = ( flag: CommandSpec.Flag, - apiFlags: ReadonlyMap, + apiFlags: ReadonlyMap, ): readonly [string, SurfaceFlag] => [ flag.name, { @@ -187,7 +219,7 @@ const walkGlobalFlags = (root: CommandRoot) => { const apiSurface = Effect.fn("CommandSurface.api")(function* (command: CommandRoot) { const descriptor = readApiCommand(command); if (Option.isNone(descriptor)) return Option.none(); - const { operationId, bindings } = descriptor.value; + const { operationId } = descriptor.value; const generated = generatedEntries.find((entry) => entry.operationId === operationId); if (generated === undefined) { return yield* Effect.die(`no generated command declares operation "${operationId}"`); @@ -214,10 +246,11 @@ const apiSurface = Effect.fn("CommandSurface.api")(function* (command: CommandRo schemas.request === undefined ? null : { contentType: schemas.request.contentType, schema: schemas.request.schema }, - bindings, + bindings: generated.bindings, } satisfies SurfaceApi, result: { anyOf: branches } satisfies JsonSchema, - apiFlags: new Map(generated.flags.map((flag) => [flag.name, flag])), + stage: { status: "experimental", feature: generated.feature } satisfies CommandStage, + apiFlags: apiFlagFacts(generated), }); }); @@ -236,7 +269,6 @@ export const commandSurfaceEntry = Effect.fn("CommandSurface.entry")(function* ( onNone: () => noApiFlags, onSome: (found) => found.apiFlags, }); - const stage = readCommandStage(command.value); const target = readTargetPolicy(command.value); const permissions = readPermissions(command.value); const flags = spec.value.flags @@ -247,7 +279,7 @@ export const commandSurfaceEntry = Effect.fn("CommandSurface.entry")(function* ( aliases: spec.value.alias === undefined ? [] : [spec.value.alias], summary: spec.value.shortDescription ?? spec.value.description ?? "", unlisted: spec.value.unlisted, - ...(Option.isSome(stage) ? { stage: stage.value } : {}), + ...(Option.isSome(api) ? { stage: api.value.stage } : {}), ...(Option.isSome(target) ? { target: { group: target.value.group, consent: target.value.consent } } : {}), diff --git a/apps/cli/src/command-internal/command-stage/command-stage.annotation.ts b/apps/cli/src/command-internal/command-stage/command-stage.annotation.ts deleted file mode 100644 index aacc431bb8..0000000000 --- a/apps/cli/src/command-internal/command-stage/command-stage.annotation.ts +++ /dev/null @@ -1,28 +0,0 @@ -import { Context, Option } from "effect"; -import { Command } from "effect/cli"; - -/** - * How far a command's contract has settled. An experimental command is reachable only while its - * `feature` is enabled: the root mounts the command's family only then. - */ -export interface CommandStage { - readonly status: "experimental"; - readonly feature: string; -} - -/** Context key under which a command's stage is stored in `Command.annotations`. */ -export class CommandStageAnnotation extends Context.Service()( - "supabase/CommandStageAnnotation", -) {} - -/** Declares the command's stage. */ -export const withCommandStage = - (stage: CommandStage) => - ( - self: Command.Command, - ) => - self.pipe(Command.annotate(CommandStageAnnotation, stage)); - -/** The stage a command declares, or `None` for a stable command. */ -export const readCommandStage = (command: Command.Command.Any): Option.Option => - Context.getOption(command.annotations, CommandStageAnnotation); diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index f6f619311a..fe8f3d42cc 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -27,17 +27,23 @@ command documentation. | `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | | `` | JSON | only with `--file `: the whole request body (`--file -` reads stdin) | | `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential, unless `--dry-run` | -| `/supabase/.temp/project-ref` | plain text | when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | +| `/supabase/.temp/project-ref` | plain text | legacy mode, when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | +| `/supabase/.link.json` | JSON | stack mode, when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | | `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | +Stack mode is on with `[experimental] stack = true` or `SUPABASE_EXPERIMENTAL_STACK=1`; otherwise the +project state is legacy. `` is the `--workdir` flag, else `SUPABASE_WORKDIR`, else the +nearest ancestor of the cwd holding `supabase/config.json` or `supabase/config.toml`, else the cwd. + Commands never write project configuration, execute SQL locally or read stdin, except `--file -`. ## Files Written -| Path | Format | When | -| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- | -| `/telemetry.json` | JSON | always, flushed on success and on failure | -| `/supabase/.temp/linked-project.json` | JSON | post-run, once the project ref resolved, only when no such file exists for that ref; never with `--dry-run` | +| Path | Format | When | +| --------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/telemetry.json` | JSON | always, flushed on success and on failure | +| `/supabase/.temp/linked-project.json` | JSON | legacy mode, post-run, once the project ref resolved, only when no such file exists for that ref; never with `--dry-run` | +| `/project-cache/.json` | JSON | stack mode, post-run, once the project ref resolved, only when that file does not exist and `` is a well-formed project ref; never with `--dry-run` | ## API Routes @@ -123,15 +129,16 @@ includes the failed status and the reported failure message. ## Environment Variables -| Variable | Purpose | Required? | -| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | -| `SUPABASE_EXPERIMENTAL_` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.`) | no | -| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | -| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | -| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to `supabase/.temp/project-ref`) | -| `SUPABASE_WORKDIR` | project directory the command acts on | no (falls back to `--workdir`, then the cwd) | -| `SUPABASE_HOME` | directory holding `telemetry.json` | no (falls back to `~/.supabase`) | -| `SUPABASE_YES` | consent for mutations in a shell; `supabase/.env` and a cwd `.env*` file do not count | no (falls back to `--yes`) | +| Variable | Purpose | Required? | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | +| `SUPABASE_EXPERIMENTAL_` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.`) | no | +| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | +| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | +| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to the linked project ref) | +| `SUPABASE_WORKDIR` | project directory the command acts on, consulted after `--workdir` | no (falls back to the discovered project root, then the cwd) | +| `SUPABASE_EXPERIMENTAL_STACK` | selects stack mode (`1`/`true`) or legacy mode (`0`/`false`) | no (falls back to `experimental.stack`) | +| `SUPABASE_HOME` | directory holding `telemetry.json`, and `project-cache/` in stack mode | no (falls back to `~/.supabase`) | +| `SUPABASE_YES` | consent for mutations in a shell; `supabase/.env` and a cwd `.env*` file do not count | no (falls back to `--yes`) | ## Telemetry Events Fired diff --git a/apps/cli/src/commands/api/api-command.annotation.ts b/apps/cli/src/commands/api/api-command.annotation.ts index e3c05da9ce..10e4b06e2c 100644 --- a/apps/cli/src/commands/api/api-command.annotation.ts +++ b/apps/cli/src/commands/api/api-command.annotation.ts @@ -1,13 +1,9 @@ import { Context, Option } from "effect"; import { Command } from "effect/cli"; -import type { ApiCommandBinding, ApiCommandEntry } from "./api-command.model.ts"; - /** What a generated command declares about its API operation; tooling reads it from `Command.annotations`. */ export interface ApiCommandDescriptor { readonly operationId: string; - readonly bindings: readonly ApiCommandBinding[]; - readonly response: ApiCommandEntry["response"]; } /** Context key under which a generated command's descriptor is stored in `Command.annotations`. */ diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 3c95de3ae9..3cd21eb0b9 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -55,8 +55,6 @@ import { import type { ApiCommandEntry } from "./api-command.model.ts"; import { assembleInput, decodeInput, previewRequest } from "./api-command-request.ts"; import { apiCommands } from "./generated.ts"; -import { readApiCommand } from "./api-command.annotation.ts"; -import { readCommandStage } from "../../command-internal/command-stage/command-stage.annotation.ts"; import { withApiCommands } from "./runtime.ts"; import { isMachineFailureMode, standardFailureFor } from "../../shared/cli/standard-errors.ts"; import { EventUpgradeSuggested } from "../../shared/telemetry/event-catalog.ts"; @@ -2218,20 +2216,6 @@ describe("generated warehouse commands", () => { }), ); - it("marks each mounted leaf with its operation and experimental feature stage", () => { - const tree = commandTreeFor({ apiFeatures: ["warehouse"] }); - for (const entry of apiCommands) { - const command = tree.get(entry.command.join(" "))?.command; - if (command === undefined) throw new Error(`${entry.command.join(" ")} is not mounted`); - expect(Option.map(readApiCommand(command), (api) => api.operationId)).toEqual( - Option.some(entry.operationId), - ); - expect(readCommandStage(command)).toEqual( - Option.some({ status: "experimental", feature: "warehouse" }), - ); - } - }); - it.effect("is on with experimental.warehouse in the project config", () => Effect.gen(function* () { yield* withConfig("[experimental]\nwarehouse = true\n"); diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index f0870e5eef..43cbbf0297 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -51,13 +51,13 @@ Enables replication for the currently eligible tables in a schema, or the named ### Flags -| Flag | Type | Required | Repeatable | Binds to | -| ----------------------------------------------------- | ------- | -------- | ---------- | ----------------------------------------------- | -| `--warehouse-region ` | string | no | no | body `/data/attributes/warehouse_region` | -| `--destination-project-ref ` | string | no | no | body `/data/attributes/destination_project_ref` | -| `--install-fdw` | boolean | no | no | body `/data/attributes/install_fdw` | -| `--schema ` | string | yes | no | body `/data/attributes/schema` | -| `--table
` | string | no | yes | body `/data/attributes/tables` | +| Flag | Type | Required | Repeatable | Binds to | +| ----------------------------------------------------- | ------- | ---------------------------------------------- | ---------- | ----------------------------------------------- | +| `--warehouse-region ` | string | no | no | body `/data/attributes/warehouse_region` | +| `--destination-project-ref ` | string | no | no | body `/data/attributes/destination_project_ref` | +| `--install-fdw` | boolean | no | no | body `/data/attributes/install_fdw` | +| `--schema ` | string | yes, unless `--body` or `--file` has the field | no | body `/data/attributes/schema` | +| `--table
` | string | no | yes | body `/data/attributes/tables` | ### Wait diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 82ee1b4c72..4837a9dfd5 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -6,10 +6,6 @@ import { ApiCommandUsageError } from "../../command-internal/command-errors/api- import { withStandardErrors } from "../../command-internal/command-errors/command-errors.annotation.ts"; import { withPermissions } from "../../command-internal/command-permissions/command-permissions.annotation.ts"; import { compose, type OperationEntry } from "../../command-internal/command-permissions/model.ts"; -import { - type CommandStage, - withCommandStage, -} from "../../command-internal/command-stage/command-stage.annotation.ts"; import { parseDuration } from "../../command-internal/duration.ts"; import { GLOBAL_OUTPUT_FORMATS, OutputFlag } from "../../command-internal/global-flags.ts"; import { requireHostedMutationConsent } from "../../command-internal/hosted-consent/hosted-consent.ts"; @@ -58,11 +54,6 @@ import { apiCommands, apiPollTargets } from "./generated.ts"; const DEFAULT_WAIT_TIMEOUT = "10m"; const NANOSECONDS_PER_MILLISECOND = 1_000_000; -const stageOf = (entry: ApiCommandEntry): CommandStage => ({ - status: "experimental", - feature: entry.feature, -}); - /** A command's `--wait`: the wait declared on its entry and the entry of the operation it polls. */ interface ResolvedWait { readonly wait: ApiCommandWait; @@ -335,13 +326,8 @@ const leafOf = (entry: ApiCommandEntry, entries: ReadonlyArray) Command.withDescription(entry.description ?? entry.summary), Command.withShortDescription(`${entry.summary} (experimental)`), Command.withExamples([{ command: exampleFor(entry), description: entry.summary }]), - withApiCommand({ - operationId: entry.operationId, - bindings: entry.bindings, - response: entry.response, - }), + withApiCommand({ operationId: entry.operationId }), withPermissions(permissionsOf(entry, resolved)), - withCommandStage(stageOf(entry)), withStandardErrors, Command.withHandler((flags) => { const { api: _generated, argument: _argument, ...recorded } = flags; From 4e0635a745c7caa0a1e05587988573c2c53c4836 Mon Sep 17 00:00:00 2001 From: Coenen Benjamin Date: Thu, 19 Nov 2026 20:26:21 +0100 Subject: [PATCH 36/45] feat(cli): add warehouse replication commands (#7718) Adds experimental `warehouse replication add`, `remove` and `resync` commands on top of #7640. All three use the generated request/runtime path and preserve the immediate API response. All support `--dry-run` as a local request preview, with no server-side dry-run contract. Resync has no idempotency, revision or wait flags. The shared generator/runtime gains CLI policy for API impact descriptions in consent. Local previews use the existing shared behavior. No hand-written command handlers are added. Depends on #7640 and the companion Management API endpoints. --------- Co-authored-by: Julien Goux --- apps/cli/scripts/api-command-derive.ts | 13 +- .../scripts/api-command-derive.unit.test.ts | 26 + apps/cli/scripts/api-command-reference.ts | 3 + apps/cli/scripts/generate-api-commands.ts | 7 +- .../command-surface.integration.test.ts | 15 + .../hosted-consent-coverage.unit.test.ts | 3 + apps/cli/src/commands/api/SIDE_EFFECTS.md | 7 +- .../src/commands/api/api-command-policy.ts | 15 + .../cli/src/commands/api/api-command.model.ts | 2 + .../api/api-commands.integration.test.ts | 255 +++- apps/cli/src/commands/api/generated.md | 57 + .../cli/src/commands/api/generated.schemas.ts | 653 ++++++++++ apps/cli/src/commands/api/generated.ts | 177 +++ apps/cli/src/commands/api/runtime.ts | 5 +- packages/api/scripts/openapi-overrides.json | 926 ++++++++++++++- packages/api/src/generated/contracts.ts | 419 +++++++ packages/api/src/generated/effect-client.ts | 48 + packages/api/src/generated/openapi.json | 1047 +++++++++++++++-- packages/api/src/generated/permissions.ts | 12 + 19 files changed, 3585 insertions(+), 105 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 6517f20170..d03221bdf7 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -1,7 +1,7 @@ import type { OperationId } from "@supabase/api/effect"; import { isDeepStrictEqual } from "node:util"; import { Cause, Exit, Predicate, Schema } from "effect"; -import type { ApiNoun } from "../src/commands/api/api-command-policy.ts"; +import type { ApiNoun, ApiCommandPolicy } from "../src/commands/api/api-command-policy.ts"; import type { ApiCommandBinding, ApiCommandEntry, @@ -116,6 +116,7 @@ const parseXOperation = (block: unknown): ParsedXOperation => { }; interface DeriveInput { + readonly policies?: Readonly>; /** The parsed OpenAPI document. */ readonly spec: JsonObject; /** Operation ids that generate commands; the roots whose response `links` are followed. */ @@ -775,6 +776,10 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const { spec, generated, nouns, operationIdMap, handWrittenRoots } = input; const operations = collectOperations(spec); const problems: Array = []; + for (const id of Object.keys(input.policies ?? {})) { + if (!input.generated.includes(id)) + problems.push(`${id}: CLI policy requires an allowlisted command`); + } const metadata = readMetadata(operations, generated, problems); const hidden = new Map(); const entries: Array = []; @@ -1105,6 +1110,11 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { if (response === undefined || schemaSet === undefined) continue; schemas[operationId] = schemaSet; const description = stripStabilityNotice(asString(operation.node.description)); + const policy = input.policies?.[operationId]; + if (policy?.confirmDescription && (operation.method === "GET" || !description)) { + fail("confirmation details require a mutation with an API description"); + continue; + } entries.push({ command, operationId, @@ -1114,6 +1124,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { summary, ...(description === undefined ? {} : { description }), readOnly: operation.method === "GET", + ...policy, feature: noun.feature, ...(body === undefined ? {} : { body }), response: { status: response.status, kind: response.kind }, diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index b8e4c78946..8295253432 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -115,6 +115,32 @@ const named = (method: string) => ({ "x-operation": { group: "thing", method } } const create = named("create"); describe("deriveApiCommands", () => { + it("applies CLI-only mutation policies and rejects an unused policy", () => { + const operations = { + "create-thing": operation({ ...create, description: "Rebuilds the thing." }), + }; + const result = derive(operations, undefined, { + overrides: { policies: { "create-thing": { confirmDescription: true } } }, + }); + expect(result.problems).toEqual([]); + expect(result.entries[0]).toMatchObject({ confirmDescription: true }); + expect( + derive(operations, undefined, { + overrides: { policies: { "missing-thing": { confirmDescription: true } } }, + }).problems, + ).toEqual([expect.stringContaining("missing-thing")]); + }); + + it.each([ + { id: "get-thing", node: operation({ ...named("get"), description: "Reads the thing." }) }, + { id: "create-thing", node: operation({ ...create }) }, + ])("rejects confirmation descriptions on $id without a described mutation", ({ id, node }) => { + const result = derive({ [id]: node }, undefined, { + overrides: { policies: { [id]: { confirmDescription: true } } }, + }); + expect(result.problems).toEqual([expect.stringContaining("confirmation")]); + }); + it("binds envelope body fields by JSON pointer and the project ref to the target", () => { const result = derive({ "create-thing": operation({ diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts index 18890446a2..4f4e0f5680 100644 --- a/apps/cli/scripts/api-command-reference.ts +++ b/apps/cli/scripts/api-command-reference.ts @@ -150,6 +150,9 @@ const commandSection = ( ...(entry.description === undefined ? [] : [prose(entry.description), ""]), `- Access: ${entry.readOnly ? "read-only, no consent" : "mutation, consent defaults to No (`--yes` when it cannot prompt)"}.`, `- Feature: ${code(entry.feature)}.`, + ...(entry.confirmDescription + ? ["- Consent: prints the API description before the interactive confirmation."] + : []), `- Request: ${route({ method: entry.method, path: entry.apiPath })} (${code(entry.operationId)}), success ${entry.response.status} ${entry.response.kind}.`, ...(body === undefined ? [] : [`- Body: ${body}.`]), ...(argument === undefined ? [] : [`- ${argument}`]), diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index a27780b8f3..9a76b80593 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -2,7 +2,11 @@ import { BunRuntime, BunServices } from "@effect/platform-bun"; import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect"; import { ChildProcess, ChildProcessSpawner } from "effect/process"; import { rootCommandForFeatures } from "../src/cli/root.ts"; -import { generatedOperations, nouns } from "../src/commands/api/api-command-policy.ts"; +import { + generatedOperations, + nouns, + commandPolicies, +} from "../src/commands/api/api-command-policy.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { renderApiCommandReference } from "./api-command-reference.ts"; import { @@ -92,6 +96,7 @@ const main = Effect.gen(function* () { const { entries, pollTargets, schemas, problems } = deriveApiCommands({ spec, generated: generatedOperations, + policies: commandPolicies, nouns, operationIdMap: openApiOperationIdMap, handWrittenRoots: yield* handWrittenRoots(), diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts index e5bf4f0668..894d49f931 100644 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts @@ -61,6 +61,10 @@ describe("command surface", () => { "warehouse inspect", "warehouse inspect capacity", "warehouse inspect query-stats", + "warehouse replication", + "warehouse replication add", + "warehouse replication remove", + "warehouse replication resync", "warehouse status", "warehouse tables", "warehouse tables get", @@ -112,6 +116,17 @@ describe("command surface", () => { }), ); + it.effect("describes local request preview results for every replication command", () => + Effect.gen(function* () { + const warehouse = yield* warehouseVariant; + for (const action of ["add", "remove", "resync"]) { + const command = warehouse[`warehouse replication ${action}`]; + expect(command?.flags).toHaveProperty("dry-run"); + expect(titlesOf(command?.result)).toEqual(["response", "dryRun"]); + } + }), + ); + it.effect("describes layout updates without unsupported backend workflow flags", () => Effect.gen(function* () { const warehouse = yield* warehouseVariant; diff --git a/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts b/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts index 8255dc584e..f0fedb7837 100644 --- a/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts +++ b/apps/cli/src/command-internal/hosted-consent/hosted-consent-coverage.unit.test.ts @@ -137,6 +137,9 @@ describe("hosted consent coverage", () => { "vanity-subdomains delete": "no", "warehouse disable": "no", "warehouse enable": "no", + "warehouse replication add": "no", + "warehouse replication remove": "no", + "warehouse replication resync": "no", "warehouse tables layout update": "no", } `); diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index fe8f3d42cc..a7b07b1d70 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -80,7 +80,12 @@ With `--wait`, the command also polls the read operation named in its reference - Consent uses the command's summary as the action and lists what the validated request does: one `name: value` line per non-ref path parameter, query parameter and body field (for an envelope body, the fields under `data.attributes`). Scalars print as is; objects and arrays print as - compact JSON. + compact JSON. Commands with `confirmDescription` also show their API description before an + interactive prompt. These describe effects without a resolved plan. +- Resync supports the same local request preview as add/remove, without a server-side dry-run + contract. Executing it resets one selected table through ETL and returns the immediate result; + it has no wait, idempotency or revision flags. Pipeline restarts can restart unfinished copies + of unrelated tables. ## `--wait` diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index 0aacd72cb0..a0169c40f2 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -23,13 +23,28 @@ export const generatedOperations: ReadonlyArray = [ "v2-update-warehouse-table-layout", "v2-get-warehouse-query-stats", "v2-get-warehouse-capacity", + "v2-add-warehouse-replication", + "v2-remove-warehouse-replication", + "v2-resync-warehouse-replication", ]; +export interface ApiCommandPolicy { + readonly confirmDescription?: true; +} + +/** CLI presentation choices, independent of the API's operation metadata. */ +export const commandPolicies = { + "v2-add-warehouse-replication": { confirmDescription: true }, + "v2-remove-warehouse-replication": { confirmDescription: true }, + "v2-resync-warehouse-replication": { confirmDescription: true }, +} satisfies Partial>; + export const nouns = { warehouse: { description: "Manage the data warehouse for a project", feature: "warehouse", groups: { + replication: "Manage Warehouse replication selections and rebuilds", inspect: "Inspect Warehouse workload metrics", tables: "Inspect tables replicated to Warehouse", "tables.layout": "Inspect and update the layout of tables replicated to Warehouse", diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index ce0b12547e..e8c5b32b78 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -83,6 +83,8 @@ export interface ApiCommandEntry { readonly summary: string; readonly description?: string; readonly readOnly: boolean; + /** Show the API description as impact details before hosted consent. */ + readonly confirmDescription?: true; /** Feature that gates the command's noun. */ readonly feature: string; /** Request body shape; `json-envelope` bodies wrap fields in `data.attributes`. */ diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 3cd21eb0b9..4bc27fbb06 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -317,6 +317,136 @@ const driveClock = (fiber: Fiber.Fiber) => Effect.raceFirst(Effect.forever(TestClock.adjust("2 seconds")), Fiber.await(fiber)); describe("generated warehouse commands", () => { + describe("incremental replication", () => { + it.effect.each(["add", "remove", "resync"])( + "%s sends one literal selector and preserves the immediate API result", + (action) => { + const type = + action === "resync" ? "warehouse_replication_resync" : "warehouse_replication_change"; + const attributes = + action === "resync" + ? { + pipeline_id: "101", + tables: [{ table_id: 42, new_state: { name: "queued" } }], + application_status: "reset", + } + : { + pipeline_id: "101", + application_status: "restart_requested", + tables: [], + changed: true, + }; + const body = { data: { type, id: "101", attributes } }; + const selector = { schema: "sales.*", table: 'Orders "2026"' }; + const { sent, out, run } = setup( + [ + "warehouse", + "replication", + action, + "--schema", + selector.schema, + "--table", + selector.table, + "--output-format", + "json", + ], + { yes: true, route: () => ({ status: 202, body }), outputFormat: "json" }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([ + { + method: "POST", + path: `/v2/projects/${VALID_REF}/warehouse/replication/${action}`, + search: "", + body: { data: { type, attributes: selector } }, + }, + ]); + expect(decodeJson(out.stdoutText)).toEqual(body); + }); + }, + ); + + it.effect.each(["add", "remove"])("%s leaves schema expansion to the server", (action) => { + const { sent, run } = setup(["warehouse", "replication", action, "--schema", "public"], { + yes: true, + route: accepted, + }); + return Effect.gen(function* () { + yield* run; + expect(bodiesOf(sent)).toEqual([ + { data: { type: "warehouse_replication_change", attributes: { schema: "public" } } }, + ]); + }); + }); + + it.effect.each(["--idempotency-key=key", "--expected-revision=1", "--wait", "--timeout=10s"])( + "rejects resync %s before a request", + (flag) => { + const { console, calls } = fakeConsole(); + const { sent, run } = setup( + ["warehouse", "replication", "resync", "--schema", "public", "--table", "orders", flag], + { yes: true, route: accepted }, + ); + return Effect.gen(function* () { + const exit = yield* run.pipe( + Effect.provideService(Console.Console, console), + Effect.exit, + ); + expect(Exit.isFailure(exit)).toBe(true); + expect(calls.join("\n")).toContain(flag.split("=")[0]); + expect(sent).toEqual([]); + }); + }, + ); + + it.effect( + "shows rebuild effects and local preview in resync help without server operation flags", + () => { + const { console, calls } = fakeConsole(); + const { sent, run } = setup(["warehouse", "replication", "resync", "--help"], { + route: accepted, + }); + return Effect.gen(function* () { + yield* run.pipe(Effect.provideService(Console.Console, console)); + const help = calls.join("\n"); + expect(help).toContain("deleted and rebuilt"); + expect(help).toContain("interrupts replication for other tables"); + expect(help).toContain("--schema"); + expect(help).toContain("--table"); + expect(help).toContain("--dry-run"); + for (const flag of ["--idempotency-key", "--expected-revision", "--wait", "--timeout"]) + expect(help).not.toContain(flag); + expect(sent).toEqual([]); + }); + }, + ); + + it.effect("does not replay a resync after an uncertain server failure", () => { + const { sent, run } = setup( + ["warehouse", "replication", "resync", "--schema", "public", "--table", "orders"], + { + yes: true, + route: () => ({ + status: 503, + body: { + error: { + code: "warehouse_setup_unavailable", + message: + "The table may have been reset. Inspect its state before repeating the request.", + }, + }, + }), + }, + ); + return Effect.gen(function* () { + const exit = yield* run.pipe(Effect.exit); + expect(Exit.isFailure(exit)).toBe(true); + expect(sent).toHaveLength(1); + }); + }); + }); + describe("consolidated warehouse status", () => { const attributes = { project_ref: VALID_REF, @@ -1402,26 +1532,40 @@ describe("generated warehouse commands", () => { }); describe("consent and dry run", () => { - it.effect("prints exactly the request preview and sends nothing under --dry-run", () => { - const { out, sent, seen, run } = setup( - ["warehouse", "enable", "--schema", "public", "--table", "a", "--dry-run"], - { route: accepted }, - ); - return Effect.gen(function* () { - yield* run; - expect(sent).toEqual([]); - expect(seen).toEqual([]); - expect(decodeJson(out.stdoutText)).toEqual({ - method: "POST", - path: ENABLE_PATH, - query: {}, - headers: {}, - body: { - data: { type: "warehouse_setup", attributes: { schema: "public", tables: ["a"] } }, - }, + it.effect.each([ + { + command: ["enable"], + path: ENABLE_PATH, + type: "warehouse_setup", + attributes: { schema: "public", tables: ["a"] }, + }, + { + command: ["replication", "resync"], + path: `/v2/projects/${VALID_REF}/warehouse/replication/resync`, + type: "warehouse_replication_resync", + attributes: { schema: "public", table: "a" }, + }, + ])( + "$command prints exactly the request preview and sends nothing under --dry-run", + ({ command, path, type, attributes }) => { + const { out, sent, seen, run } = setup( + ["warehouse", ...command, "--schema", "public", "--table", "a", "--dry-run"], + { token: false, route: accepted }, + ); + return Effect.gen(function* () { + yield* run; + expect(sent).toEqual([]); + expect(seen).toEqual([]); + expect(decodeJson(out.stdoutText)).toEqual({ + method: "POST", + path, + query: {}, + headers: {}, + body: { data: { type, attributes } }, + }); }); - }); - }); + }, + ); it.effect( "previews a mutation for a literal --remote ref with no access token, no request and no cache write", @@ -2363,9 +2507,82 @@ describeHostedConsent("warehouse tables layout update", { ["warehouse", "tables", "layout", "update", "16385", "--body", encodeJson(body)], { yes, route: accepted }, ); + return { run: run.pipe(Effect.provide(cliServices(workdir, args))), mutations: () => sent.filter((request) => request.method !== "GET").length, }; }, }); + +describeHostedConsent("warehouse replication add", { + command: commandTreeFor({ apiFeatures: ["warehouse"] }).get("warehouse replication add")!.command, + invoke: ({ workdir, yes, out }) => { + const { args, sent, run } = execute( + ["warehouse", "replication", "add", "--schema", "public", "--table", "orders"], + { yes, route: accepted }, + ); + return { + run: run.pipe( + Effect.onExit(() => + Effect.sync(() => { + if (out.promptConfirmCalls.length > 0) { + expect(out.stderrText).toContain("interrupting replication for other tables"); + } + }), + ), + Effect.provide(cliServices(workdir, args)), + ), + mutations: () => sent.filter((request) => request.method !== "GET").length, + }; + }, +}); + +describeHostedConsent("warehouse replication remove", { + command: commandTreeFor({ apiFeatures: ["warehouse"] }).get("warehouse replication remove")! + .command, + invoke: ({ workdir, yes, out }) => { + const { args, sent, run } = execute( + ["warehouse", "replication", "remove", "--schema", "public", "--table", "orders"], + { yes, route: accepted }, + ); + return { + run: run.pipe( + Effect.onExit(() => + Effect.sync(() => { + if (out.promptConfirmCalls.length > 0) { + expect(out.stderrText).toContain("retained copy stops receiving updates"); + } + }), + ), + Effect.provide(cliServices(workdir, args)), + ), + mutations: () => sent.filter((request) => request.method !== "GET").length, + }; + }, +}); + +describeHostedConsent("warehouse replication resync", { + command: commandTreeFor({ apiFeatures: ["warehouse"] }).get("warehouse replication resync")! + .command, + invoke: ({ workdir, yes, out }) => { + const { args, sent, run } = execute( + ["warehouse", "replication", "resync", "--schema", "public", "--table", "orders"], + { yes, route: accepted }, + ); + return { + run: run.pipe( + Effect.onExit(() => + Effect.sync(() => { + if (out.promptConfirmCalls.length > 0) { + expect(out.stderrText).toContain("deleted and rebuilt"); + expect(out.stderrText).toContain("interrupts replication for other tables"); + } + }), + ), + Effect.provide(cliServices(workdir, args)), + ), + mutations: () => sent.filter((request) => request.method !== "GET").length, + }; + }, +}); diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index 43cbbf0297..1266041431 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -115,6 +115,63 @@ Returns aggregate workload measurements over a bounded time range, using the pro | `--since ` | string | no | no | query `since` | | `--to ` | string | no | no | query `to` | +## `supabase warehouse replication add` + +Add source tables to Warehouse replication + +Adds one eligible source table or the currently eligible tables in a schema to an enabled Warehouse. Existing selections and layouts are preserved; already-selected tables are unchanged. Schema selection excludes future tables, except future partitions of selected partition roots. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline remains stopped and requires an explicit start before copying. Initial copy adds source reads; duration is unknown. Unsafe reattachment of retained data is rejected. The response describes configuration and restart acceptance, not completed copy or streaming. Failures may have partial effects; inspect table and pipeline state before retrying. + +- Access: mutation, consent defaults to No (`--yes` when it cannot prompt). +- Feature: `warehouse`. +- Consent: prints the API description before the interactive confirmation. +- Request: `POST /v2/projects/{ref}/warehouse/replication/add` (`v2-add-warehouse-replication`), success 202 json. +- Body: JSON envelope `data.type = warehouse_replication_change`, fields under `data.attributes`. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| ------------------- | ------ | ---------------------------------------------- | ---------- | ------------------------------ | +| `--schema ` | string | yes, unless `--body` or `--file` has the field | no | body `/data/attributes/schema` | +| `--table
` | string | no | no | body `/data/attributes/table` | + +## `supabase warehouse replication remove` + +Remove source tables from Warehouse replication + +Removes one selected source table or all selected tables in a schema as a batch. Source PostgreSQL rows and existing Warehouse data are retained. The retained copy stops receiving updates. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline stays stopped. Removing an unselected target is unchanged. Removing the last target leaves Warehouse enabled with an empty selection. Publication changes and restart acceptance do not establish observed exclusion by active replication. Failures may have partial effects; inspect the selection and pipeline before retrying. + +- Access: mutation, consent defaults to No (`--yes` when it cannot prompt). +- Feature: `warehouse`. +- Consent: prints the API description before the interactive confirmation. +- Request: `POST /v2/projects/{ref}/warehouse/replication/remove` (`v2-remove-warehouse-replication`), success 202 json. +- Body: JSON envelope `data.type = warehouse_replication_change`, fields under `data.attributes`. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| ------------------- | ------ | ---------------------------------------------- | ---------- | ------------------------------ | +| `--schema ` | string | yes, unless `--body` or `--file` has the field | no | body `/data/attributes/schema` | +| `--table
` | string | no | no | body `/data/attributes/table` | + +## `supabase warehouse replication resync` + +Reset and rebuild one Warehouse table + +Resets replication for one selected source table using its currently saved layout. Source rows, saved layouts and completed replication state for unrelated tables are preserved. In-progress initial copies of other tables may restart from scratch. The Warehouse copy is deleted and rebuilt when replication resumes; table reads may be unavailable, freshness can lag, and the source incurs additional reads. Stopping and restarting the pipeline interrupts replication for other tables. Duration is unknown. The pipeline must be started and initial sync enabled for the table before the reset. The immediate response retains ETL reset states; it does not establish recopy completion. Inspect warehouse tables get and warehouse status separately. Do not automatically retry an uncertain response: repeating this request may reset the table again. There is no server-side preview, revision check, idempotency key or operation polling. + +- Access: mutation, consent defaults to No (`--yes` when it cannot prompt). +- Feature: `warehouse`. +- Consent: prints the API description before the interactive confirmation. +- Request: `POST /v2/projects/{ref}/warehouse/replication/resync` (`v2-resync-warehouse-replication`), success 202 json. +- Body: JSON envelope `data.type = warehouse_replication_resync`, fields under `data.attributes`. + +### Flags + +| Flag | Type | Required | Repeatable | Binds to | +| ------------------- | ------ | ---------------------------------------------- | ---------- | ------------------------------ | +| `--schema ` | string | yes, unless `--body` or `--file` has the field | no | body `/data/attributes/schema` | +| `--table
` | string | yes, unless `--body` or `--file` has the field | no | body `/data/attributes/table` | + ## `supabase warehouse status` Get consolidated Warehouse status and capabilities diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts index c4a39cb9dc..6cf2e2b16a 100644 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ b/apps/cli/src/commands/api/generated.schemas.ts @@ -2,6 +2,220 @@ import type { ApiCommandSchemas } from "./api-command.model.ts"; export const apiCommandSchemas = { + "v2-add-warehouse-replication": { + request: { + contentType: "application/json", + schema: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + additionalProperties: false, + properties: { + schema: { + description: + "Literal source PostgreSQL schema. Omit table to select its current tables.", + minLength: 1, + type: "string", + }, + table: { + description: "Literal source table name. Omit to select the schema.", + minLength: 1, + type: "string", + }, + }, + required: ["schema"], + type: "object", + }, + type: { + description: "Resource type.", + enum: ["warehouse_replication_change"], + type: "string", + }, + }, + required: ["attributes", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + action: { + enum: ["add", "remove"], + type: "string", + }, + affected_tables: { + items: { + properties: { + id: { + maximum: 4294967295, + type: "integer", + exclusiveMinimum: 0, + }, + name: { + minLength: 1, + type: "string", + }, + schema: { + minLength: 1, + type: "string", + }, + }, + required: ["id", "name", "schema"], + type: "object", + }, + type: "array", + }, + application_status: { + description: + "Immediate orchestration result. Restart acceptance does not establish runtime application or copy completion.", + enum: ["configured", "restart_requested", "unchanged"], + type: "string", + }, + changed: { + type: "boolean", + }, + includes_future_tables: { + enum: [false], + type: "boolean", + }, + pipeline_id: { + type: "string", + }, + pipeline_status_before: { + type: "string", + }, + selected_table_count: { + maximum: 9007199254740991, + minimum: 0, + type: "integer", + }, + source_data_preserved: { + enum: [true], + type: "boolean", + }, + tables: { + description: + "Resulting configured selection, with best-effort replication observations.", + items: { + properties: { + copy_name: { + type: "string", + }, + id: { + maximum: 4294967295, + type: "integer", + exclusiveMinimum: 0, + }, + lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + name: { + minLength: 1, + type: "string", + }, + replication_state: { + type: ["string", "null"], + }, + schema: { + minLength: 1, + type: "string", + }, + state: { + description: + "Last observed table state; null when unavailable. Does not establish completion of this request.", + enum: ["error", "live", null, "syncing"], + type: ["string", "null"], + }, + }, + required: [ + "copy_name", + "id", + "lag_ms", + "name", + "replication_state", + "schema", + "state", + ], + type: "object", + }, + type: "array", + }, + unchanged_tables: { + items: { + properties: { + id: { + maximum: 4294967295, + type: "integer", + exclusiveMinimum: 0, + }, + name: { + minLength: 1, + type: "string", + }, + schema: { + minLength: 1, + type: "string", + }, + }, + required: ["id", "name", "schema"], + type: "object", + }, + type: "array", + }, + warehouse_data_retained: { + enum: [true], + type: "boolean", + }, + warehouse_enabled: { + enum: [true], + type: "boolean", + }, + }, + required: [ + "action", + "affected_tables", + "application_status", + "changed", + "includes_future_tables", + "pipeline_id", + "pipeline_status_before", + "selected_table_count", + "source_data_preserved", + "tables", + "unchanged_tables", + "warehouse_data_retained", + "warehouse_enabled", + ], + type: "object", + }, + id: { + type: "string", + }, + type: { + description: "Resource type.", + enum: ["warehouse_replication_change"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-disable-warehouse": { result: { $schema: "https://json-schema.org/draft/2020-12/schema", @@ -2107,6 +2321,445 @@ export const apiCommandSchemas = { type: "object", }, }, + "v2-remove-warehouse-replication": { + request: { + contentType: "application/json", + schema: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + additionalProperties: false, + properties: { + schema: { + description: + "Literal source PostgreSQL schema. Omit table to select its current tables.", + minLength: 1, + type: "string", + }, + table: { + description: "Literal source table name. Omit to select the schema.", + minLength: 1, + type: "string", + }, + }, + required: ["schema"], + type: "object", + }, + type: { + description: "Resource type.", + enum: ["warehouse_replication_change"], + type: "string", + }, + }, + required: ["attributes", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + action: { + enum: ["add", "remove"], + type: "string", + }, + affected_tables: { + items: { + properties: { + id: { + maximum: 4294967295, + type: "integer", + exclusiveMinimum: 0, + }, + name: { + minLength: 1, + type: "string", + }, + schema: { + minLength: 1, + type: "string", + }, + }, + required: ["id", "name", "schema"], + type: "object", + }, + type: "array", + }, + application_status: { + description: + "Immediate orchestration result. Restart acceptance does not establish runtime application or copy completion.", + enum: ["configured", "restart_requested", "unchanged"], + type: "string", + }, + changed: { + type: "boolean", + }, + includes_future_tables: { + enum: [false], + type: "boolean", + }, + pipeline_id: { + type: "string", + }, + pipeline_status_before: { + type: "string", + }, + selected_table_count: { + maximum: 9007199254740991, + minimum: 0, + type: "integer", + }, + source_data_preserved: { + enum: [true], + type: "boolean", + }, + tables: { + description: + "Resulting configured selection, with best-effort replication observations.", + items: { + properties: { + copy_name: { + type: "string", + }, + id: { + maximum: 4294967295, + type: "integer", + exclusiveMinimum: 0, + }, + lag_ms: { + minimum: 0, + type: ["number", "null"], + }, + name: { + minLength: 1, + type: "string", + }, + replication_state: { + type: ["string", "null"], + }, + schema: { + minLength: 1, + type: "string", + }, + state: { + description: + "Last observed table state; null when unavailable. Does not establish completion of this request.", + enum: ["error", "live", null, "syncing"], + type: ["string", "null"], + }, + }, + required: [ + "copy_name", + "id", + "lag_ms", + "name", + "replication_state", + "schema", + "state", + ], + type: "object", + }, + type: "array", + }, + unchanged_tables: { + items: { + properties: { + id: { + maximum: 4294967295, + type: "integer", + exclusiveMinimum: 0, + }, + name: { + minLength: 1, + type: "string", + }, + schema: { + minLength: 1, + type: "string", + }, + }, + required: ["id", "name", "schema"], + type: "object", + }, + type: "array", + }, + warehouse_data_retained: { + enum: [true], + type: "boolean", + }, + warehouse_enabled: { + enum: [true], + type: "boolean", + }, + }, + required: [ + "action", + "affected_tables", + "application_status", + "changed", + "includes_future_tables", + "pipeline_id", + "pipeline_status_before", + "selected_table_count", + "source_data_preserved", + "tables", + "unchanged_tables", + "warehouse_data_retained", + "warehouse_enabled", + ], + type: "object", + }, + id: { + type: "string", + }, + type: { + description: "Resource type.", + enum: ["warehouse_replication_change"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, + "v2-resync-warehouse-replication": { + request: { + contentType: "application/json", + schema: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + additionalProperties: false, + properties: { + schema: { + description: "Literal source PostgreSQL schema of the table.", + minLength: 1, + type: "string", + }, + table: { + description: "Literal name of the single source table to reset and recopy.", + minLength: 1, + type: "string", + }, + }, + required: ["schema", "table"], + type: "object", + }, + type: { + description: "Resource type.", + enum: ["warehouse_replication_resync"], + type: "string", + }, + }, + required: ["attributes", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, + result: { + $schema: "https://json-schema.org/draft/2020-12/schema", + properties: { + data: { + properties: { + attributes: { + properties: { + application_status: { + description: + "ETL reset replication state. Destination rebuild and recopy may still be pending.", + enum: ["reset"], + type: "string", + }, + pipeline_id: { + description: "Pipeline ID", + minLength: 1, + type: "string", + examples: ["03dg2o5teb2eucxr9ggh3uie6"], + }, + source_data_preserved: { + enum: [true], + type: "boolean", + }, + source_table: { + properties: { + id: { + maximum: 4294967295, + type: "integer", + exclusiveMinimum: 0, + }, + name: { + minLength: 1, + type: "string", + }, + schema: { + minLength: 1, + type: "string", + }, + }, + required: ["id", "name", "schema"], + type: "object", + }, + tables: { + description: "Rolled back tables", + items: { + properties: { + new_state: { + description: "Table replication state", + oneOf: [ + { + properties: { + name: { + enum: ["queued"], + type: "string", + }, + }, + required: ["name"], + type: "object", + }, + { + properties: { + name: { + enum: ["copying_table"], + type: "string", + }, + }, + required: ["name"], + type: "object", + }, + { + properties: { + name: { + enum: ["copied_table"], + type: "string", + }, + }, + required: ["name"], + type: "object", + }, + { + properties: { + name: { + enum: ["following_wal"], + type: "string", + }, + }, + required: ["name"], + type: "object", + }, + { + properties: { + name: { + enum: ["error"], + type: "string", + }, + reason: { + type: "string", + }, + retry_policy: { + oneOf: [ + { + properties: { + policy: { + enum: ["no_retry"], + type: "string", + }, + }, + required: ["policy"], + type: "object", + }, + { + properties: { + policy: { + enum: ["manual_retry"], + type: "string", + }, + }, + required: ["policy"], + type: "object", + }, + { + properties: { + next_retry: { + description: "Next retry time (RFC 3339 timestamp)", + type: "string", + examples: ["2025-01-02T03:04:05Z"], + }, + policy: { + enum: ["timed_retry"], + type: "string", + }, + }, + required: ["next_retry", "policy"], + type: "object", + }, + ], + }, + solution: { + type: ["string", "null"], + }, + }, + required: ["name", "reason", "retry_policy"], + type: "object", + }, + ], + }, + table_id: { + description: "Table id (Postgres OID)", + maximum: 4294967295, + minimum: 0, + type: "integer", + examples: [16408], + }, + }, + required: ["new_state", "table_id"], + type: "object", + }, + type: "array", + }, + }, + required: [ + "application_status", + "pipeline_id", + "source_data_preserved", + "source_table", + "tables", + ], + type: "object", + }, + id: { + type: "string", + }, + type: { + description: "Resource type.", + enum: ["warehouse_replication_resync"], + type: "string", + }, + }, + required: ["attributes", "id", "type"], + type: "object", + }, + }, + required: ["data"], + type: "object", + }, + }, "v2-update-warehouse-table-layout": { request: { contentType: "application/json", diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 946bd3e493..2b88424975 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -382,6 +382,183 @@ export const apiCommands = [ }, ], }, + { + command: ["warehouse", "replication", "add"], + operationId: "v2-add-warehouse-replication", + definition: "v2AddWarehouseReplication", + method: "POST", + apiPath: "/v2/projects/{ref}/warehouse/replication/add", + summary: "Add source tables to Warehouse replication", + description: + "Adds one eligible source table or the currently eligible tables in a schema to an enabled Warehouse. Existing selections and layouts are preserved; already-selected tables are unchanged. Schema selection excludes future tables, except future partitions of selected partition roots. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline remains stopped and requires an explicit start before copying. Initial copy adds source reads; duration is unknown. Unsafe reattachment of retained data is rejected. The response describes configuration and restart acceptance, not completed copy or streaming. Failures may have partial effects; inspect table and pipeline state before retrying.", + readOnly: false, + confirmDescription: true, + feature: "warehouse", + body: { + contentType: "application/json", + kind: "json-envelope", + type: "warehouse_replication_change", + }, + response: { + status: 202, + kind: "json", + }, + flags: [ + { + name: "schema", + type: "string", + repeatable: false, + required: true, + description: "Literal source PostgreSQL schema. Omit table to select its current tables.", + }, + { + name: "table", + type: "string", + repeatable: false, + required: false, + description: "Literal source table name. Omit to select the schema.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "body", + name: "schema", + pointer: "/data/attributes/schema", + source: "flag", + flag: "schema", + }, + { + location: "body", + name: "table", + pointer: "/data/attributes/table", + source: "flag", + flag: "table", + }, + ], + }, + { + command: ["warehouse", "replication", "remove"], + operationId: "v2-remove-warehouse-replication", + definition: "v2RemoveWarehouseReplication", + method: "POST", + apiPath: "/v2/projects/{ref}/warehouse/replication/remove", + summary: "Remove source tables from Warehouse replication", + description: + "Removes one selected source table or all selected tables in a schema as a batch. Source PostgreSQL rows and existing Warehouse data are retained. The retained copy stops receiving updates. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline stays stopped. Removing an unselected target is unchanged. Removing the last target leaves Warehouse enabled with an empty selection. Publication changes and restart acceptance do not establish observed exclusion by active replication. Failures may have partial effects; inspect the selection and pipeline before retrying.", + readOnly: false, + confirmDescription: true, + feature: "warehouse", + body: { + contentType: "application/json", + kind: "json-envelope", + type: "warehouse_replication_change", + }, + response: { + status: 202, + kind: "json", + }, + flags: [ + { + name: "schema", + type: "string", + repeatable: false, + required: true, + description: "Literal source PostgreSQL schema. Omit table to select its current tables.", + }, + { + name: "table", + type: "string", + repeatable: false, + required: false, + description: "Literal source table name. Omit to select the schema.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "body", + name: "schema", + pointer: "/data/attributes/schema", + source: "flag", + flag: "schema", + }, + { + location: "body", + name: "table", + pointer: "/data/attributes/table", + source: "flag", + flag: "table", + }, + ], + }, + { + command: ["warehouse", "replication", "resync"], + operationId: "v2-resync-warehouse-replication", + definition: "v2ResyncWarehouseReplication", + method: "POST", + apiPath: "/v2/projects/{ref}/warehouse/replication/resync", + summary: "Reset and rebuild one Warehouse table", + description: + "Resets replication for one selected source table using its currently saved layout. Source rows, saved layouts and completed replication state for unrelated tables are preserved. In-progress initial copies of other tables may restart from scratch. The Warehouse copy is deleted and rebuilt when replication resumes; table reads may be unavailable, freshness can lag, and the source incurs additional reads. Stopping and restarting the pipeline interrupts replication for other tables. Duration is unknown. The pipeline must be started and initial sync enabled for the table before the reset. The immediate response retains ETL reset states; it does not establish recopy completion. Inspect warehouse tables get and warehouse status separately. Do not automatically retry an uncertain response: repeating this request may reset the table again. There is no server-side preview, revision check, idempotency key or operation polling.", + readOnly: false, + confirmDescription: true, + feature: "warehouse", + body: { + contentType: "application/json", + kind: "json-envelope", + type: "warehouse_replication_resync", + }, + response: { + status: 202, + kind: "json", + }, + flags: [ + { + name: "schema", + type: "string", + repeatable: false, + required: true, + description: "Literal source PostgreSQL schema of the table.", + }, + { + name: "table", + type: "string", + repeatable: false, + required: true, + description: "Literal name of the single source table to reset and recopy.", + }, + ], + bindings: [ + { + location: "path", + name: "ref", + source: "target", + }, + { + location: "body", + name: "schema", + pointer: "/data/attributes/schema", + source: "flag", + flag: "schema", + }, + { + location: "body", + name: "table", + pointer: "/data/attributes/table", + source: "flag", + flag: "table", + }, + ], + }, { command: ["warehouse", "status"], operationId: "v2-get-warehouse-status", diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 4837a9dfd5..92464a3b62 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -231,7 +231,10 @@ const handle = Effect.fn("api-command.run")(function* ( if (!entry.readOnly) { yield* requireHostedMutationConsent({ action: summaryText(entry), - details: consentDetails(entry, decoded), + details: [ + ...(entry.confirmDescription && entry.description ? [entry.description] : []), + ...consentDetails(entry, decoded), + ], }); } diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index d4064ff9d3..84c5de3b6e 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -2546,7 +2546,7 @@ "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1query-stats", "value": { "get": { - "description": "Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.\n\nThis endpoint is currently in its **Alpha** stage.", + "description": "Returns aggregate workload measurements over a bounded time range, using the project\u2019s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.\n\nThis endpoint is currently in its **Alpha** stage.", "operationId": "v2-get-warehouse-query-stats", "parameters": [ { @@ -2938,7 +2938,7 @@ "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1capacity", "value": { "get": { - "description": "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.\n\nThis endpoint is currently in its **Alpha** stage.", + "description": "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project\u2019s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.\n\nThis endpoint is currently in its **Alpha** stage.", "operationId": "v2-get-warehouse-capacity", "parameters": [ { @@ -3121,5 +3121,927 @@ } }, "$comment": "Public Warehouse capacity metrics generate warehouse inspect capacity." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseReplicationRequest", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "additionalProperties": false, + "properties": { + "schema": { + "description": "Literal source PostgreSQL schema. Omit table to select its current tables.", + "minLength": 1, + "type": "string" + }, + "table": { + "description": "Literal source table name. Omit to select the schema.", + "minLength": 1, + "type": "string" + } + }, + "required": ["schema"], + "type": "object" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_replication_change"], + "type": "string" + } + }, + "required": ["attributes", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse replication selection request contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseReplicationResponse_Output", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "action": { + "enum": ["add", "remove"], + "type": "string" + }, + "affected_tables": { + "items": { + "properties": { + "id": { + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + }, + "name": { + "minLength": 1, + "type": "string" + }, + "schema": { + "minLength": 1, + "type": "string" + } + }, + "required": ["id", "name", "schema"], + "type": "object" + }, + "type": "array" + }, + "application_status": { + "description": "Immediate orchestration result. Restart acceptance does not establish runtime application or copy completion.", + "enum": ["configured", "restart_requested", "unchanged"], + "type": "string" + }, + "changed": { + "type": "boolean" + }, + "includes_future_tables": { + "enum": [false], + "type": "boolean" + }, + "pipeline_id": { + "type": "string" + }, + "pipeline_status_before": { + "type": "string" + }, + "selected_table_count": { + "maximum": 9007199254740991, + "minimum": 0, + "type": "integer" + }, + "source_data_preserved": { + "enum": [true], + "type": "boolean" + }, + "tables": { + "description": "Resulting configured selection, with best-effort replication observations.", + "items": { + "properties": { + "copy_name": { + "type": "string" + }, + "id": { + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + }, + "lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "name": { + "minLength": 1, + "type": "string" + }, + "replication_state": { + "nullable": true, + "type": "string" + }, + "schema": { + "minLength": 1, + "type": "string" + }, + "state": { + "description": "Last observed table state; null when unavailable. Does not establish completion of this request.", + "enum": ["error", "live", null, "syncing"], + "nullable": true, + "type": "string" + } + }, + "required": [ + "copy_name", + "id", + "lag_ms", + "name", + "replication_state", + "schema", + "state" + ], + "type": "object" + }, + "type": "array" + }, + "unchanged_tables": { + "items": { + "properties": { + "id": { + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + }, + "name": { + "minLength": 1, + "type": "string" + }, + "schema": { + "minLength": 1, + "type": "string" + } + }, + "required": ["id", "name", "schema"], + "type": "object" + }, + "type": "array" + }, + "warehouse_data_retained": { + "enum": [true], + "type": "boolean" + }, + "warehouse_enabled": { + "enum": [true], + "type": "boolean" + } + }, + "required": [ + "action", + "affected_tables", + "application_status", + "changed", + "includes_future_tables", + "pipeline_id", + "pipeline_status_before", + "selected_table_count", + "source_data_preserved", + "tables", + "unchanged_tables", + "warehouse_data_retained", + "warehouse_enabled" + ], + "type": "object" + }, + "id": { + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_replication_change"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse replication change response contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseResyncRequest", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "additionalProperties": false, + "properties": { + "schema": { + "description": "Literal source PostgreSQL schema of the table.", + "minLength": 1, + "type": "string" + }, + "table": { + "description": "Literal name of the single source table to reset and recopy.", + "minLength": 1, + "type": "string" + } + }, + "required": ["schema", "table"], + "type": "object" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_replication_resync"], + "type": "string" + } + }, + "required": ["attributes", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse replication resync request contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/components/schemas/V2WarehouseResyncResponse_Output", + "value": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "application_status": { + "description": "ETL reset replication state. Destination rebuild and recopy may still be pending.", + "enum": ["reset"], + "type": "string" + }, + "pipeline_id": { + "description": "Pipeline ID", + "example": "03dg2o5teb2eucxr9ggh3uie6", + "minLength": 1, + "type": "string" + }, + "source_data_preserved": { + "enum": [true], + "type": "boolean" + }, + "source_table": { + "properties": { + "id": { + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + }, + "name": { + "minLength": 1, + "type": "string" + }, + "schema": { + "minLength": 1, + "type": "string" + } + }, + "required": ["id", "name", "schema"], + "type": "object" + }, + "tables": { + "description": "Rolled back tables", + "items": { + "properties": { + "new_state": { + "description": "Table replication state", + "oneOf": [ + { + "properties": { + "name": { + "enum": ["queued"], + "type": "string" + } + }, + "required": ["name"], + "type": "object" + }, + { + "properties": { + "name": { + "enum": ["copying_table"], + "type": "string" + } + }, + "required": ["name"], + "type": "object" + }, + { + "properties": { + "name": { + "enum": ["copied_table"], + "type": "string" + } + }, + "required": ["name"], + "type": "object" + }, + { + "properties": { + "name": { + "enum": ["following_wal"], + "type": "string" + } + }, + "required": ["name"], + "type": "object" + }, + { + "properties": { + "name": { + "enum": ["error"], + "type": "string" + }, + "reason": { + "type": "string" + }, + "retry_policy": { + "oneOf": [ + { + "properties": { + "policy": { + "enum": ["no_retry"], + "type": "string" + } + }, + "required": ["policy"], + "type": "object" + }, + { + "properties": { + "policy": { + "enum": ["manual_retry"], + "type": "string" + } + }, + "required": ["policy"], + "type": "object" + }, + { + "properties": { + "next_retry": { + "description": "Next retry time (RFC 3339 timestamp)", + "example": "2025-01-02T03:04:05Z", + "type": "string" + }, + "policy": { + "enum": ["timed_retry"], + "type": "string" + } + }, + "required": ["next_retry", "policy"], + "type": "object" + } + ] + }, + "solution": { + "nullable": true, + "type": "string" + } + }, + "required": ["name", "reason", "retry_policy"], + "type": "object" + } + ] + }, + "table_id": { + "description": "Table id (Postgres OID)", + "example": 16408, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + } + }, + "required": ["new_state", "table_id"], + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "application_status", + "pipeline_id", + "source_data_preserved", + "source_table", + "tables" + ], + "type": "object" + }, + "id": { + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_replication_resync"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "$comment": "The Warehouse replication resync response contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1replication~1add", + "value": { + "post": { + "description": "Adds one eligible source table or the currently eligible tables in a schema to an enabled Warehouse. Existing selections and layouts are preserved; already-selected tables are unchanged. Schema selection excludes future tables, except future partitions of selected partition roots. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline remains stopped and requires an explicit start before copying. Initial copy adds source reads; duration is unknown. Unsafe reattachment of retained data is rejected. The response describes configuration and restart acceptance, not completed copy or streaming. Failures may have partial effects; inspect table and pipeline state before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-add-warehouse-replication", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseReplicationRequest" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseReplicationResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid or ineligible source selection" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse pipeline, publication or selected table not found" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse lifecycle, initial sync or retained data conflict" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Backend unavailable or outcome uncertain; inspect table and pipeline state before retrying" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Add source tables to Warehouse replication", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse.replication", + "method": "add" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The Warehouse replication add contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1replication~1remove", + "value": { + "post": { + "description": "Removes one selected source table or all selected tables in a schema as a batch. Source PostgreSQL rows and existing Warehouse data are retained. The retained copy stops receiving updates. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline stays stopped. Removing an unselected target is unchanged. Removing the last target leaves Warehouse enabled with an empty selection. Publication changes and restart acceptance do not establish observed exclusion by active replication. Failures may have partial effects; inspect the selection and pipeline before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-remove-warehouse-replication", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseReplicationRequest" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseReplicationResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid or ineligible source selection" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse pipeline, publication or selected table not found" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse lifecycle, initial sync or retained data conflict" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Backend unavailable or outcome uncertain; inspect table and pipeline state before retrying" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Remove source tables from Warehouse replication", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse.replication", + "method": "remove" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The Warehouse replication remove contract is not yet in the deployed Management API specification." + }, + { + "op": "add", + "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1replication~1resync", + "value": { + "post": { + "description": "Resets replication for one selected source table using its currently saved layout. Source rows, saved layouts and completed replication state for unrelated tables are preserved. In-progress initial copies of other tables may restart from scratch. The Warehouse copy is deleted and rebuilt when replication resumes; table reads may be unavailable, freshness can lag, and the source incurs additional reads. Stopping and restarting the pipeline interrupts replication for other tables. Duration is unknown. The pipeline must be started and initial sync enabled for the table before the reset. The immediate response retains ETL reset states; it does not establish recopy completion. Inspect warehouse tables get and warehouse status separately. Do not automatically retry an uncertain response: repeating this request may reset the table again. There is no server-side preview, revision check, idempotency key or operation polling.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-resync-warehouse-replication", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseResyncRequest" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseResyncResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid or ineligible source selection" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse pipeline, publication or selected table not found" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse lifecycle, initial sync or retained data conflict" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Backend unavailable or outcome uncertain; inspect table and pipeline state before retrying" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Reset and rebuild one Warehouse table", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse.replication", + "method": "resync" + }, + "x-scalar-stability": "experimental" + } + }, + "$comment": "The Warehouse replication resync contract is not yet in the deployed Management API specification." } ] diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index 12aa997d93..6fd5080342 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -11551,6 +11551,142 @@ export const V1VerifyDnsConfigOutput = Schema.Struct({ }), }), }); +export const V2AddWarehouseReplicationInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + data: Schema.Struct({ + attributes: Schema.Struct({ + schema: Schema.String.annotate({ + description: "Literal source PostgreSQL schema. Omit table to select its current tables.", + }).check(Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" })), + table: Schema.optionalKey( + Schema.String.annotate({ + description: "Literal source table name. Omit to select the schema.", + }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + ), + }), + type: Schema.Literal("warehouse_replication_change").annotate({ + description: "Resource type.", + }), + }), +}); +export const V2AddWarehouseReplicationOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + action: Schema.Union([Schema.Literals(["add", "remove"]), OpenString]), + affected_tables: Schema.Array( + Schema.Struct({ + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + name: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + schema: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + }), + ), + application_status: Schema.Union([ + Schema.Literals(["configured", "restart_requested", "unchanged"]).annotate({ + description: + "Immediate orchestration result. Restart acceptance does not establish runtime application or copy completion.", + }), + OpenString, + ]), + changed: Schema.Boolean, + includes_future_tables: Schema.Literal(false), + pipeline_id: Schema.String, + pipeline_status_before: Schema.String, + selected_table_count: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + source_data_preserved: Schema.Literal(true), + tables: Schema.Array( + Schema.Struct({ + copy_name: Schema.String, + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + lag_ms: Schema.Union([ + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + name: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + replication_state: Schema.Union([Schema.String, Schema.Null]), + schema: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + state: Schema.Union([ + Schema.Union([Schema.Literals(["error", "live", "syncing"]), Schema.Null]).annotate({ + description: + "Last observed table state; null when unavailable. Does not establish completion of this request.", + }), + OpenString, + ]), + }), + ).annotate({ + description: "Resulting configured selection, with best-effort replication observations.", + }), + unchanged_tables: Schema.Array( + Schema.Struct({ + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + name: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + schema: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + }), + ), + warehouse_data_retained: Schema.Literal(true), + warehouse_enabled: Schema.Literal(true), + }), + id: Schema.String, + type: Schema.Literal("warehouse_replication_change").annotate({ + description: "Resource type.", + }), + }), +}); export const V2AssignOrganizationMemberRoleInput = Schema.Struct({ slug: Schema.String.check( Schema.isPattern(new RegExp("^[\\w-]+$", "u")).annotate({ @@ -19895,6 +20031,244 @@ export const V2RemoveOrganizationMembersInput = Schema.Struct({ }), ), }); +export const V2RemoveWarehouseReplicationInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + data: Schema.Struct({ + attributes: Schema.Struct({ + schema: Schema.String.annotate({ + description: "Literal source PostgreSQL schema. Omit table to select its current tables.", + }).check(Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" })), + table: Schema.optionalKey( + Schema.String.annotate({ + description: "Literal source table name. Omit to select the schema.", + }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + ), + }), + type: Schema.Literal("warehouse_replication_change").annotate({ + description: "Resource type.", + }), + }), +}); +export const V2RemoveWarehouseReplicationOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + action: Schema.Union([Schema.Literals(["add", "remove"]), OpenString]), + affected_tables: Schema.Array( + Schema.Struct({ + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + name: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + schema: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + }), + ), + application_status: Schema.Union([ + Schema.Literals(["configured", "restart_requested", "unchanged"]).annotate({ + description: + "Immediate orchestration result. Restart acceptance does not establish runtime application or copy completion.", + }), + OpenString, + ]), + changed: Schema.Boolean, + includes_future_tables: Schema.Literal(false), + pipeline_id: Schema.String, + pipeline_status_before: Schema.String, + selected_table_count: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(9007199254740991).annotate({ + expected: "a value less than or equal to 9007199254740991", + }), + ), + source_data_preserved: Schema.Literal(true), + tables: Schema.Array( + Schema.Struct({ + copy_name: Schema.String, + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + lag_ms: Schema.Union([ + Schema.Number.check(Schema.isFinite().annotate({ expected: "a finite number" })).check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ), + Schema.Null, + ]), + name: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + replication_state: Schema.Union([Schema.String, Schema.Null]), + schema: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + state: Schema.Union([ + Schema.Union([Schema.Literals(["error", "live", "syncing"]), Schema.Null]).annotate({ + description: + "Last observed table state; null when unavailable. Does not establish completion of this request.", + }), + OpenString, + ]), + }), + ).annotate({ + description: "Resulting configured selection, with best-effort replication observations.", + }), + unchanged_tables: Schema.Array( + Schema.Struct({ + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + name: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + schema: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + }), + ), + warehouse_data_retained: Schema.Literal(true), + warehouse_enabled: Schema.Literal(true), + }), + id: Schema.String, + type: Schema.Literal("warehouse_replication_change").annotate({ + description: "Resource type.", + }), + }), +}); +export const V2ResyncWarehouseReplicationInput = Schema.Struct({ + ref: Schema.String.check( + Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), + ) + .check( + Schema.isMaxCodePoints(20).annotate({ expected: "a string with at most 20 code points" }), + ) + .check( + Schema.isPattern(new RegExp("^[a-z]+$", "u")).annotate({ + expected: "a string matching the RegExp ^[a-z]+$", + }), + ), + data: Schema.Struct({ + attributes: Schema.Struct({ + schema: Schema.String.annotate({ + description: "Literal source PostgreSQL schema of the table.", + }).check(Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" })), + table: Schema.String.annotate({ + description: "Literal name of the single source table to reset and recopy.", + }).check(Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" })), + }), + type: Schema.Literal("warehouse_replication_resync").annotate({ + description: "Resource type.", + }), + }), +}); +export const V2ResyncWarehouseReplicationOutput = Schema.Struct({ + data: Schema.Struct({ + attributes: Schema.Struct({ + application_status: Schema.Literal("reset").annotate({ + description: + "ETL reset replication state. Destination rebuild and recopy may still be pending.", + }), + pipeline_id: Schema.String.annotate({ description: "Pipeline ID" }).check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + source_data_preserved: Schema.Literal(true), + source_table: Schema.Struct({ + id: Schema.Number.check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ) + .check(Schema.isGreaterThan(0).annotate({ expected: "a value greater than 0" })), + name: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + schema: Schema.String.check( + Schema.isMinLength(1).annotate({ expected: "a value with a length of at least 1" }), + ), + }), + tables: Schema.Array( + Schema.Struct({ + new_state: Schema.Union( + [ + Schema.Struct({ name: Schema.Literal("queued") }), + Schema.Struct({ name: Schema.Literal("copying_table") }), + Schema.Struct({ name: Schema.Literal("copied_table") }), + Schema.Struct({ name: Schema.Literal("following_wal") }), + Schema.Struct({ + name: Schema.Literal("error"), + reason: Schema.String, + retry_policy: Schema.Union( + [ + Schema.Struct({ policy: Schema.Literal("no_retry") }), + Schema.Struct({ policy: Schema.Literal("manual_retry") }), + Schema.Struct({ + next_retry: Schema.String.annotate({ + description: "Next retry time (RFC 3339 timestamp)", + }), + policy: Schema.Literal("timed_retry"), + }), + ], + { mode: "oneOf" }, + ), + solution: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])), + }), + ], + { mode: "oneOf" }, + ).annotate({ description: "Table replication state" }), + table_id: Schema.Number.annotate({ description: "Table id (Postgres OID)" }) + .check(Schema.isInt().annotate({ expected: "an integer" })) + .check( + Schema.isGreaterThanOrEqualTo(0).annotate({ + expected: "a value greater than or equal to 0", + }), + ) + .check( + Schema.isLessThanOrEqualTo(4294967295).annotate({ + expected: "a value less than or equal to 4294967295", + }), + ), + }), + ).annotate({ description: "Rolled back tables" }), + }), + id: Schema.String, + type: Schema.Literal("warehouse_replication_resync").annotate({ + description: "Resource type.", + }), + }), +}); export const V2RunProjectAdvisorsInput = Schema.Struct({ ref: Schema.String.check( Schema.isMinCodePoints(20).annotate({ expected: "a string with at least 20 code points" }), @@ -21106,6 +21480,7 @@ export const openApiOperationIdMap = { "v1-upgrade-postgres-version": "v1UpgradePostgresVersion", "v1-upsert-a-migration": "v1UpsertAMigration", "v1-verify-dns-config": "v1VerifyDnsConfig", + "v2-add-warehouse-replication": "v2AddWarehouseReplication", "v2-assign-organization-member-role": "v2AssignOrganizationMemberRole", "v2-create-a-branch": "v2CreateABranch", "v2-create-compute-instance-upload": "v2CreateComputeInstanceUpload", @@ -21173,6 +21548,8 @@ export const openApiOperationIdMap = { "v2-projects-ref-webhooks-endpoints-id-test-post": "v2ProjectsRefWebhooksEndpointsIdTestPost", "v2-projects-ref-webhooks-endpoints-post": "v2ProjectsRefWebhooksEndpointsPost", "v2-remove-organization-members": "v2RemoveOrganizationMembers", + "v2-remove-warehouse-replication": "v2RemoveWarehouseReplication", + "v2-resync-warehouse-replication": "v2ResyncWarehouseReplication", "v2-run-project-advisors": "v2RunProjectAdvisors", "v2-transfer-a-project": "v2TransferAProject", "v2-update-log-drain": "v2UpdateLogDrain", @@ -24021,6 +24398,20 @@ export const operationDefinitions = { inputSchema: V1VerifyDnsConfigInput, outputSchema: V1VerifyDnsConfigOutput, }, + v2AddWarehouseReplication: { + id: "v2AddWarehouseReplication", + description: + "Adds one eligible source table or the currently eligible tables in a schema to an enabled Warehouse. Existing selections and layouts are preserved; already-selected tables are unchanged. Schema selection excludes future tables, except future partitions of selected partition roots. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline remains stopped and requires an explicit start before copying. Initial copy adds source reads; duration is unknown. Unsafe reattachment of retained data is rejected. The response describes configuration and restart acceptance, not completed copy or streaming. Failures may have partial effects; inspect table and pipeline state before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "POST", + path: "/v2/projects/{ref}/warehouse/replication/add", + pathParams: ["ref"], + queryParams: [], + headerParams: [], + requestBody: { kind: "json", contentType: "application/json", fields: ["data"] }, + response: { kind: "json" }, + inputSchema: V2AddWarehouseReplicationInput, + outputSchema: V2AddWarehouseReplicationOutput, + }, v2AssignOrganizationMemberRole: { id: "v2AssignOrganizationMemberRole", description: @@ -24856,6 +25247,34 @@ export const operationDefinitions = { inputSchema: V2RemoveOrganizationMembersInput, outputSchema: V2RemoveOrganizationMembersOutput, }, + v2RemoveWarehouseReplication: { + id: "v2RemoveWarehouseReplication", + description: + "Removes one selected source table or all selected tables in a schema as a batch. Source PostgreSQL rows and existing Warehouse data are retained. The retained copy stops receiving updates. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline stays stopped. Removing an unselected target is unchanged. Removing the last target leaves Warehouse enabled with an empty selection. Publication changes and restart acceptance do not establish observed exclusion by active replication. Failures may have partial effects; inspect the selection and pipeline before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "POST", + path: "/v2/projects/{ref}/warehouse/replication/remove", + pathParams: ["ref"], + queryParams: [], + headerParams: [], + requestBody: { kind: "json", contentType: "application/json", fields: ["data"] }, + response: { kind: "json" }, + inputSchema: V2RemoveWarehouseReplicationInput, + outputSchema: V2RemoveWarehouseReplicationOutput, + }, + v2ResyncWarehouseReplication: { + id: "v2ResyncWarehouseReplication", + description: + "Resets replication for one selected source table using its currently saved layout. Source rows, saved layouts and completed replication state for unrelated tables are preserved. In-progress initial copies of other tables may restart from scratch. The Warehouse copy is deleted and rebuilt when replication resumes; table reads may be unavailable, freshness can lag, and the source incurs additional reads. Stopping and restarting the pipeline interrupts replication for other tables. Duration is unknown. The pipeline must be started and initial sync enabled for the table before the reset. The immediate response retains ETL reset states; it does not establish recopy completion. Inspect warehouse tables get and warehouse status separately. Do not automatically retry an uncertain response: repeating this request may reset the table again. There is no server-side preview, revision check, idempotency key or operation polling.\n\nThis endpoint is currently in its **Alpha** stage.", + method: "POST", + path: "/v2/projects/{ref}/warehouse/replication/resync", + pathParams: ["ref"], + queryParams: [], + headerParams: [], + requestBody: { kind: "json", contentType: "application/json", fields: ["data"] }, + response: { kind: "json" }, + inputSchema: V2ResyncWarehouseReplicationInput, + outputSchema: V2ResyncWarehouseReplicationOutput, + }, v2RunProjectAdvisors: { id: "v2RunProjectAdvisors", description: "Runs the project advisors with the given names", diff --git a/packages/api/src/generated/effect-client.ts b/packages/api/src/generated/effect-client.ts index b1a8cd3e65..4b2acf2107 100644 --- a/packages/api/src/generated/effect-client.ts +++ b/packages/api/src/generated/effect-client.ts @@ -2756,6 +2756,22 @@ export const versionedEffectOperations = { }), }, v2: { + addWarehouseReplication: ( + input: typeof operationDefinitions.v2AddWarehouseReplication.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2AddWarehouseReplication.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2AddWarehouseReplication">( + operationDefinitions.v2AddWarehouseReplication, + input, + options, + ); + }), assignOrganizationMemberRole: ( input: typeof operationDefinitions.v2AssignOrganizationMemberRole.inputSchema.Type, options?: SupabaseApiRequestOptions, @@ -3732,6 +3748,38 @@ export const versionedEffectOperations = { options, ); }), + removeWarehouseReplication: ( + input: typeof operationDefinitions.v2RemoveWarehouseReplication.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2RemoveWarehouseReplication.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2RemoveWarehouseReplication">( + operationDefinitions.v2RemoveWarehouseReplication, + input, + options, + ); + }), + resyncWarehouseReplication: ( + input: typeof operationDefinitions.v2ResyncWarehouseReplication.inputSchema.Type, + options?: SupabaseApiRequestOptions, + ): Effect.Effect< + typeof operationDefinitions.v2ResyncWarehouseReplication.outputSchema.Type, + SupabaseApiError, + SupabaseApiClient + > => + Effect.gen(function* () { + const client = yield* SupabaseApiClient; + return yield* client.execute<"v2ResyncWarehouseReplication">( + operationDefinitions.v2ResyncWarehouseReplication, + input, + options, + ); + }), runProjectAdvisors: ( input: typeof operationDefinitions.v2RunProjectAdvisors.inputSchema.Type, options?: SupabaseApiRequestOptions, diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index ae80cc2b1c..6a857e7e5f 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -33737,6 +33737,465 @@ }, "x-scalar-stability": "experimental" } + }, + "/v2/projects/{ref}/warehouse/replication/add": { + "post": { + "description": "Adds one eligible source table or the currently eligible tables in a schema to an enabled Warehouse. Existing selections and layouts are preserved; already-selected tables are unchanged. Schema selection excludes future tables, except future partitions of selected partition roots. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline remains stopped and requires an explicit start before copying. Initial copy adds source reads; duration is unknown. Unsafe reattachment of retained data is rejected. The response describes configuration and restart acceptance, not completed copy or streaming. Failures may have partial effects; inspect table and pipeline state before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-add-warehouse-replication", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseReplicationRequest" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseReplicationResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid or ineligible source selection" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse pipeline, publication or selected table not found" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse lifecycle, initial sync or retained data conflict" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Backend unavailable or outcome uncertain; inspect table and pipeline state before retrying" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Add source tables to Warehouse replication", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse.replication", + "method": "add" + }, + "x-scalar-stability": "experimental" + } + }, + "/v2/projects/{ref}/warehouse/replication/remove": { + "post": { + "description": "Removes one selected source table or all selected tables in a schema as a batch. Source PostgreSQL rows and existing Warehouse data are retained. The retained copy stops receiving updates. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline stays stopped. Removing an unselected target is unchanged. Removing the last target leaves Warehouse enabled with an empty selection. Publication changes and restart acceptance do not establish observed exclusion by active replication. Failures may have partial effects; inspect the selection and pipeline before retrying.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-remove-warehouse-replication", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseReplicationRequest" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseReplicationResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid or ineligible source selection" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse pipeline, publication or selected table not found" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse lifecycle, initial sync or retained data conflict" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Backend unavailable or outcome uncertain; inspect table and pipeline state before retrying" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Remove source tables from Warehouse replication", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse.replication", + "method": "remove" + }, + "x-scalar-stability": "experimental" + } + }, + "/v2/projects/{ref}/warehouse/replication/resync": { + "post": { + "description": "Resets replication for one selected source table using its currently saved layout. Source rows, saved layouts and completed replication state for unrelated tables are preserved. In-progress initial copies of other tables may restart from scratch. The Warehouse copy is deleted and rebuilt when replication resumes; table reads may be unavailable, freshness can lag, and the source incurs additional reads. Stopping and restarting the pipeline interrupts replication for other tables. Duration is unknown. The pipeline must be started and initial sync enabled for the table before the reset. The immediate response retains ETL reset states; it does not establish recopy completion. Inspect warehouse tables get and warehouse status separately. Do not automatically retry an uncertain response: repeating this request may reset the table again. There is no server-side preview, revision check, idempotency key or operation polling.\n\nThis endpoint is currently in its **Alpha** stage.", + "operationId": "v2-resync-warehouse-replication", + "parameters": [ + { + "description": "Project ref", + "in": "path", + "name": "ref", + "required": true, + "schema": { + "example": "abcdefghijklmnopqrst", + "maxLength": 20, + "minLength": 20, + "pattern": "^[a-z]+$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseResyncRequest" + } + } + }, + "required": true + }, + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/V2WarehouseResyncResponse_Output" + } + } + }, + "description": "" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Invalid or ineligible source selection" + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Unauthorized" + }, + "402": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "This feature requires the Pro, Team, or Enterprise organization plan." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Forbidden action" + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse pipeline, publication or selected table not found" + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Warehouse lifecycle, initial sync or retained data conflict" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Rate limit exceeded" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponseBody" + } + } + }, + "description": "Backend unavailable or outcome uncertain; inspect table and pipeline state before retrying" + } + }, + "security": [ + { + "bearer": [] + } + ], + "summary": "Reset and rebuild one Warehouse table", + "tags": ["Projects Warehouse"], + "x-allowed-plans": ["Enterprise", "Pro", "Team"], + "x-badges": [ + { + "name": "OAuth scope: database:write", + "position": "after" + }, + { + "name": "Only available on Pro, Team, Enterprise", + "position": "before" + }, + { + "name": "Alpha", + "position": "before" + } + ], + "x-endpoint-owners": ["pipelines"], + "x-fga-permissions": [["database_write", "project_admin_write"]], + "x-oauth-scope": "database:write", + "x-operation": { + "group": "warehouse.replication", + "method": "resync" + }, + "x-scalar-stability": "experimental" + } } }, "components": { @@ -50756,106 +51215,534 @@ "start": { "type": "number" }, - "step": { - "type": "number" + "step": { + "type": "number" + } + }, + "required": ["end", "metric", "start"], + "type": "object" + }, + "scrape_interval_seconds": { + "type": "number" + }, + "series": { + "items": { + "properties": { + "coverage": { + "description": "Grid point coverage, not proof that every worker was scraped.", + "properties": { + "expected_points": { + "type": "number" + }, + "returned_points": { + "type": "number" + } + }, + "required": ["expected_points", "returned_points"], + "type": "object" + }, + "labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "points": { + "items": { + "properties": { + "timestamp": { + "type": "number" + }, + "value": { + "nullable": true, + "type": "number" + } + }, + "required": ["timestamp", "value"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["coverage", "labels", "points"], + "type": "object" + }, + "type": "array" + }, + "unit": { + "enum": ["grants", "per_second", "queries", "seconds"], + "type": "string" + } + }, + "required": [ + "aggregation", + "availability", + "definition", + "effective", + "last_sample_at", + "metric", + "project_ref", + "requested", + "scrape_interval_seconds", + "series", + "unit" + ], + "type": "object" + }, + "id": { + "enum": [ + "activation_duration_mean", + "activation_duration_p95", + "activation_rate", + "admission_rejection_rate", + "assignment_wait_mean", + "assignment_wait_p95", + "query_in_flight", + "worker_admission_active", + "worker_admission_limit", + "worker_admission_occupied", + "worker_admission_pending" + ], + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_metric"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + }, + "type": "array" + } + }, + "required": ["data"], + "type": "object" + }, + "V2WarehouseReplicationRequest": { + "properties": { + "data": { + "properties": { + "attributes": { + "additionalProperties": false, + "properties": { + "schema": { + "description": "Literal source PostgreSQL schema. Omit table to select its current tables.", + "minLength": 1, + "type": "string" + }, + "table": { + "description": "Literal source table name. Omit to select the schema.", + "minLength": 1, + "type": "string" + } + }, + "required": ["schema"], + "type": "object" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_replication_change"], + "type": "string" + } + }, + "required": ["attributes", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "V2WarehouseReplicationResponse_Output": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "action": { + "enum": ["add", "remove"], + "type": "string" + }, + "affected_tables": { + "items": { + "properties": { + "id": { + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + }, + "name": { + "minLength": 1, + "type": "string" + }, + "schema": { + "minLength": 1, + "type": "string" + } + }, + "required": ["id", "name", "schema"], + "type": "object" + }, + "type": "array" + }, + "application_status": { + "description": "Immediate orchestration result. Restart acceptance does not establish runtime application or copy completion.", + "enum": ["configured", "restart_requested", "unchanged"], + "type": "string" + }, + "changed": { + "type": "boolean" + }, + "includes_future_tables": { + "enum": [false], + "type": "boolean" + }, + "pipeline_id": { + "type": "string" + }, + "pipeline_status_before": { + "type": "string" + }, + "selected_table_count": { + "maximum": 9007199254740991, + "minimum": 0, + "type": "integer" + }, + "source_data_preserved": { + "enum": [true], + "type": "boolean" + }, + "tables": { + "description": "Resulting configured selection, with best-effort replication observations.", + "items": { + "properties": { + "copy_name": { + "type": "string" + }, + "id": { + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + }, + "lag_ms": { + "minimum": 0, + "nullable": true, + "type": "number" + }, + "name": { + "minLength": 1, + "type": "string" + }, + "replication_state": { + "nullable": true, + "type": "string" + }, + "schema": { + "minLength": 1, + "type": "string" + }, + "state": { + "description": "Last observed table state; null when unavailable. Does not establish completion of this request.", + "enum": ["error", "live", null, "syncing"], + "nullable": true, + "type": "string" + } + }, + "required": [ + "copy_name", + "id", + "lag_ms", + "name", + "replication_state", + "schema", + "state" + ], + "type": "object" + }, + "type": "array" + }, + "unchanged_tables": { + "items": { + "properties": { + "id": { + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + }, + "name": { + "minLength": 1, + "type": "string" + }, + "schema": { + "minLength": 1, + "type": "string" } }, - "required": ["end", "metric", "start"], + "required": ["id", "name", "schema"], "type": "object" }, - "scrape_interval_seconds": { - "type": "number" + "type": "array" + }, + "warehouse_data_retained": { + "enum": [true], + "type": "boolean" + }, + "warehouse_enabled": { + "enum": [true], + "type": "boolean" + } + }, + "required": [ + "action", + "affected_tables", + "application_status", + "changed", + "includes_future_tables", + "pipeline_id", + "pipeline_status_before", + "selected_table_count", + "source_data_preserved", + "tables", + "unchanged_tables", + "warehouse_data_retained", + "warehouse_enabled" + ], + "type": "object" + }, + "id": { + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_replication_change"], + "type": "string" + } + }, + "required": ["attributes", "id", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "V2WarehouseResyncRequest": { + "properties": { + "data": { + "properties": { + "attributes": { + "additionalProperties": false, + "properties": { + "schema": { + "description": "Literal source PostgreSQL schema of the table.", + "minLength": 1, + "type": "string" + }, + "table": { + "description": "Literal name of the single source table to reset and recopy.", + "minLength": 1, + "type": "string" + } + }, + "required": ["schema", "table"], + "type": "object" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_replication_resync"], + "type": "string" + } + }, + "required": ["attributes", "type"], + "type": "object" + } + }, + "required": ["data"], + "type": "object" + }, + "V2WarehouseResyncResponse_Output": { + "properties": { + "data": { + "properties": { + "attributes": { + "properties": { + "application_status": { + "description": "ETL reset replication state. Destination rebuild and recopy may still be pending.", + "enum": ["reset"], + "type": "string" + }, + "pipeline_id": { + "description": "Pipeline ID", + "example": "03dg2o5teb2eucxr9ggh3uie6", + "minLength": 1, + "type": "string" + }, + "source_data_preserved": { + "enum": [true], + "type": "boolean" + }, + "source_table": { + "properties": { + "id": { + "exclusiveMinimum": true, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + }, + "name": { + "minLength": 1, + "type": "string" + }, + "schema": { + "minLength": 1, + "type": "string" + } }, - "series": { - "items": { - "properties": { - "coverage": { - "description": "Grid point coverage, not proof that every worker was scraped.", - "properties": { - "expected_points": { - "type": "number" + "required": ["id", "name", "schema"], + "type": "object" + }, + "tables": { + "description": "Rolled back tables", + "items": { + "properties": { + "new_state": { + "description": "Table replication state", + "oneOf": [ + { + "properties": { + "name": { + "enum": ["queued"], + "type": "string" + } }, - "returned_points": { - "type": "number" - } + "required": ["name"], + "type": "object" }, - "required": ["expected_points", "returned_points"], - "type": "object" - }, - "labels": { - "additionalProperties": { - "type": "string" + { + "properties": { + "name": { + "enum": ["copying_table"], + "type": "string" + } + }, + "required": ["name"], + "type": "object" }, - "type": "object" - }, - "points": { - "items": { + { "properties": { - "timestamp": { - "type": "number" + "name": { + "enum": ["copied_table"], + "type": "string" + } + }, + "required": ["name"], + "type": "object" + }, + { + "properties": { + "name": { + "enum": ["following_wal"], + "type": "string" + } + }, + "required": ["name"], + "type": "object" + }, + { + "properties": { + "name": { + "enum": ["error"], + "type": "string" }, - "value": { + "reason": { + "type": "string" + }, + "retry_policy": { + "oneOf": [ + { + "properties": { + "policy": { + "enum": ["no_retry"], + "type": "string" + } + }, + "required": ["policy"], + "type": "object" + }, + { + "properties": { + "policy": { + "enum": ["manual_retry"], + "type": "string" + } + }, + "required": ["policy"], + "type": "object" + }, + { + "properties": { + "next_retry": { + "description": "Next retry time (RFC 3339 timestamp)", + "example": "2025-01-02T03:04:05Z", + "type": "string" + }, + "policy": { + "enum": ["timed_retry"], + "type": "string" + } + }, + "required": ["next_retry", "policy"], + "type": "object" + } + ] + }, + "solution": { "nullable": true, - "type": "number" + "type": "string" } }, - "required": ["timestamp", "value"], + "required": ["name", "reason", "retry_policy"], "type": "object" - }, - "type": "array" - } + } + ] }, - "required": ["coverage", "labels", "points"], - "type": "object" + "table_id": { + "description": "Table id (Postgres OID)", + "example": 16408, + "maximum": 4294967295, + "minimum": 0, + "type": "integer" + } }, - "type": "array" + "required": ["new_state", "table_id"], + "type": "object" }, - "unit": { - "enum": ["grants", "per_second", "queries", "seconds"], - "type": "string" - } - }, - "required": [ - "aggregation", - "availability", - "definition", - "effective", - "last_sample_at", - "metric", - "project_ref", - "requested", - "scrape_interval_seconds", - "series", - "unit" - ], - "type": "object" - }, - "id": { - "enum": [ - "activation_duration_mean", - "activation_duration_p95", - "activation_rate", - "admission_rejection_rate", - "assignment_wait_mean", - "assignment_wait_p95", - "query_in_flight", - "worker_admission_active", - "worker_admission_limit", - "worker_admission_occupied", - "worker_admission_pending" - ], - "type": "string" + "type": "array" + } }, - "type": { - "description": "Resource type.", - "enum": ["warehouse_metric"], - "type": "string" - } + "required": [ + "application_status", + "pipeline_id", + "source_data_preserved", + "source_table", + "tables" + ], + "type": "object" }, - "required": ["attributes", "id", "type"], - "type": "object" + "id": { + "type": "string" + }, + "type": { + "description": "Resource type.", + "enum": ["warehouse_replication_resync"], + "type": "string" + } }, - "type": "array" + "required": ["attributes", "id", "type"], + "type": "object" } }, "required": ["data"], diff --git a/packages/api/src/generated/permissions.ts b/packages/api/src/generated/permissions.ts index 59ffaf69a7..1912f851fb 100644 --- a/packages/api/src/generated/permissions.ts +++ b/packages/api/src/generated/permissions.ts @@ -459,4 +459,16 @@ export const operationPermissions: Readonly }, "v2-get-warehouse-query-stats": { fga: [["database_read"]], oauthScope: "database:read" }, "v2-get-warehouse-capacity": { fga: [["database_read"]], oauthScope: "database:read" }, + "v2-add-warehouse-replication": { + fga: [["database_write", "project_admin_write"]], + oauthScope: "database:write", + }, + "v2-remove-warehouse-replication": { + fga: [["database_write", "project_admin_write"]], + oauthScope: "database:write", + }, + "v2-resync-warehouse-replication": { + fga: [["database_write", "project_admin_write"]], + oauthScope: "database:write", + }, }; From 9c09ddcd2091d0b8bf929e9af7491f08d6e7720a Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 21:01:07 +0100 Subject: [PATCH 37/45] test(cli): expect JSON from piped warehouse enable --wait with text format --- .../src/commands/api/api-commands.e2e.test.ts | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/apps/cli/src/commands/api/api-commands.e2e.test.ts b/apps/cli/src/commands/api/api-commands.e2e.test.ts index 4c93e3ee8c..287b753417 100644 --- a/apps/cli/src/commands/api/api-commands.e2e.test.ts +++ b/apps/cli/src/commands/api/api-commands.e2e.test.ts @@ -197,24 +197,22 @@ it.live("warehouse status keeps consolidated API bytes when stdout is piped", () }).pipe(Effect.provide(BunServices.layer)), ); -it.live("warehouse enable --wait --output-format text renders the final response for people", () => - Effect.gen(function* () { - const { result } = yield* runWarehouse( - ["enable", "--schema", "public", "--wait", "--yes", "--output-format", "text"], - (request) => - request.method === "POST" - ? json(202, { data: { attributes: { selection_id: SEL } } }) - : statusBody("succeeded"), - ); +it.live( + "warehouse enable --wait --output-format text keeps the final JSON response when piped", + () => + Effect.gen(function* () { + const final = statusBody("succeeded"); + const { result } = yield* runWarehouse( + ["enable", "--schema", "public", "--wait", "--yes", "--output-format", "text"], + (request) => + request.method === "POST" + ? json(202, { data: { attributes: { selection_id: SEL } } }) + : final, + ); - requireCliSuccess(result, "warehouse enable --wait --output-format text"); - expect(result.exitCode, result.stderr).toBe(0); - expect( - result.stdout.endsWith( - `Warehouse setup\n Selection ID ${SEL}\n Status succeeded\n`, - ), - ).toBe(true); - }).pipe(Effect.provide(BunServices.layer)), + requireCliSuccess(result, "warehouse enable --wait --output-format text"); + expect(result.stdout, result.stderr).toBe(final.body); + }).pipe(Effect.provide(BunServices.layer)), ); it.live("warehouse enable without --yes refuses to run when stdin is piped", () => From d4319e5d1a8c625953a8d51babe1a8c56d72ec41 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 21:04:44 +0100 Subject: [PATCH 38/45] fix(cli): map ambiguous-remote auth failures and share routing args --- apps/cli/src/command-internal/routing-args.ts | 23 +++++++++++++ .../cli/src/command-internal/stack-backend.ts | 21 +++--------- .../src/commands/api/api-command-features.ts | 17 +++------- .../experimental/compute/compute-backend.ts | 17 +++------- apps/cli/src/shared/cli/standard-errors.ts | 13 ++++++++ .../shared/cli/standard-errors.unit.test.ts | 32 ++++++++++++++++++- 6 files changed, 82 insertions(+), 41 deletions(-) create mode 100644 apps/cli/src/command-internal/routing-args.ts diff --git a/apps/cli/src/command-internal/routing-args.ts b/apps/cli/src/command-internal/routing-args.ts new file mode 100644 index 0000000000..8bb1f6b47d --- /dev/null +++ b/apps/cli/src/command-internal/routing-args.ts @@ -0,0 +1,23 @@ +import { extractCommandPath, hasRootVersionFlag } from "../shared/cli/run.ts"; + +const isCompletionToken = (arg: string | undefined): boolean => + arg === "__complete" || arg === "__completeNoDesc"; + +/** + * Splits argv into the args and command path that backend and feature routing read, or + * `undefined` for `--version`. Completion passes the final token as the cursor word, so it is + * dropped from both. + */ +export const routingArgsFor = ( + args: ReadonlyArray, +): + | { readonly routingArgs: ReadonlyArray; readonly path: ReadonlyArray } + | undefined => { + const routingArgs = isCompletionToken(args[0]) ? args.slice(0, -1) : args; + if (hasRootVersionFlag(routingArgs)) return undefined; + const commandPath = extractCommandPath(routingArgs); + return { + routingArgs, + path: isCompletionToken(commandPath[0]) ? commandPath.slice(1) : commandPath, + }; +}; diff --git a/apps/cli/src/command-internal/stack-backend.ts b/apps/cli/src/command-internal/stack-backend.ts index 850836704b..3cacfed7bb 100644 --- a/apps/cli/src/command-internal/stack-backend.ts +++ b/apps/cli/src/command-internal/stack-backend.ts @@ -8,7 +8,7 @@ import { Option, type Path, } from "effect"; -import { extractCommandPath, hasRootVersionFlag } from "../shared/cli/run.ts"; +import { routingArgsFor } from "./routing-args.ts"; import type { ExperimentalFeatureFlagError } from "../shared/config/experimental-feature.ts"; import { projectStateMode, @@ -97,21 +97,10 @@ export const resolveProjectStateSelection = Effect.fn("ProjectState.resolveSelec StackRoutingError, FileSystem.FileSystem | Path.Path > { - // Completion passes the final token as the cursor word, so it is not part of - // the resolved command path. - const routingArgs = - input.args[0] === "__complete" || input.args[0] === "__completeNoDesc" - ? input.args.slice(0, -1) - : input.args; - if (hasRootVersionFlag(routingArgs)) - return { projectState: undefined, stackBackend: undefined }; - - const commandPath = extractCommandPath(routingArgs); - const completePath = - commandPath[0] === "__complete" || commandPath[0] === "__completeNoDesc" - ? commandPath.slice(1) - : commandPath; - const routedPath = completePath[0] === "help" ? completePath.slice(1) : completePath; + const routing = routingArgsFor(input.args); + if (routing === undefined) return { projectState: undefined, stackBackend: undefined }; + const { routingArgs, path } = routing; + const routedPath = path[0] === "help" ? path.slice(1) : path; const command = routedPath[0]; const routed = command === undefined || diff --git a/apps/cli/src/commands/api/api-command-features.ts b/apps/cli/src/commands/api/api-command-features.ts index 4720fe9b49..190bffc818 100644 --- a/apps/cli/src/commands/api/api-command-features.ts +++ b/apps/cli/src/commands/api/api-command-features.ts @@ -1,6 +1,6 @@ import { Effect, type FileSystem, type Path } from "effect"; -import { extractCommandPath, hasRootVersionFlag } from "../../shared/cli/run.ts"; +import { routingArgsFor } from "../../command-internal/routing-args.ts"; import { type ExperimentalFeature, type ExperimentalFeatureFlagError, @@ -29,17 +29,10 @@ export const resolveApiCommandFeatures = Effect.fn("ApiCommands.resolveFeatures" ExperimentalFeatureFlagError, FileSystem.FileSystem | Path.Path > { - const routingArgs = - input.args[0] === "__complete" || input.args[0] === "__completeNoDesc" - ? input.args.slice(0, -1) - : input.args; - if (hasRootVersionFlag(routingArgs)) return []; - const commandPath = extractCommandPath(routingArgs); - const completePath = - commandPath[0] === "__complete" || commandPath[0] === "__completeNoDesc" - ? commandPath.slice(1) - : commandPath; - const enabled = yield* Effect.filter(nounFeatures(completePath[0]), (feature) => + const routing = routingArgsFor(input.args); + if (routing === undefined) return []; + const { routingArgs, path } = routing; + const enabled = yield* Effect.filter(nounFeatures(path[0]), (feature) => resolveExperimentalFeature({ feature, configValue: readExperimentalFeatureConfig({ feature, cwd: input.cwd, args: routingArgs }), diff --git a/apps/cli/src/commands/experimental/compute/compute-backend.ts b/apps/cli/src/commands/experimental/compute/compute-backend.ts index 9bda8bf290..3bc76be1b6 100644 --- a/apps/cli/src/commands/experimental/compute/compute-backend.ts +++ b/apps/cli/src/commands/experimental/compute/compute-backend.ts @@ -4,24 +4,17 @@ import { readExperimentalFeatureConfig, resolveExperimentalFeature, } from "../../../shared/config/experimental-feature.ts"; -import { extractCommandPath, hasRootVersionFlag } from "../../../shared/cli/run.ts"; +import { routingArgsFor } from "../../../command-internal/routing-args.ts"; export const resolveComputeEnabled = (input: { readonly args: ReadonlyArray; readonly cwd: string; }): Effect.Effect => Effect.gen(function* () { - const routingArgs = - input.args[0] === "__complete" || input.args[0] === "__completeNoDesc" - ? input.args.slice(0, -1) - : input.args; - if (hasRootVersionFlag(routingArgs)) return false; - const commandPath = extractCommandPath(routingArgs); - const completePath = - commandPath[0] === "__complete" || commandPath[0] === "__completeNoDesc" - ? commandPath.slice(1) - : commandPath; - if (completePath[0] !== undefined && completePath[0] !== "compute") return false; + const routing = routingArgsFor(input.args); + if (routing === undefined) return false; + const { routingArgs, path } = routing; + if (path[0] !== undefined && path[0] !== "compute") return false; return yield* resolveExperimentalFeature({ feature: "compute", configValue: readExperimentalFeatureConfig({ diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index b159352918..88743aced4 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -19,6 +19,7 @@ import { ApiCommandWaitTimeoutError, } from "../../command-internal/command-errors/api-command.errors.ts"; import { LinkBranchListStatusError } from "../../command-internal/target/branch-resolution.errors.ts"; +import { TargetRemoteAmbiguousError } from "../../command-internal/target/target.errors.ts"; import { normalizeCause, upgradeHint, @@ -156,6 +157,18 @@ const failureForError = ( document: documentForStatus(error.status, error.message, {}), }; } + if ( + error instanceof TargetRemoteAmbiguousError && + (error.status !== undefined || error.authFailure !== undefined) + ) { + const hint = error.suggestion ?? null; + return error.status === undefined + ? failure(EXIT_FAILURE, "unauthenticated", error.message, hint) + : { + exitCode: EXIT_FAILURE, + document: documentForStatus(error.status, error.message, { hint: error.suggestion }), + }; + } if (error instanceof ApiCommandUsageError) { return failure(EXIT_USAGE, "usage_error", error.message, error.hint ?? null); } diff --git a/apps/cli/src/shared/cli/standard-errors.unit.test.ts b/apps/cli/src/shared/cli/standard-errors.unit.test.ts index 5db4d82851..76e658cec0 100644 --- a/apps/cli/src/shared/cli/standard-errors.unit.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.unit.test.ts @@ -5,7 +5,10 @@ import * as HttpClientError from "effect/http/HttpClientError"; import { HttpClientRequest, HttpClientResponse } from "effect/http"; import { AccessTokenRequiredError } from "../../auth/errors.ts"; import { InvalidOutputFormatError } from "../../command-internal/output-formats.ts"; -import { TargetSelectorConflictError } from "../../command-internal/target/target.errors.ts"; +import { + TargetRemoteAmbiguousError, + TargetSelectorConflictError, +} from "../../command-internal/target/target.errors.ts"; import { HostedMutationConsentRequiredError, HostedMutationDeclinedError, @@ -217,6 +220,33 @@ describe("standardFailureFor", () => { ), expected: { exitCode: 1, code: String(code), status: Number(status), hint: null }, })), + { + name: "ambiguous remote whose branch listing was forbidden", + cause: Cause.fail( + new TargetRemoteAmbiguousError({ + message: "Could not check branches", + suggestion: "Ask for branch access", + status: 403, + }), + ), + expected: { exitCode: 1, code: "forbidden", status: 403, hint: "Ask for branch access" }, + }, + { + name: "ambiguous remote with an invalid token", + cause: Cause.fail( + new TargetRemoteAmbiguousError({ + message: "Could not check branches", + suggestion: "Set SUPABASE_ACCESS_TOKEN", + authFailure: "token", + }), + ), + expected: { + exitCode: 1, + code: "unauthenticated", + status: null, + hint: "Set SUPABASE_ACCESS_TOKEN", + }, + }, { name: "defect", cause: Cause.die(new Error("boom")), From fb3958e872dbfb3dd5c5f9be7c7bd4b494a0d001 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 21:06:29 +0100 Subject: [PATCH 39/45] refactor(cli): drop the unused command surface and duplicate route fields --- .github/workflows/api-package-sync.yml | 2 +- apps/cli/scripts/api-command-derive.ts | 182 +- .../scripts/api-command-derive.unit.test.ts | 90 +- apps/cli/scripts/api-command-reference.ts | 22 +- apps/cli/scripts/generate-api-commands.ts | 28 +- .../command-surface.integration.test.ts | 277 -- .../cli/command-surface/command-surface.ts | 329 -- .../api-command-bindings.integration.test.ts | 81 +- .../commands/api/api-command.annotation.ts | 25 - .../cli/src/commands/api/api-command.model.ts | 8 - .../cli/src/commands/api/generated.schemas.ts | 3414 ----------------- apps/cli/src/commands/api/generated.ts | 28 - apps/cli/src/commands/api/runtime.ts | 2 - turbo.json | 6 +- 14 files changed, 39 insertions(+), 4455 deletions(-) delete mode 100644 apps/cli/src/cli/command-surface/command-surface.integration.test.ts delete mode 100644 apps/cli/src/cli/command-surface/command-surface.ts delete mode 100644 apps/cli/src/commands/api/api-command.annotation.ts delete mode 100644 apps/cli/src/commands/api/generated.schemas.ts diff --git a/.github/workflows/api-package-sync.yml b/.github/workflows/api-package-sync.yml index 74ff75a551..3ac1084ab4 100644 --- a/.github/workflows/api-package-sync.yml +++ b/.github/workflows/api-package-sync.yml @@ -37,7 +37,7 @@ jobs: - name: Check for generated changes id: check run: | - if git diff --ignore-space-at-eol --exit-code --quiet packages/api/src/generated packages/api/scripts/openapi-source.json apps/cli/src/commands/api/generated.ts apps/cli/src/commands/api/generated.schemas.ts apps/cli/src/commands/api/generated.md; then + if git diff --ignore-space-at-eol --exit-code --quiet packages/api/src/generated packages/api/scripts/openapi-source.json apps/cli/src/commands/api/generated.ts apps/cli/src/commands/api/generated.md; then echo "No generated changes detected." echo "has_changes=false" >> "$GITHUB_OUTPUT" else diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index d03221bdf7..c53794c344 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -1,31 +1,28 @@ import type { OperationId } from "@supabase/api/effect"; import { isDeepStrictEqual } from "node:util"; import { Cause, Exit, Predicate, Schema } from "effect"; +import { ROOT_GLOBAL_FLAGS } from "../src/command-internal/global-flags.ts"; import type { ApiNoun, ApiCommandPolicy } from "../src/commands/api/api-command-policy.ts"; import type { ApiCommandBinding, ApiCommandEntry, ApiCommandFlag, - ApiCommandSchemas, ApiCommandWait, ApiPollTarget, } from "../src/commands/api/api-command.model.ts"; type JsonObject = Readonly>; -/** Flags the generated-command runtime adds itself. */ +/** Flags a generated command may not redeclare: the registered globals plus those the runtime adds itself. */ const RESERVED_FLAGS: ReadonlySet = new Set([ + ...ROOT_GLOBAL_FLAGS.map((flag) => flag.id), "body", "file", "remote", "project-ref", - "yes", "dry-run", "wait", "timeout", - "output", - "output-format", - "experimental", "help", ]); @@ -37,7 +34,7 @@ const CREDENTIAL_TOKENS: ReadonlySet = new Set([ "private", ]); -const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const; +const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const; const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u; /** Headers the request builder owns; a spec that declares them gets no flag. */ const UNMAPPED_HEADERS: ReadonlySet = new Set(["authorization", "content-type", "accept"]); @@ -131,14 +128,12 @@ interface DeriveInput { interface DeriveResult { readonly entries: ReadonlyArray; readonly pollTargets: ReadonlyArray; - readonly schemas: Readonly>; readonly problems: ReadonlyArray; } interface Operation { readonly id: string; - readonly method: ApiCommandEntry["method"]; - readonly path: string; + readonly method: (typeof HTTP_METHODS)[number]; readonly node: JsonObject; readonly pathItem: JsonObject; } @@ -235,131 +230,7 @@ const deriveAttributeFields = ( }; }; -const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"; -const DROPPED_KEYWORDS: ReadonlySet = new Set(["discriminator", "xml", "externalDocs"]); -const DATA_KEYWORDS: ReadonlySet = new Set([ - "type", - "format", - "title", - "description", - "default", - "enum", - "const", - "required", - "minimum", - "maximum", - "multipleOf", - "minLength", - "maxLength", - "pattern", - "minItems", - "maxItems", - "uniqueItems", - "minProperties", - "maxProperties", - "readOnly", - "writeOnly", - "deprecated", -]); const SCHEMA_LIST_KEYWORDS = ["allOf", "anyOf", "oneOf"] as const; -const SCHEMA_MAP_KEYWORDS = ["properties", "patternProperties"] as const; - -/** - * Copies an OpenAPI 3.0 schema as JSON Schema 2020-12: every `$ref` is inlined and 3.0-only - * keywords are converted. A keyword with no conversion fails generation. - */ -const toJsonSchema = ( - spec: JsonObject, - node: unknown, - stack: ReadonlyArray, - fail: (reason: string) => void, -): unknown => { - const schema = asRecord(node); - if (schema === undefined) { - fail("schema is not an object"); - return {}; - } - const recurse = (child: unknown) => toJsonSchema(spec, child, stack, fail); - const ref = asString(schema.$ref); - if (ref !== undefined) { - if (stack.includes(ref)) { - fail(`unsupported in this runtime: recursive schema reference ${ref}`); - return {}; - } - const target = lookupRef(spec, ref); - if (target === undefined) { - fail(`schema reference ${ref} does not resolve`); - return {}; - } - return toJsonSchema(spec, target, [...stack, ref], fail); - } - - const out: Record = {}; - for (const [key, value] of Object.entries(schema)) { - if (DROPPED_KEYWORDS.has(key) || key === "nullable" || key === "example") continue; - if (key === "exclusiveMinimum" || key === "exclusiveMaximum") continue; - if (DATA_KEYWORDS.has(key) || key.startsWith("x-")) { - out[key] = value; - } else if (key === "items" || key === "not") { - out[key] = recurse(value); - } else if (key === "additionalProperties") { - out[key] = typeof value === "boolean" ? value : recurse(value); - } else if (SCHEMA_LIST_KEYWORDS.some((keyword) => keyword === key)) { - out[key] = asArray(value).map(recurse); - } else if (SCHEMA_MAP_KEYWORDS.some((keyword) => keyword === key)) { - out[key] = Object.fromEntries( - Object.entries(asRecord(value) ?? {}).map(([name, child]) => [name, recurse(child)]), - ); - } else { - fail( - `unsupported in this runtime: schema keyword "${key}" has no JSON Schema 2020-12 conversion`, - ); - } - } - - for (const [exclusive, bound] of [ - ["exclusiveMinimum", "minimum"], - ["exclusiveMaximum", "maximum"], - ] as const) { - const flag = schema[exclusive]; - if (typeof flag === "number") { - out[exclusive] = flag; - } else if (flag === true) { - if (typeof schema[bound] === "number") { - out[exclusive] = schema[bound]; - delete out[bound]; - } else { - fail(`schema sets ${exclusive}: true without ${bound}`); - } - } else if (flag !== undefined && flag !== false) { - fail(`schema keyword "${exclusive}" has an unsupported value`); - } - } - - if (schema.example !== undefined) { - if (out.examples !== undefined) fail('schema has both "example" and "examples"'); - out.examples = [schema.example]; - } - - if (schema.nullable === true) { - const type = out.type; - if (typeof type === "string") { - out.type = [type, "null"]; - } else if (Array.isArray(type)) { - out.type = [...type, "null"]; - } else { - return { anyOf: [out, { type: "null" }] }; - } - } else if (schema.nullable !== undefined && schema.nullable !== false) { - fail('schema keyword "nullable" has an unsupported value'); - } - return out; -}; - -const withDialect = (schema: unknown): unknown => ({ - $schema: JSON_SCHEMA_DIALECT, - ...asRecord(schema), -}); const escapePointer = (segment: string): string => segment.replaceAll("~", "~0").replaceAll("/", "~1"); @@ -367,7 +238,6 @@ const escapePointer = (segment: string): string => interface SuccessResponse { readonly status: number; readonly kind: "json" | "text" | "empty"; - readonly schema?: unknown; } /** Classifies the 2xx responses; the first one by status code is the one commands report. */ @@ -391,7 +261,7 @@ const classifySuccess = ( if (types.length === 0) { classified.push({ status, kind: "empty" }); } else if (json !== undefined) { - classified.push({ status, kind: "json", schema: asRecord(content[json])?.schema ?? {} }); + classified.push({ status, kind: "json" }); } else if (types.every((type) => type.startsWith("text/") && type !== "text/event-stream")) { classified.push({ status, kind: "text" }); } else { @@ -561,19 +431,18 @@ const successSchema = (spec: JsonObject, operation: Operation): unknown => { return undefined; }; -export const collectOperations = (spec: JsonObject): ReadonlyMap => { +const collectOperations = (spec: JsonObject): ReadonlyMap => { const operations = new Map(); - for (const [path, rawItem] of Object.entries(asRecord(spec.paths) ?? {})) { + for (const rawItem of Object.values(asRecord(spec.paths) ?? {})) { const pathItem = asRecord(rawItem); if (pathItem === undefined) continue; for (const method of HTTP_METHODS) { - const node = asRecord(pathItem[method]); + const node = asRecord(pathItem[method.toLowerCase()]); const id = asString(node?.operationId); if (node === undefined || id === undefined) continue; operations.set(id, { id, - method: method.toUpperCase() as ApiCommandEntry["method"], - path, + method, node, pathItem, }); @@ -783,7 +652,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const metadata = readMetadata(operations, generated, problems); const hidden = new Map(); const entries: Array = []; - const schemas: Record = {}; const commandOwners = new Map(); const groupPaths = new Set(); @@ -932,7 +800,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { } let body: ApiCommandEntry["body"]; - let requestSchema: unknown; const requestBody = asRecord(resolve(spec, operation.node.requestBody)); if (requestBody !== undefined) { const content = asRecord(requestBody.content) ?? {}; @@ -973,7 +840,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const isEnvelope = hasEnvelopeShape && attributeFields !== undefined; const fieldProperties = isEnvelope ? attributeFields.properties : properties; const required = isEnvelope ? attributeFields.required : asArray(bodySchema.required); - requestSchema = asRecord(content["application/json"])?.schema; body = isEnvelope ? { contentType: "application/json", kind: "json-envelope", type: envelopeType } : { contentType: "application/json", kind: "json-object" }; @@ -1086,29 +952,8 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { } const response = classifySuccess(spec, operation, fail); - const schemaSet: ApiCommandSchemas | undefined = - response === undefined - ? undefined - : { - ...(requestSchema === undefined - ? {} - : { - request: { - contentType: "application/json" as const, - schema: withDialect(toJsonSchema(spec, requestSchema, [], fail)), - }, - }), - result: - response.kind === "empty" - ? withDialect({ type: "null" }) - : response.kind === "text" - ? withDialect({ type: "string" }) - : withDialect(toJsonSchema(spec, response.schema, [], fail)), - }; - if (problems.length > failuresBefore || summary === undefined) continue; - if (response === undefined || schemaSet === undefined) continue; - schemas[operationId] = schemaSet; + if (response === undefined) continue; const description = stripStabilityNotice(asString(operation.node.description)); const policy = input.policies?.[operationId]; if (policy?.confirmDescription && (operation.method === "GET" || !description)) { @@ -1119,8 +964,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { command, operationId, definition, - method: operation.method, - apiPath: operation.path, summary, ...(description === undefined ? {} : { description }), readOnly: operation.method === "GET", @@ -1187,7 +1030,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { fail("polling target must return JSON"); continue; } - schemas[operationId] = { result: withDialect(toJsonSchema(spec, response.schema, [], fail)) }; pollTargets.push({ operationId, definition, @@ -1196,7 +1038,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { inspect: inspectId, }); } - return { entries, pollTargets, schemas, problems }; + return { entries, pollTargets, problems }; } function lintWait(input: { diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 8295253432..791177d6a1 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -2,8 +2,6 @@ import { describe, expect, it } from "@effect/vitest"; import type { ApiNoun } from "../src/commands/api/api-command-policy.ts"; import { deriveApiCommands } from "./api-command-derive.ts"; -const DIALECT = "https://json-schema.org/draft/2020-12/schema"; - const jsonResponse = (schema: unknown) => ({ "200": { description: "ok", content: { "application/json": { schema } } }, }); @@ -229,7 +227,7 @@ describe("deriveApiCommands", () => { ); }); - it("binds plain body fields at the body root and inlines referenced schemas", () => { + it("binds plain body fields at the body root", () => { const result = derive({ "create-thing": operation({ ...create, @@ -256,14 +254,9 @@ describe("deriveApiCommands", () => { source: "flag", flag: "display-name", }); - expect(result.schemas["create-thing"]?.result).toEqual({ - $schema: DIALECT, - type: "array", - items: { type: "string" }, - }); }); - it("turns a string enum query parameter into flag choices and an empty response into null", () => { + it("turns a string enum query parameter into flag choices and records an empty response", () => { const result = derive({ "list-things": operation({ ...named("list"), @@ -278,7 +271,6 @@ describe("deriveApiCommands", () => { expect(result.problems).toEqual([]); expect(result.entries[0]?.flags[0]).toMatchObject({ name: "sort", choices: ["asc", "desc"] }); expect(result.entries[0]?.response).toEqual({ status: 204, kind: "empty" }); - expect(result.schemas["list-things"]?.result).toEqual({ $schema: DIALECT, type: "null" }); }); it("derives a plain token-named query parameter as a flag", () => { @@ -431,10 +423,7 @@ describe("deriveApiCommands", () => { { schemas: { Node: node } }, ); - expect(result.problems.join("\n")).not.toContain("secret"); - expect(result.problems).toEqual([ - "create-thing: unsupported in this runtime: recursive schema reference #/components/schemas/Node", - ]); + expect(result.problems).toEqual([]); }); }); @@ -449,49 +438,15 @@ describe("deriveApiCommands", () => { expect(result.problems.join("\n")).toContain('"--wait"'); }); - it("converts OpenAPI 3.0 schema keywords to JSON Schema 2020-12", () => { + it("rejects a body field named like a registered global flag", () => { const result = derive({ - "get-thing": operation({ - ...named("get"), - responses: jsonResponse({ - type: "object", - properties: { - name: { type: "string", nullable: true, example: "a" }, - count: { - type: "integer", - minimum: 0, - exclusiveMinimum: true, - maximum: 9, - exclusiveMaximum: false, - }, - any: { nullable: true, description: "free" }, - }, - discriminator: { propertyName: "name" }, - }), - }), - }); - - expect(result.problems).toEqual([]); - expect(result.schemas["get-thing"]?.result).toEqual({ - $schema: DIALECT, - type: "object", - properties: { - name: { type: ["string", "null"], examples: ["a"] }, - count: { type: "integer", exclusiveMinimum: 0, maximum: 9 }, - any: { anyOf: [{ description: "free" }, { type: "null" }] }, - }, - }); - }); - - it("rejects a schema keyword it cannot convert", () => { - const result = derive({ - "get-thing": operation({ - ...named("get"), - responses: jsonResponse({ type: "string", contentMediaType: "x" }), + "create-thing": operation({ + ...create, + requestBody: envelope({ profile: { type: "string" } }), }), }); - expect(result.problems.join("\n")).toContain('keyword "contentMediaType"'); + expect(result.problems.join("\n")).toContain('"--profile"'); }); it("names a command from the operation's x-operation", () => { @@ -788,7 +743,6 @@ describe("deriveApiCommands", () => { inspect: "get-inspect", }, ]); - expect(result.schemas["get-thing"]?.result).toEqual({ $schema: DIALECT, ...readSchema }); }); it("records a poll-only read once when several mutations link to it", () => { @@ -822,7 +776,6 @@ describe("deriveApiCommands", () => { expect(result.problems).toEqual([]); expect(result.pollTargets).toEqual([]); - expect(result.schemas["get-thing"]).toBeUndefined(); }); it.each([ @@ -1429,35 +1382,8 @@ describe("deriveApiCommands", () => { const ref = { name: "ref", in: "path", required: true, schema: { type: "string" } }; const withParameters = (...parameters: ReadonlyArray) => operation({ ...create, parameters: [ref, ...parameters] }); - const respondWith = (schema: unknown) => - operation({ ...named("get"), responses: jsonResponse(schema) }); it.each([ - [ - "a response schema that is not an object", - { "get-thing": respondWith({ type: "object", properties: { a: 5 } }) }, - "get-thing: schema is not an object", - ], - [ - "a response schema reference that does not resolve", - { "get-thing": respondWith({ $ref: "#/components/schemas/Missing" }) }, - "get-thing: schema reference #/components/schemas/Missing does not resolve", - ], - [ - "an exclusive bound without its bound", - { "get-thing": respondWith({ type: "integer", exclusiveMinimum: true }) }, - "get-thing: schema sets exclusiveMinimum: true without minimum", - ], - [ - "an exclusive bound with an unsupported value", - { "get-thing": respondWith({ type: "integer", exclusiveMaximum: "yes" }) }, - 'get-thing: schema keyword "exclusiveMaximum" has an unsupported value', - ], - [ - "a nullable keyword with an unsupported value", - { "get-thing": respondWith({ type: "string", nullable: "yes" }) }, - 'get-thing: schema keyword "nullable" has an unsupported value', - ], [ "a response status that is not a number", { "create-thing": operation({ ...create, responses: { "2XX": { description: "ok" } } }) }, diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts index 4f4e0f5680..0c3a51bf57 100644 --- a/apps/cli/scripts/api-command-reference.ts +++ b/apps/cli/scripts/api-command-reference.ts @@ -1,3 +1,4 @@ +import { operationDefinitions } from "@supabase/api/effect"; import type { ApiCommandBinding, ApiCommandEntry, @@ -6,22 +7,18 @@ import type { ApiPollTarget, } from "../src/commands/api/api-command.model.ts"; -/** Method and path of an operation, for polled reads that are not generated commands. */ -export interface ApiOperationRoute { - readonly method: string; - readonly path: string; -} - export interface ApiCommandReferenceInput { readonly entries: ReadonlyArray; readonly pollTargets: ReadonlyArray; - /** Route of every poll target, keyed by operation id. */ - readonly pollRoutes: Readonly>; } const code = (text: string): string => `\`${text}\``; -const route = ({ method, path }: ApiOperationRoute): string => code(`${method} ${path}`); +/** The route the runtime sends, read from the typed client's definition of the operation. */ +const route = (operation: Pick): string => { + const { method, path } = operationDefinitions[operation.definition]; + return code(`${method} ${path}`); +}; const cell = (text: string): string => text.replaceAll("|", "\\|"); @@ -104,10 +101,7 @@ const waitSection = ( input: ApiCommandReferenceInput, ): ReadonlyArray => { const publicRead = input.entries.find((candidate) => candidate.operationId === wait.read); - const polled = - publicRead === undefined - ? input.pollRoutes[wait.read] - : { method: publicRead.method, path: publicRead.apiPath }; + const polled = publicRead ?? input.pollTargets.find((target) => target.operationId === wait.read); const polledRoute = polled === undefined ? "unknown route" : route(polled); const params = Object.entries(wait.params); return [ @@ -153,7 +147,7 @@ const commandSection = ( ...(entry.confirmDescription ? ["- Consent: prints the API description before the interactive confirmation."] : []), - `- Request: ${route({ method: entry.method, path: entry.apiPath })} (${code(entry.operationId)}), success ${entry.response.status} ${entry.response.kind}.`, + `- Request: ${route(entry)} (${code(entry.operationId)}), success ${entry.response.status} ${entry.response.kind}.`, ...(body === undefined ? [] : [`- Body: ${body}.`]), ...(argument === undefined ? [] : [`- ${argument}`]), ...(flags.length === 0 diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index 9a76b80593..d4359eeae5 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -9,11 +9,7 @@ import { } from "../src/commands/api/api-command-policy.ts"; import { openApiOperationIdMap } from "@supabase/api/effect"; import { renderApiCommandReference } from "./api-command-reference.ts"; -import { - ApiCommandGenerationError, - collectOperations, - deriveApiCommands, -} from "./api-command-derive.ts"; +import { ApiCommandGenerationError, deriveApiCommands } from "./api-command-derive.ts"; class ApiCommandFormatError extends Data.TaggedError("ApiCommandFormatError")<{ readonly message: string; @@ -93,7 +89,7 @@ const main = Effect.gen(function* () { return yield* new ApiCommandGenerationError({ problems: ["openapi.json is not an object"] }); } - const { entries, pollTargets, schemas, problems } = deriveApiCommands({ + const { entries, pollTargets, problems } = deriveApiCommands({ spec, generated: generatedOperations, policies: commandPolicies, @@ -103,32 +99,14 @@ const main = Effect.gen(function* () { }); if (problems.length > 0) return yield* new ApiCommandGenerationError({ problems }); - const sortedSchemas = Object.fromEntries( - Object.entries(schemas).sort(([left], [right]) => left.localeCompare(right, "en")), - ); - const operations = collectOperations(spec); - const pollRoutes: Record = {}; - for (const target of pollTargets) { - const operation = operations.get(target.operationId); - if (operation === undefined) { - return yield* new ApiCommandGenerationError({ - problems: [`${target.operationId}: polling target has no operation in the spec`], - }); - } - pollRoutes[target.operationId] = { method: operation.method, path: operation.path }; - } const outputs = [ { relative: "src/commands/api/generated.ts", source: `${HEADER}import type { ApiCommandEntry, ApiPollTarget } from "./api-command.model.ts";\n\nexport const apiCommands = ${yield* encodeJson(entries)} as const satisfies readonly ApiCommandEntry[];\n\nexport const apiPollTargets = ${yield* encodeJson(pollTargets)} as const satisfies readonly ApiPollTarget[];\n`, }, - { - relative: "src/commands/api/generated.schemas.ts", - source: `${HEADER}import type { ApiCommandSchemas } from "./api-command.model.ts";\n\nexport const apiCommandSchemas = ${yield* encodeJson(sortedSchemas)} as const satisfies Readonly>;\n`, - }, { relative: "src/commands/api/generated.md", - source: renderApiCommandReference({ entries, pollTargets, pollRoutes }), + source: renderApiCommandReference({ entries, pollTargets }), }, ]; diff --git a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts b/apps/cli/src/cli/command-surface/command-surface.integration.test.ts deleted file mode 100644 index 894d49f931..0000000000 --- a/apps/cli/src/cli/command-surface/command-surface.integration.test.ts +++ /dev/null @@ -1,277 +0,0 @@ -import { describe, expect, it } from "@effect/vitest"; -import { Effect, Schema } from "effect"; - -import { commandSurface, commandSurfaceEntry, walkCommandSurface } from "./command-surface.ts"; -import { apiCommands } from "../../commands/api/generated.ts"; -import { rootCommandForFeatures } from "../root.ts"; - -const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); -const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); - -const surface = Effect.runPromise(commandSurface()); - -const warehouseVariant = Effect.promise(() => surface).pipe( - Effect.map(({ variants }) => { - const variant = variants["warehouse"]; - if (variant === undefined) throw new Error("the surface has no warehouse variant"); - return variant; - }), -); - -const titlesOf = (result: unknown): ReadonlyArray => - typeof result === "object" && result !== null && "anyOf" in result && Array.isArray(result.anyOf) - ? result.anyOf.map((branch) => - typeof branch === "object" && branch !== null && "title" in branch ? branch.title : null, - ) - : []; - -/** Source files a bundle of `entrypoint` pulls in, following relative imports only. */ -const bundledInputs = (entrypoint: string) => - Effect.promise(() => - Bun.build({ - entrypoints: [entrypoint], - target: "bun", - packages: "external", - metafile: true, - }), - ).pipe( - Effect.map((built) => { - expect(built.success).toBe(true); - return Object.keys(built.metafile?.inputs ?? {}); - }), - ); - -describe("command surface", () => { - it.effect("keeps warehouse commands out of the default surface", () => - Effect.gen(function* () { - const { commands } = yield* Effect.promise(() => surface); - expect(Object.keys(commands).filter((path) => path.startsWith("warehouse"))).toEqual([]); - expect(Object.keys(commands)).toContain("projects list"); - }), - ); - - it.effect("lists exactly the warehouse entries the feature adds", () => - Effect.gen(function* () { - const warehouse = yield* warehouseVariant; - expect(Object.keys(warehouse)).toEqual([ - "warehouse", - "warehouse connection", - "warehouse disable", - "warehouse enable", - "warehouse inspect", - "warehouse inspect capacity", - "warehouse inspect query-stats", - "warehouse replication", - "warehouse replication add", - "warehouse replication remove", - "warehouse replication resync", - "warehouse status", - "warehouse tables", - "warehouse tables get", - "warehouse tables layout", - "warehouse tables layout get", - "warehouse tables layout update", - "warehouse tables list", - "warehouse teardowns", - "warehouse teardowns get", - ]); - }), - ); - - it.effect("extracts one command from any mounted root, keyed like the full walk", () => - Effect.gen(function* () { - const root = rootCommandForFeatures({ apiFeatures: ["warehouse"] }); - const walked = yield* walkCommandSurface(root); - const single = yield* commandSurfaceEntry(root, ["warehouse", "status"]); - expect(walked["warehouse status"]).toStrictEqual(single); - expect(Object.keys(walked)).toEqual(Object.keys(walked).toSorted()); - }), - ); - - it.effect( - "mounts metrics inspection under Warehouse and preserves standalone inspect commands", - () => - Effect.gen(function* () { - const { commands } = yield* Effect.promise(() => surface); - expect(commands).not.toHaveProperty("warehouse inspect query-stats"); - const enabled = yield* walkCommandSurface( - rootCommandForFeatures({ apiFeatures: ["warehouse"] }), - ); - for (const path of ["inspect", "inspect db", "inspect report", "inspect db table-stats"]) { - expect(enabled[path]).toEqual(commands[path]); - } - expect(enabled).not.toHaveProperty("inspect warehouse"); - for (const command of ["capacity", "query-stats"]) { - const entry = enabled[`warehouse inspect ${command}`]; - expect(entry).toMatchObject({ - stage: { status: "experimental", feature: "warehouse" }, - target: { group: "hosted", consent: "none" }, - api: { operationId: `v2-get-warehouse-${command}` }, - }); - expect(Object.keys(entry?.flags ?? {})).toEqual( - expect.arrayContaining(["since", "from", "to", "attributes", "interval", "remote"]), - ); - expect(entry?.flags).not.toHaveProperty("wait"); - } - }), - ); - - it.effect("describes local request preview results for every replication command", () => - Effect.gen(function* () { - const warehouse = yield* warehouseVariant; - for (const action of ["add", "remove", "resync"]) { - const command = warehouse[`warehouse replication ${action}`]; - expect(command?.flags).toHaveProperty("dry-run"); - expect(titlesOf(command?.result)).toEqual(["response", "dryRun"]); - } - }), - ); - - it.effect("describes layout updates without unsupported backend workflow flags", () => - Effect.gen(function* () { - const warehouse = yield* warehouseVariant; - const update = warehouse["warehouse tables layout update"]; - expect(update).toMatchObject({ - path: ["warehouse", "tables", "layout", "update"], - stage: { status: "experimental", feature: "warehouse" }, - errors: "standard", - api: { - operationId: "v2-update-warehouse-table-layout", - request: { contentType: "application/json" }, - }, - }); - expect(Object.keys(update?.flags ?? {})).toEqual( - expect.arrayContaining(["body", "file", "dry-run", "reset-table"]), - ); - for (const flag of ["wait", "timeout"]) { - expect(update?.flags).not.toHaveProperty(flag); - } - expect(titlesOf(update?.result)).toEqual(["response", "dryRun"]); - }), - ); - - it.effect( - "describes a generated command from its operation and schemas; a body flag is not required on the command line", - () => - Effect.gen(function* () { - const warehouse = yield* warehouseVariant; - const enable = warehouse["warehouse enable"]; - expect(enable).toMatchObject({ - path: ["warehouse", "enable"], - target: { group: "hosted", consent: "no" }, - errors: "standard", - stage: { status: "experimental", feature: "warehouse" }, - api: { operationId: "v2-enable-warehouse", request: { contentType: "application/json" } }, - }); - expect(titlesOf(enable?.result)).toEqual(["response", "waited", "dryRun"]); - expect(enable?.flags["schema"]).toMatchObject({ required: false }); - expect(enable?.flags["table"]).toMatchObject({ - type: "string", - variadic: true, - required: false, - }); - expect(enable?.flags["dry-run"]).toMatchObject({ type: "boolean", default: false }); - expect(Object.keys(enable?.flags ?? {})).not.toContain("output"); - }), - ); - - it.effect("reports every generated command with its operation and experimental stage", () => - Effect.gen(function* () { - const warehouse = yield* warehouseVariant; - for (const entry of apiCommands) { - expect(warehouse[entry.command.join(" ")]).toMatchObject({ - stage: { status: "experimental", feature: entry.feature }, - api: { operationId: entry.operationId }, - }); - } - }), - ); - - it.effect("describes retained-data disable and its linked cleanup read", () => - Effect.gen(function* () { - const warehouse = yield* warehouseVariant; - const disable = warehouse["warehouse disable"]; - expect(disable).toMatchObject({ - target: { group: "hosted", consent: "no" }, - stage: { status: "experimental", feature: "warehouse" }, - errors: "standard", - api: { operationId: "v2-disable-warehouse" }, - }); - expect(disable?.flags["delete-data"]).toMatchObject({ type: "boolean", required: false }); - expect(disable?.flags["wait"]).toMatchObject({ type: "boolean" }); - expect(disable?.flags["timeout"]).toMatchObject({ type: "string" }); - expect(titlesOf(disable?.result)).toEqual(["response", "waited", "dryRun"]); - expect(warehouse["warehouse teardowns get"]?.flags["operation-id"]).toMatchObject({ - required: false, - }); - }), - ); - - it.effect("emits global flags once at the top level, not per command", () => - Effect.gen(function* () { - const { globalFlags, commands } = yield* Effect.promise(() => surface); - expect(globalFlags["yes"]).toMatchObject({ type: "boolean", default: false }); - expect(globalFlags["output-format"]).toMatchObject({ type: "choice" }); - expect(globalFlags["output-format"]?.choices).toContain("json"); - expect(Object.keys(commands["projects list"]?.flags ?? {})).not.toContain("yes"); - }), - ); - - it.effect("separates consolidated status from the identity-bound setup waiter", () => - Effect.gen(function* () { - const warehouse = yield* warehouseVariant; - const status = warehouse["warehouse status"]; - expect(status).toMatchObject({ - api: { operationId: "v2-get-warehouse-status" }, - target: { group: "hosted", consent: "none" }, - stage: { status: "experimental", feature: "warehouse" }, - }); - expect(status?.flags).not.toHaveProperty("inspect-fdw"); - expect(status?.flags).not.toHaveProperty("selection-id"); - expect(status?.flags).not.toHaveProperty("wait"); - expect(status?.flags).not.toHaveProperty("timeout"); - expect(warehouse).not.toHaveProperty("warehouse setups"); - expect(warehouse).not.toHaveProperty("warehouse setups get"); - expect(warehouse["warehouse enable"]?.flags).toMatchObject({ - wait: { type: "boolean" }, - timeout: { type: "string" }, - }); - }), - ); - - it.effect("declares a waited result only for a command that waits on another read", () => - Effect.gen(function* () { - const warehouse = yield* warehouseVariant; - expect(titlesOf(warehouse["warehouse status"]?.result)).toEqual(["response", "dryRun"]); - }), - ); - - it.effect("reports a hand-written command with the legacy error contract and no result", () => - Effect.gen(function* () { - const { commands } = yield* Effect.promise(() => surface); - expect(commands["projects list"]).toMatchObject({ - errors: "legacy", - result: "undeclared", - target: { group: "account" }, - }); - expect(commands["projects list"]).not.toHaveProperty("api"); - }), - ); - - it.effect("serializes to JSON and back unchanged", () => - Effect.gen(function* () { - const built = yield* Effect.promise(() => surface); - expect(decodeJson(encodeJson(built))).toStrictEqual(built); - }), - ); - - it.effect("loads the generated schemas only through the surface extraction", () => - Effect.gen(function* () { - const extraction = yield* bundledInputs("src/cli/command-surface/command-surface.ts"); - const runtime = yield* bundledInputs("src/main.ts"); - expect(extraction).toContain("src/commands/api/generated.schemas.ts"); - expect(runtime).not.toContain("src/commands/api/generated.schemas.ts"); - expect(runtime).not.toContain("src/cli/command-surface/command-surface.ts"); - }), - ); -}); diff --git a/apps/cli/src/cli/command-surface/command-surface.ts b/apps/cli/src/cli/command-surface/command-surface.ts deleted file mode 100644 index 0842d323f5..0000000000 --- a/apps/cli/src/cli/command-surface/command-surface.ts +++ /dev/null @@ -1,329 +0,0 @@ -import { Effect, Option, Predicate, Schema } from "effect"; -import { Command, CommandSpec } from "effect/cli"; - -import { readApiCommand } from "../../commands/api/api-command.annotation.ts"; -import type { - ApiCommandBinding, - ApiCommandEntry, - ApiCommandSchemas, -} from "../../commands/api/api-command.model.ts"; -import { nouns } from "../../commands/api/api-command-policy.ts"; -import { apiCommands } from "../../commands/api/generated.ts"; -import { rootCommandForFeatures } from "../root.ts"; -import { flattenSubcommands } from "../../docs/docs-introspection.ts"; -import { readCommandErrorsContract } from "../../command-internal/command-errors/command-errors.annotation.ts"; -import { readPermissions } from "../../command-internal/command-permissions/command-permissions.annotation.ts"; -import type { CommandPermissions } from "../../command-internal/command-permissions/model.ts"; -import { readTargetPolicy } from "../../command-internal/target/target-policy.ts"; -import type { TargetGroup } from "../../command-internal/target/target-policy.ts"; - -type JsonSchema = Readonly>; - -/** A positional argument as the parser accepts it. */ -interface SurfaceArgument { - readonly name: string; - readonly type: string; - readonly choices: readonly string[] | null; - readonly required: boolean; - readonly variadic: boolean; -} - -/** - * A flag as the parser accepts it, except that a generated API flag is `required` and `sensitive` - * as its operation declares; `env` is `null` because the parser carries no env name. - */ -interface SurfaceFlag { - readonly name: string; - readonly aliases: readonly string[]; - readonly type: string; - readonly choices: readonly string[] | null; - readonly required: boolean; - readonly default: unknown; - readonly env: string | null; - readonly negatable: boolean; - readonly variadic: boolean; - readonly hidden: boolean; - readonly sensitive: boolean; -} - -/** What a generated command declares about the Management API operation it calls. */ -interface SurfaceApi { - readonly operationId: string; - /** Request body content type and JSON Schema, `null` when the operation sends none. */ - readonly request: { readonly contentType: string; readonly schema: unknown } | null; - readonly bindings: readonly ApiCommandBinding[]; -} - -/** - * How far a command's contract has settled. An experimental command is reachable only while its - * `feature` is enabled: the root mounts the command's family only then. - */ -interface CommandStage { - readonly status: "experimental"; - readonly feature: string; -} - -/** One command or group of the mounted tree. Optional fields are omitted when the command declares nothing. */ -interface CommandSurfaceEntry { - readonly path: readonly string[]; - readonly aliases: readonly string[]; - readonly summary: string; - readonly unlisted: boolean; - readonly stage?: CommandStage; - readonly target?: { readonly group: TargetGroup; readonly consent: "none" | "no" | "yes" }; - readonly permissions?: CommandPermissions; - readonly arguments: readonly SurfaceArgument[]; - readonly flags: Readonly>; - /** `"undeclared"` for a hand-written command, else a JSON Schema `anyOf` of titled branches. */ - readonly result: "undeclared" | JsonSchema; - readonly errors: "standard" | "legacy"; - readonly api?: SurfaceApi; -} - -/** The default tree plus the entries each feature variant adds or changes. */ -interface CommandSurface { - readonly globalFlags: Readonly>; - readonly commands: Readonly>; - readonly variants: Readonly>>>; -} - -type CommandRoot = Command.Command.Any; - -const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); - -const generatedEntries: readonly ApiCommandEntry[] = apiCommands; - -const dryRunSchema: JsonSchema = { - title: "dryRun", - type: "object", - properties: { - method: { type: "string" }, - path: { type: "string" }, - query: { type: "object" }, - headers: { type: "object" }, - body: {}, - }, - required: ["method", "path", "query", "headers", "body"], - additionalProperties: false, -}; - -// The schema table is the heavy generated module; importing it on demand keeps it out of the -// command runtime's module graph. -const loadSchemaTable = Effect.fn("CommandSurface.loadSchemas")(function* () { - const loaded = yield* Effect.promise(() => import("../../commands/api/generated.schemas.ts")); - const table: Readonly> = loaded.apiCommandSchemas; - return table; -}); - -const titled = (schema: unknown, title: string): JsonSchema => - Predicate.isObject(schema) ? { ...schema, title } : { title, allOf: [schema] }; - -const jsonOf = (value: unknown): unknown => - Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value) - ? value - : Array.isArray(value) - ? value.map(jsonOf) - : null; - -const choicesOf = (type: CommandSpec.Type): readonly string[] | null => - type._tag === "Choice" ? type.values : null; - -const defaultOf = (fallbacks: ReadonlyArray): unknown => { - const found = fallbacks.find((fallback) => fallback._tag === "Default"); - return found === undefined ? null : jsonOf(found.value); -}; - -const findCommand = (root: CommandRoot, path: readonly string[]): Option.Option => - path.reduce>( - (current, segment) => - Option.flatMap(current, (command) => - Option.fromUndefinedOr(flattenSubcommands(command).find((child) => child.name === segment)), - ), - Option.some(root), - ); - -const collectPaths = ( - command: CommandRoot, - prefix: readonly string[], -): ReadonlyArray => - flattenSubcommands(command).flatMap((child) => { - const path = [...prefix, child.name]; - return [path, ...collectPaths(child, path)]; - }); - -const sortedRecord = ( - entries: ReadonlyArray, -): Readonly> => - Object.fromEntries([...entries].toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))); - -/** What a generated flag adds to its parsed definition. */ -interface ApiFlagFacts { - readonly required: boolean; - readonly sensitive: boolean; -} - -const noApiFlags: ReadonlyMap = new Map(); - -/** - * A body flag's requirement sits on the request body, which `--body` or `--file` can supply - * instead; a query or header flag has no other source, so it is required on the command line. - */ -const apiFlagFacts = (entry: ApiCommandEntry): ReadonlyMap => - new Map( - entry.flags.map((flag) => { - const bodyBound = entry.bindings.some( - (binding) => binding.location === "body" && binding.flag === flag.name, - ); - return [ - flag.name, - { - required: flag.required && !bodyBound, - sensitive: flag.sensitive === true, - }, - ]; - }), - ); - -const surfaceFlag = ( - flag: CommandSpec.Flag, - apiFlags: ReadonlyMap, -): readonly [string, SurfaceFlag] => [ - flag.name, - { - name: flag.name, - aliases: flag.aliases, - type: flag.typeName, - choices: choicesOf(flag.type), - required: flag.required || apiFlags.get(flag.name)?.required === true, - default: defaultOf(flag.fallbacks), - env: null, - negatable: flag.negation !== undefined, - variadic: flag.variadic !== undefined, - hidden: flag.hidden, - sensitive: flag.type._tag === "Redacted" || apiFlags.get(flag.name)?.sensitive === true, - }, -]; - -/** The Global-scope flags every command accepts, keyed by name in sorted order. */ -const walkGlobalFlags = (root: CommandRoot) => { - const spec = CommandSpec.resolve(root, [root.name]); - return sortedRecord( - Option.isNone(spec) - ? [] - : spec.value.flags - .filter((flag) => flag.scope._tag === "Global") - .map((flag) => surfaceFlag(flag, noApiFlags)), - ); -}; - -const apiSurface = Effect.fn("CommandSurface.api")(function* (command: CommandRoot) { - const descriptor = readApiCommand(command); - if (Option.isNone(descriptor)) return Option.none(); - const { operationId } = descriptor.value; - const generated = generatedEntries.find((entry) => entry.operationId === operationId); - if (generated === undefined) { - return yield* Effect.die(`no generated command declares operation "${operationId}"`); - } - const table = yield* loadSchemaTable(); - const schemas = table[operationId]; - if (schemas === undefined) { - return yield* Effect.die(`no generated schemas for operation "${operationId}"`); - } - const waitRead = generated.wait?.read === operationId ? undefined : generated.wait?.read; - const waitSchemas = waitRead === undefined ? undefined : table[waitRead]; - if (waitRead !== undefined && waitSchemas === undefined) { - return yield* Effect.die(`no generated schemas for operation "${waitRead}"`); - } - const branches = [ - titled(schemas.result, "response"), - ...(waitSchemas === undefined ? [] : [titled(waitSchemas.result, "waited")]), - dryRunSchema, - ]; - return Option.some({ - api: { - operationId, - request: - schemas.request === undefined - ? null - : { contentType: schemas.request.contentType, schema: schemas.request.schema }, - bindings: generated.bindings, - } satisfies SurfaceApi, - result: { anyOf: branches } satisfies JsonSchema, - stage: { status: "experimental", feature: generated.feature } satisfies CommandStage, - apiFlags: apiFlagFacts(generated), - }); -}); - -/** Extracts the surface of the command at `path` (root name omitted) from the mounted tree `root`. */ -export const commandSurfaceEntry = Effect.fn("CommandSurface.entry")(function* ( - root: CommandRoot, - path: readonly string[], -) { - const command = findCommand(root, path); - const spec = CommandSpec.resolve(root, [root.name, ...path]); - if (Option.isNone(command) || Option.isNone(spec)) { - return yield* Effect.die(`unknown command path "${path.join(" ")}"`); - } - const api = yield* apiSurface(command.value); - const apiFlags = Option.match(api, { - onNone: () => noApiFlags, - onSome: (found) => found.apiFlags, - }); - const target = readTargetPolicy(command.value); - const permissions = readPermissions(command.value); - const flags = spec.value.flags - .filter((flag) => flag.scope._tag !== "Global") - .map((flag) => surfaceFlag(flag, apiFlags)); - const entry: CommandSurfaceEntry = { - path, - aliases: spec.value.alias === undefined ? [] : [spec.value.alias], - summary: spec.value.shortDescription ?? spec.value.description ?? "", - unlisted: spec.value.unlisted, - ...(Option.isSome(api) ? { stage: api.value.stage } : {}), - ...(Option.isSome(target) - ? { target: { group: target.value.group, consent: target.value.consent } } - : {}), - ...(Option.isSome(permissions) ? { permissions: permissions.value } : {}), - arguments: spec.value.arguments.map((argument) => ({ - name: argument.name, - type: argument.typeName, - choices: choicesOf(argument.type), - required: argument.required, - variadic: argument.variadic !== undefined, - })), - flags: sortedRecord(flags), - result: Option.isSome(api) ? api.value.result : "undeclared", - errors: readCommandErrorsContract(command.value), - ...(Option.isSome(api) ? { api: api.value.api } : {}), - }; - return entry; -}); - -/** Extracts every command and group of `root`, keyed by space-joined path in sorted order. */ -export const walkCommandSurface = Effect.fn("CommandSurface.walk")(function* (root: CommandRoot) { - const paths = collectPaths(root, []); - const entries = yield* Effect.forEach(paths, (path) => - Effect.map(commandSurfaceEntry(root, path), (entry) => [path.join(" "), entry] as const), - ); - return sortedRecord(entries); -}); - -/** The default command surface and, per feature, the entries that differ when the feature is on. */ -export const commandSurface = Effect.fn("CommandSurface.build")(function* () { - const base = yield* walkCommandSurface(rootCommandForFeatures()); - const features = [...new Set(Object.values(nouns).map(({ feature }) => feature))]; - const variants = yield* Effect.forEach(features, (feature) => - Effect.gen(function* () { - const walked = yield* walkCommandSurface(rootCommandForFeatures({ apiFeatures: [feature] })); - const differing = Object.entries(walked).filter( - ([key, entry]) => key in base === false || encodeJson(base[key]) !== encodeJson(entry), - ); - return [feature, sortedRecord(differing)] as const; - }), - ); - return { - globalFlags: walkGlobalFlags(rootCommandForFeatures()), - commands: base, - variants: sortedRecord(variants), - } satisfies CommandSurface; -}); diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index a1b425ff40..280b2858cf 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -4,7 +4,6 @@ import openApiSpec from "@supabase/api/openapi.json"; import { Effect, Layer, Predicate, Schema, Stdio } from "effect"; import { CliOutput, Command } from "effect/cli"; -import { commandSurface } from "../../cli/command-surface/command-surface.ts"; import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; import { @@ -25,7 +24,6 @@ import { } from "../../../tests/helpers/mocks.ts"; import type { ApiCommandEntry } from "./api-command.model.ts"; import { apiCommands } from "./generated.ts"; -import { apiCommandSchemas } from "./generated.schemas.ts"; import { withApiCommands } from "./runtime.ts"; type Json = Readonly>; @@ -54,7 +52,6 @@ interface SpecOperation { readonly parameters: ReadonlyArray; readonly requestSchema: Json | undefined; readonly responseStatus: number; - readonly responseSchema: Json; } const operationOf = (operationId: string): SpecOperation => { @@ -74,46 +71,12 @@ const operationOf = (operationId: string): SpecOperation => { parameters: asList(operation["parameters"]).map(asRecord), requestSchema: request === undefined ? undefined : resolveRef(request), responseStatus: Number(success[0]), - responseSchema: resolveRef(json(asRecord(success[1])["content"])), }; } } throw new Error(`${operationId} is not in openapi.json`); }; -/** - * The JSON Schema types of a node, with OpenAPI 3.0 `nullable` and a `null` union branch folded in - * as a `null` type. - */ -const typesOf = (node: Json): ReadonlyArray => { - const declared = node["type"]; - const types = (Array.isArray(declared) ? declared : declared === undefined ? [] : [declared]).map( - String, - ); - const nullable = - node["nullable"] === true || - asList(node["anyOf"]).some((branch) => asRecord(branch)["type"] === "null"); - return (nullable ? [...types, "null"] : types) - .filter((type, index, all) => all.indexOf(type) === index) - .toSorted((a, b) => a.localeCompare(b)); -}; - -/** A structural fingerprint of a schema that ignores descriptions, examples and titles. */ -const shapeOf = (schema: unknown): unknown => { - const node = resolveRef(schema); - return { - types: typesOf(node), - enum: node["enum"] ?? null, - properties: Object.fromEntries( - Object.entries(asRecord(node["properties"])).map(([key, value]) => [key, shapeOf(value)]), - ), - required: asList(node["required"]) - .map(String) - .toSorted((a, b) => a.localeCompare(b)), - items: node["items"] === undefined ? null : shapeOf(node["items"]), - }; -}; - const PATTERN_SAMPLES: Readonly> = { "^[1-9]\\d*(s|m|h|d)$": "30m", "^[a-f0-9]{64}$": "ab".repeat(32), @@ -347,28 +310,12 @@ const send = (path: ReadonlyArray, argv: ReadonlyArray, status: ); }; -const generated: readonly ApiCommandEntry[] = apiCommands; - -const surface = await Effect.runPromise(commandSurface()); -const rows = [ - ...Object.values(surface.commands), - ...Object.values(surface.variants["warehouse"] ?? {}), -] - .flatMap((entry) => (entry.api === undefined ? [] : [{ ...entry, api: entry.api }])) - .toSorted((a, b) => a.api.operationId.localeCompare(b.api.operationId)); - describe("generated command bindings", () => { - it("covers every generated command", () => { - expect(rows.map((row) => row.api.operationId)).toEqual( - apiCommands.map((entry) => entry.operationId).toSorted(), - ); - }); - - for (const row of rows) { - const { operationId } = row.api; + for (const entry of apiCommands) { + const { operationId } = entry; const operation = operationOf(operationId); // The API rejects `since` combined with `from`/`to`; the relative form is the one sent here. - const inputs = inputsOf(operationId, operation, row.api.bindings).filter( + const inputs = inputsOf(operationId, operation, entry.bindings).filter( (input, _, all) => input.location !== "query" || (input.field !== "from" && input.field !== "to") || @@ -381,11 +328,11 @@ describe("generated command bindings", () => { operation.template.replace("{ref}", VALID_REF), ); - describe(row.path.join(" "), () => { + describe(entry.command.join(" "), () => { it.effect("sends every input at its binding", () => Effect.gen(function* () { const requests = yield* send( - row.path, + entry.command, [...positionals.map(({ sample }) => sample), ...argvOf(inputs)], operation.responseStatus, ); @@ -404,7 +351,7 @@ describe("generated command bindings", () => { it.effect("sends only the inputs the spec requires when no other flag is given", () => Effect.gen(function* () { const requests = yield* send( - row.path, + entry.command, [...positionals.map(({ sample }) => sample), ...argvOf(required)], operation.responseStatus, ); @@ -417,22 +364,6 @@ describe("generated command bindings", () => { }), ); } - - it("declares the operation's success response as the response result", () => { - expect(Object.keys(apiCommandSchemas)).toContain(operationId); - const branches = asList(asRecord(row.result)["anyOf"]).map(asRecord); - expect(shapeOf(branches.find((branch) => branch["title"] === "response"))).toEqual( - shapeOf(operation.responseSchema), - ); - const waitRead = generated.find((entry) => entry.operationId === operationId)?.wait?.read; - const waited = branches.find((branch) => branch["title"] === "waited"); - if (waitRead === undefined || waitRead === operationId) { - expect(waited).toBeUndefined(); - return; - } - expect(Object.keys(apiCommandSchemas)).toContain(waitRead); - expect(shapeOf(waited)).toEqual(shapeOf(operationOf(waitRead).responseSchema)); - }); }); } }); diff --git a/apps/cli/src/commands/api/api-command.annotation.ts b/apps/cli/src/commands/api/api-command.annotation.ts deleted file mode 100644 index 10e4b06e2c..0000000000 --- a/apps/cli/src/commands/api/api-command.annotation.ts +++ /dev/null @@ -1,25 +0,0 @@ -import { Context, Option } from "effect"; -import { Command } from "effect/cli"; - -/** What a generated command declares about its API operation; tooling reads it from `Command.annotations`. */ -export interface ApiCommandDescriptor { - readonly operationId: string; -} - -/** Context key under which a generated command's descriptor is stored in `Command.annotations`. */ -export class ApiCommandAnnotation extends Context.Service< - ApiCommandAnnotation, - ApiCommandDescriptor ->()("supabase/ApiCommandAnnotation") {} - -/** Marks a command as generated from the Management API operation `descriptor` names. */ -export const withApiCommand = - (descriptor: ApiCommandDescriptor) => - ( - self: Command.Command, - ) => - self.pipe(Command.annotate(ApiCommandAnnotation, descriptor)); - -/** The descriptor of a generated command, or `None` for a hand-written one. */ -export const readApiCommand = (command: Command.Command.Any): Option.Option => - Context.getOption(command.annotations, ApiCommandAnnotation); diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index e8c5b32b78..91d2c89b12 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -78,8 +78,6 @@ export interface ApiCommandEntry { readonly operationId: string; /** Key of the operation in the typed client's `operationDefinitions`. */ readonly definition: OperationId; - readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; - readonly apiPath: string; readonly summary: string; readonly description?: string; readonly readOnly: boolean; @@ -120,9 +118,3 @@ export interface ApiPollTarget extends ApiPollRead { /** Operation id of the generated command that inspects the state after a failed or timed-out wait. */ readonly inspect: string; } - -/** OpenAPI schemas of one operation with every `$ref` inlined. */ -export interface ApiCommandSchemas { - readonly request?: { readonly contentType: "application/json"; readonly schema: unknown }; - readonly result: unknown; -} diff --git a/apps/cli/src/commands/api/generated.schemas.ts b/apps/cli/src/commands/api/generated.schemas.ts deleted file mode 100644 index 6cf2e2b16a..0000000000 --- a/apps/cli/src/commands/api/generated.schemas.ts +++ /dev/null @@ -1,3414 +0,0 @@ -// Generated by scripts/generate-api-commands.ts. Do not edit. -import type { ApiCommandSchemas } from "./api-command.model.ts"; - -export const apiCommandSchemas = { - "v2-add-warehouse-replication": { - request: { - contentType: "application/json", - schema: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - additionalProperties: false, - properties: { - schema: { - description: - "Literal source PostgreSQL schema. Omit table to select its current tables.", - minLength: 1, - type: "string", - }, - table: { - description: "Literal source table name. Omit to select the schema.", - minLength: 1, - type: "string", - }, - }, - required: ["schema"], - type: "object", - }, - type: { - description: "Resource type.", - enum: ["warehouse_replication_change"], - type: "string", - }, - }, - required: ["attributes", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - properties: { - action: { - enum: ["add", "remove"], - type: "string", - }, - affected_tables: { - items: { - properties: { - id: { - maximum: 4294967295, - type: "integer", - exclusiveMinimum: 0, - }, - name: { - minLength: 1, - type: "string", - }, - schema: { - minLength: 1, - type: "string", - }, - }, - required: ["id", "name", "schema"], - type: "object", - }, - type: "array", - }, - application_status: { - description: - "Immediate orchestration result. Restart acceptance does not establish runtime application or copy completion.", - enum: ["configured", "restart_requested", "unchanged"], - type: "string", - }, - changed: { - type: "boolean", - }, - includes_future_tables: { - enum: [false], - type: "boolean", - }, - pipeline_id: { - type: "string", - }, - pipeline_status_before: { - type: "string", - }, - selected_table_count: { - maximum: 9007199254740991, - minimum: 0, - type: "integer", - }, - source_data_preserved: { - enum: [true], - type: "boolean", - }, - tables: { - description: - "Resulting configured selection, with best-effort replication observations.", - items: { - properties: { - copy_name: { - type: "string", - }, - id: { - maximum: 4294967295, - type: "integer", - exclusiveMinimum: 0, - }, - lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - name: { - minLength: 1, - type: "string", - }, - replication_state: { - type: ["string", "null"], - }, - schema: { - minLength: 1, - type: "string", - }, - state: { - description: - "Last observed table state; null when unavailable. Does not establish completion of this request.", - enum: ["error", "live", null, "syncing"], - type: ["string", "null"], - }, - }, - required: [ - "copy_name", - "id", - "lag_ms", - "name", - "replication_state", - "schema", - "state", - ], - type: "object", - }, - type: "array", - }, - unchanged_tables: { - items: { - properties: { - id: { - maximum: 4294967295, - type: "integer", - exclusiveMinimum: 0, - }, - name: { - minLength: 1, - type: "string", - }, - schema: { - minLength: 1, - type: "string", - }, - }, - required: ["id", "name", "schema"], - type: "object", - }, - type: "array", - }, - warehouse_data_retained: { - enum: [true], - type: "boolean", - }, - warehouse_enabled: { - enum: [true], - type: "boolean", - }, - }, - required: [ - "action", - "affected_tables", - "application_status", - "changed", - "includes_future_tables", - "pipeline_id", - "pipeline_status_before", - "selected_table_count", - "source_data_preserved", - "tables", - "unchanged_tables", - "warehouse_data_retained", - "warehouse_enabled", - ], - type: "object", - }, - id: { - type: "string", - }, - type: { - description: "Resource type.", - enum: ["warehouse_replication_change"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-disable-warehouse": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - type: "object", - properties: { - data: { - type: "object", - properties: { - type: { - type: "string", - description: "Resource type.", - enum: ["warehouse_teardown"], - }, - id: { - type: "string", - format: "uuid", - pattern: - "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", - }, - attributes: { - type: "object", - properties: { - lifecycle_status: { - type: "string", - enum: ["disabling", "disabled", "deletion_failed"], - }, - delete_data: { - type: "boolean", - description: - "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", - }, - updated_at: { - type: "string", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", - }, - cleanup_error: { - description: - "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", - type: ["string", "null"], - }, - }, - required: ["lifecycle_status", "delete_data", "updated_at", "cleanup_error"], - }, - }, - required: ["type", "id", "attributes"], - }, - }, - required: ["data"], - }, - }, - "v2-enable-warehouse": { - request: { - contentType: "application/json", - schema: { - $schema: "https://json-schema.org/draft/2020-12/schema", - type: "object", - properties: { - data: { - type: "object", - properties: { - type: { - type: "string", - description: "Resource type.", - enum: ["warehouse_setup"], - }, - attributes: { - type: "object", - properties: { - warehouse_region: { - description: - "Optional Warehouse compute region, independent of the source and catalog regions. Defaults to the existing assignment, or ap-southeast-1 in staging and eu-west-1 in production for a new assignment. DNS routing requires a registered cluster in that environment. Unsupported regions and changes to an existing assignment are rejected. Ignored when targets is empty.", - type: "string", - minLength: 1, - examples: ["ap-southeast-1"], - }, - destination_project_ref: { - description: - "Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. Defaults to this project on first setup and to the configured destination on later requests. The destination must be active and healthy, and another project requires SQL and Storage admin write permissions. An existing destination cannot be changed through setup. Ignored when targets is empty.", - type: "string", - minLength: 20, - maxLength: 20, - pattern: "^[a-z]+$", - examples: ["zyxwvutsrqponmlkjihg"], - }, - install_fdw: { - description: - "Whether to configure and install the Warehouse FDW in the project database. Defaults to false. Ignored when targets is empty.", - type: "boolean", - examples: [false], - }, - schema: { - type: "string", - minLength: 1, - description: - "Source PostgreSQL schema. Without tables, selects its currently eligible tables only.", - examples: ["public"], - }, - tables: { - description: - "Table names in schema. Omit to select the currently eligible tables in that schema.", - "x-ignore-array-items-must-be-objects": true, - minItems: 1, - type: "array", - items: { - type: "string", - minLength: 1, - }, - }, - }, - required: ["schema"], - additionalProperties: false, - }, - }, - required: ["type", "attributes"], - }, - }, - required: ["data"], - }, - }, - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - type: "object", - properties: { - data: { - type: "object", - properties: { - type: { - type: "string", - description: "Resource type.", - enum: ["warehouse_setup"], - }, - id: { - type: "string", - }, - attributes: { - type: "object", - properties: { - tables: { - type: "array", - items: { - type: "object", - properties: { - schema: { - type: "string", - minLength: 1, - description: "Postgres schema name", - examples: ["public"], - }, - name: { - type: "string", - minLength: 1, - description: "Postgres table name", - examples: ["orders"], - }, - state: { - type: "string", - enum: ["syncing", "live", "error"], - description: "Warehouse copy sync state derived from replication status", - examples: ["live"], - }, - lag_ms: { - description: "Replication lag in milliseconds, when available", - type: "integer", - minimum: 0, - maximum: 9007199254740991, - examples: [12000], - }, - last_synced_at: { - description: "Last sync timestamp, when available", - type: "string", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - examples: ["2026-06-23T17:48:00Z"], - }, - copy_name: { - type: "string", - description: - "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", - examples: ['"abcjuqabhgwjjutfvtpa"."public"."orders"'], - }, - warehouse_size_bytes: { - description: "Warehouse table size in bytes, when available", - type: "integer", - minimum: 0, - maximum: 9007199254740991, - examples: [197912092672], - }, - }, - required: ["schema", "name", "state", "copy_name"], - }, - description: "Tables with Warehouse copies", - }, - pipeline_id: { - type: ["string", "null"], - minLength: 1, - description: - "Warehouse replication pipeline ID, or null when Warehouse disable has been requested", - examples: ["03dg2o5teb2eucxr9ggh3uie6"], - }, - accepted: { - type: "boolean", - enum: [true], - }, - selected_tables: { - type: "array", - items: { - type: "object", - properties: { - id: { - type: "integer", - maximum: 4294967295, - exclusiveMinimum: 0, - }, - schema: { - type: "string", - minLength: 1, - }, - name: { - type: "string", - minLength: 1, - }, - }, - required: ["id", "schema", "name"], - }, - }, - selection_id: { - type: "string", - pattern: "^[a-f0-9]{64}$", - description: - "Identity of the accepted selection. Pass to the current setup read to reject a changed selection while waiting.", - }, - }, - required: ["tables", "pipeline_id", "accepted", "selected_tables", "selection_id"], - }, - }, - required: ["type", "id", "attributes"], - }, - }, - required: ["data"], - }, - }, - "v2-get-warehouse-capacity": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - items: { - properties: { - attributes: { - properties: { - aggregation: { - enum: ["mean", "occupied", "p50", "p95", "p99", "rate", "sum"], - type: "string", - }, - availability: { - enum: [ - "disabled", - "insufficient_data", - "no_data", - "not_provisioned", - "ok", - "partial", - "stale", - "unavailable", - ], - type: "string", - }, - definition: { - type: "string", - }, - effective: { - properties: { - end: { - type: "number", - }, - rate_window_seconds: { - type: "number", - }, - start: { - type: "number", - }, - step: { - type: "number", - }, - }, - required: ["end", "rate_window_seconds", "start", "step"], - type: "object", - }, - last_sample_at: { - description: - "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", - type: ["number", "null"], - }, - metric: { - enum: [ - "activation_duration_mean", - "activation_duration_p95", - "activation_rate", - "admission_rejection_rate", - "assignment_wait_mean", - "assignment_wait_p95", - "query_in_flight", - "worker_admission_active", - "worker_admission_limit", - "worker_admission_occupied", - "worker_admission_pending", - ], - type: "string", - }, - project_ref: { - type: "string", - }, - requested: { - properties: { - end: { - type: "number", - }, - metric: { - enum: [ - "activation_duration_mean", - "activation_duration_p95", - "activation_rate", - "admission_rejection_rate", - "assignment_wait_mean", - "assignment_wait_p95", - "query_in_flight", - "worker_admission_active", - "worker_admission_limit", - "worker_admission_occupied", - "worker_admission_pending", - ], - type: "string", - }, - start: { - type: "number", - }, - step: { - type: "number", - }, - }, - required: ["end", "metric", "start"], - type: "object", - }, - scrape_interval_seconds: { - type: "number", - }, - series: { - items: { - properties: { - coverage: { - description: - "Grid point coverage, not proof that every worker was scraped.", - properties: { - expected_points: { - type: "number", - }, - returned_points: { - type: "number", - }, - }, - required: ["expected_points", "returned_points"], - type: "object", - }, - labels: { - additionalProperties: { - type: "string", - }, - type: "object", - }, - points: { - items: { - properties: { - timestamp: { - type: "number", - }, - value: { - type: ["number", "null"], - }, - }, - required: ["timestamp", "value"], - type: "object", - }, - type: "array", - }, - }, - required: ["coverage", "labels", "points"], - type: "object", - }, - type: "array", - }, - unit: { - enum: ["grants", "per_second", "queries", "seconds"], - type: "string", - }, - }, - required: [ - "aggregation", - "availability", - "definition", - "effective", - "last_sample_at", - "metric", - "project_ref", - "requested", - "scrape_interval_seconds", - "series", - "unit", - ], - type: "object", - }, - id: { - enum: [ - "activation_duration_mean", - "activation_duration_p95", - "activation_rate", - "admission_rejection_rate", - "assignment_wait_mean", - "assignment_wait_p95", - "query_in_flight", - "worker_admission_active", - "worker_admission_limit", - "worker_admission_occupied", - "worker_admission_pending", - ], - type: "string", - }, - type: { - description: "Resource type.", - enum: ["warehouse_metric"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - type: "array", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-get-warehouse-connection": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - properties: { - access_mode: { - enum: ["read_only"], - type: "string", - }, - authentication: { - description: - "How to authenticate. No credentials are returned; the password is never exposed by this API.", - properties: { - credential_source: { - enum: ["source_project_database"], - type: "string", - }, - default_username: { - enum: ["postgres"], - type: "string", - }, - membership_guidance: { - type: "string", - }, - method: { - enum: ["database_username_password"], - type: "string", - }, - password_guidance: { - type: "string", - }, - required_membership: { - enum: ["supabase_warehouse_reader"], - type: "string", - }, - }, - required: [ - "credential_source", - "default_username", - "membership_guidance", - "method", - "password_guidance", - "required_membership", - ], - type: "object", - }, - endpoint: { - description: - "Arrow Flight SQL URI, grpc+tls://:443. Null unless status is available or pending.", - type: ["string", "null"], - }, - host: { - description: - "Public hostname of the Flight SQL endpoint. Null unless status is available or pending.", - type: ["string", "null"], - }, - observed_at: { - description: - "Time the API retrieved this information. This timestamp does not indicate when connectivity was last verified.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: "string", - }, - port: { - description: - "Public TLS port of the Flight SQL endpoint. Null unless status is available or pending.", - maximum: 9007199254740991, - minimum: -9007199254740991, - type: ["integer", "null"], - }, - project_ref: { - description: "Project ref", - maxLength: 20, - minLength: 20, - pattern: "^[a-z]+$", - type: "string", - examples: ["abcdefghijklmnopqrst"], - }, - protocol: { - enum: ["arrow_flight_sql"], - type: "string", - }, - query_connectivity: { - enum: ["not_checked"], - type: "string", - }, - region: { - description: - "Assigned Warehouse compute region, which may differ from the source database region. Null when the project has no project-specific route.", - type: ["string", "null"], - }, - routing_status: { - description: - "DNS delivery status of the project route. Null when the project uses the shared legacy route.", - enum: ["error", null, "pending", "ready", "removed"], - type: ["string", "null"], - }, - status: { - description: - "Configured availability of the Warehouse endpoint, derived from routing and lifecycle state. It is not a connectivity probe: a ready route does not prove a query will succeed.", - enum: [ - "available", - "disabled", - "disabling", - "not_configured", - "pending", - "unavailable", - ], - type: "string", - }, - tls_required: { - enum: [true], - type: "boolean", - }, - unavailable_reason: { - description: - "Why the endpoint is unavailable. Null unless status is unavailable.", - enum: [ - "assignment_unavailable", - "cleanup_failed", - null, - "observation_unavailable", - "routing_failed", - ], - type: ["string", "null"], - }, - }, - required: [ - "access_mode", - "authentication", - "endpoint", - "host", - "observed_at", - "port", - "project_ref", - "protocol", - "query_connectivity", - "region", - "routing_status", - "status", - "tls_required", - "unavailable_reason", - ], - type: "object", - }, - id: { - description: "Project ref", - maxLength: 20, - minLength: 20, - pattern: "^[a-z]+$", - type: "string", - examples: ["abcdefghijklmnopqrst"], - }, - type: { - description: "Resource type.", - enum: ["warehouse_connection"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-get-warehouse-query-stats": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - items: { - properties: { - attributes: { - properties: { - aggregation: { - enum: ["mean", "occupied", "p50", "p95", "p99", "rate", "sum"], - type: "string", - }, - availability: { - enum: [ - "disabled", - "insufficient_data", - "no_data", - "not_provisioned", - "ok", - "partial", - "stale", - "unavailable", - ], - type: "string", - }, - definition: { - type: "string", - }, - effective: { - properties: { - end: { - type: "number", - }, - rate_window_seconds: { - type: "number", - }, - start: { - type: "number", - }, - step: { - type: "number", - }, - }, - required: ["end", "rate_window_seconds", "start", "step"], - type: "object", - }, - last_sample_at: { - description: - "Latest observed source sample timestamp in Unix seconds; not the query evaluation timestamp.", - type: ["number", "null"], - }, - metric: { - enum: [ - "activation_duration_mean", - "activation_duration_p95", - "activation_rate", - "admission_rejection_rate", - "assignment_wait_mean", - "assignment_wait_p95", - "duckdb_duration_mean", - "query_canceled_rate", - "query_duration_mean", - "query_duration_p50", - "query_duration_p95", - "query_duration_p99", - "query_error_rate", - "query_in_flight", - "query_rate", - "query_timeout_rate", - "rpc_duration_mean", - "rpc_duration_p95", - "rpc_rate", - "worker_admission_active", - "worker_admission_limit", - "worker_admission_occupied", - "worker_admission_pending", - ], - type: "string", - }, - project_ref: { - type: "string", - }, - requested: { - properties: { - end: { - type: "number", - }, - metric: { - enum: [ - "activation_duration_mean", - "activation_duration_p95", - "activation_rate", - "admission_rejection_rate", - "assignment_wait_mean", - "assignment_wait_p95", - "duckdb_duration_mean", - "query_canceled_rate", - "query_duration_mean", - "query_duration_p50", - "query_duration_p95", - "query_duration_p99", - "query_error_rate", - "query_in_flight", - "query_rate", - "query_timeout_rate", - "rpc_duration_mean", - "rpc_duration_p95", - "rpc_rate", - "worker_admission_active", - "worker_admission_limit", - "worker_admission_occupied", - "worker_admission_pending", - ], - type: "string", - }, - start: { - type: "number", - }, - step: { - type: "number", - }, - }, - required: ["end", "metric", "start"], - type: "object", - }, - scrape_interval_seconds: { - type: "number", - }, - series: { - items: { - properties: { - coverage: { - description: - "Grid point coverage, not proof that every worker was scraped.", - properties: { - expected_points: { - type: "number", - }, - returned_points: { - type: "number", - }, - }, - required: ["expected_points", "returned_points"], - type: "object", - }, - labels: { - additionalProperties: { - type: "string", - }, - type: "object", - }, - points: { - items: { - properties: { - timestamp: { - type: "number", - }, - value: { - type: ["number", "null"], - }, - }, - required: ["timestamp", "value"], - type: "object", - }, - type: "array", - }, - }, - required: ["coverage", "labels", "points"], - type: "object", - }, - type: "array", - }, - unit: { - enum: ["grants", "per_second", "queries", "seconds"], - type: "string", - }, - }, - required: [ - "aggregation", - "availability", - "definition", - "effective", - "last_sample_at", - "metric", - "project_ref", - "requested", - "scrape_interval_seconds", - "series", - "unit", - ], - type: "object", - }, - id: { - enum: [ - "activation_duration_mean", - "activation_duration_p95", - "activation_rate", - "admission_rejection_rate", - "assignment_wait_mean", - "assignment_wait_p95", - "duckdb_duration_mean", - "query_canceled_rate", - "query_duration_mean", - "query_duration_p50", - "query_duration_p95", - "query_duration_p99", - "query_error_rate", - "query_in_flight", - "query_rate", - "query_timeout_rate", - "rpc_duration_mean", - "rpc_duration_p95", - "rpc_rate", - "worker_admission_active", - "worker_admission_limit", - "worker_admission_occupied", - "worker_admission_pending", - ], - type: "string", - }, - type: { - description: "Resource type.", - enum: ["warehouse_metric"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - type: "array", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-get-warehouse-setup": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - type: "object", - properties: { - data: { - type: "object", - properties: { - type: { - type: "string", - description: "Resource type.", - enum: ["warehouse_setup"], - }, - id: { - type: "string", - }, - attributes: { - type: "object", - properties: { - dns: { - description: - "Warehouse DNS delivery status. Ready means the DNS API accepted the route; client DNS caches may still be updating.", - type: "object", - properties: { - hostname: { - type: "string", - }, - region: { - type: "string", - }, - status: { - type: "string", - enum: ["pending", "ready", "error", "removed"], - }, - }, - required: ["hostname", "region", "status"], - }, - delete_data: { - description: "Whether the current disable request deletes DuckLake data.", - type: "boolean", - }, - error: { - description: "Warehouse cleanup failure, when present.", - type: "string", - }, - setup_status: { - type: "string", - enum: [ - "not_started", - "setting_up", - "copying", - "complete", - "error", - "disabling", - "disabled", - "deletion_failed", - ], - description: - "Overall Warehouse lifecycle status, using persisted state during teardown and replication state during setup", - examples: ["copying"], - }, - pipeline_id: { - description: "Warehouse replication pipeline ID when it exists", - type: "string", - minLength: 1, - examples: ["03dg2o5teb2eucxr9ggh3uie6"], - }, - steps: { - type: "array", - items: { - type: "object", - properties: { - name: { - type: "string", - enum: ["warehouse_pipeline", "warehouse_copy", "warehouse_fdw"], - description: "Observable Warehouse setup phase", - examples: ["warehouse_copy"], - }, - status: { - type: "string", - enum: ["waiting", "running", "completed", "skipped", "error"], - description: "Derived Warehouse setup step status", - examples: ["running"], - }, - message: { - description: - "Best-effort progress or error message derived from Warehouse state", - type: "string", - examples: ["Pending initial copy: public.orders:copying_table"], - }, - }, - required: ["name", "status"], - }, - description: "Warehouse setup phases in execution order", - }, - tables: { - type: "array", - items: { - type: "object", - properties: { - schema: { - type: "string", - minLength: 1, - description: "Postgres schema name", - examples: ["public"], - }, - name: { - type: "string", - minLength: 1, - description: "Postgres table name", - examples: ["orders"], - }, - state: { - type: "string", - enum: ["syncing", "live", "error"], - description: "Warehouse copy sync state derived from replication status", - examples: ["live"], - }, - lag_ms: { - description: "Replication lag in milliseconds, when available", - type: "integer", - minimum: 0, - maximum: 9007199254740991, - examples: [12000], - }, - last_synced_at: { - description: "Last sync timestamp, when available", - type: "string", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - examples: ["2026-06-23T17:48:00Z"], - }, - copy_name: { - type: "string", - description: - "DuckLake table path with individually quoted identifiers, including the configured project namespace when present", - examples: ['"abcjuqabhgwjjutfvtpa"."public"."orders"'], - }, - warehouse_size_bytes: { - description: "Warehouse table size in bytes, when available", - type: "integer", - minimum: 0, - maximum: 9007199254740991, - examples: [197912092672], - }, - id: { - type: "integer", - maximum: 4294967295, - exclusiveMinimum: 0, - }, - replication_state: { - type: ["string", "null"], - }, - }, - required: ["schema", "name", "state", "copy_name", "id", "replication_state"], - }, - }, - fdw_status: { - type: ["object", "null"], - properties: { - extension_available: { - type: "boolean", - description: - "Whether fdw_warehouse is available to install on the project database instance", - examples: [true], - }, - extension_installed: { - type: "boolean", - description: - "Whether the fdw_warehouse extension exists in the project database", - examples: [true], - }, - wrapper_installed: { - type: "boolean", - description: - "Whether the Warehouse foreign data wrapper exists in the project database", - examples: [true], - }, - server_configured: { - type: "boolean", - description: - "Whether the Warehouse foreign server exists in the project database", - examples: [true], - }, - schema_created: { - type: "boolean", - description: - "Whether the local Warehouse schema exists in the project database", - examples: [true], - }, - foreign_schema_imported: { - type: "boolean", - description: - "Whether the Warehouse foreign schema import has exposed the Warehouse snapshots table", - examples: [true], - }, - }, - required: [ - "extension_available", - "extension_installed", - "wrapper_installed", - "server_configured", - "schema_created", - "foreign_schema_imported", - ], - description: - "Project database FDW setup markers; null during or after teardown, when setup inspection is inapplicable.", - }, - status: { - type: "string", - enum: ["running", "succeeded", "failed"], - description: - "Current enablement readiness. Success requires initial copy, a running pipeline and ready routing; this is not a historical operation result or a query connectivity check.", - }, - status_error: { - description: - "Reason current enablement readiness failed. Separate from Studio setup or cleanup errors.", - type: "string", - }, - replication_state: { - type: "string", - }, - }, - required: [ - "setup_status", - "steps", - "tables", - "fdw_status", - "status", - "replication_state", - ], - }, - }, - required: ["type", "id", "attributes"], - }, - }, - required: ["data"], - }, - }, - "v2-get-warehouse-status": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - properties: { - capabilities: { - description: - "Complete operations supported by this API, not caller authorization. Each operation still requires its feature, entitlement and project permission checks.", - properties: { - context: { - type: "boolean", - }, - query_explain: { - type: "boolean", - }, - replication_add: { - type: "boolean", - }, - replication_remove: { - type: "boolean", - }, - table_layout_read: { - type: "boolean", - }, - table_layout_update: { - type: "boolean", - }, - table_resync: { - type: "boolean", - }, - workload_metrics: { - type: "boolean", - }, - }, - required: [ - "context", - "query_explain", - "replication_add", - "replication_remove", - "table_layout_read", - "table_layout_update", - "table_resync", - "workload_metrics", - ], - type: "object", - }, - compute: { - description: - "Configured Warehouse compute and region, which may differ from the source database region. Live availability and capacity are not reported.", - properties: { - observed_at: { - description: - "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: ["string", "null"], - }, - region: { - type: ["string", "null"], - }, - routing_status: { - enum: ["error", null, "pending", "ready", "removed"], - type: ["string", "null"], - }, - status: { - enum: ["available", "not_provisioned", "unavailable"], - type: "string", - }, - unavailable_reason: { - enum: [ - "assignment_unavailable", - "cleanup_failed", - "cleanup_in_progress", - "identity_mismatch", - null, - "observation_unavailable", - ], - type: ["string", "null"], - }, - }, - required: [ - "observed_at", - "region", - "routing_status", - "status", - "unavailable_reason", - ], - type: "object", - }, - configured_readiness: { - description: - "Readiness inferred from configuration and replication observations; no query is executed.", - enum: ["not_ready", "ready", "unavailable"], - type: "string", - }, - enabled: { - description: - "Whether Warehouse is enabled, independently of selected table count. Null means provisioning could not be determined.", - type: ["boolean", "null"], - }, - lifecycle: { - properties: { - delete_data: { - type: "boolean", - }, - status: { - enum: ["deletion_failed", "disabled", "disabling"], - type: "string", - }, - updated_at: { - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: "string", - }, - }, - required: ["delete_data", "status", "updated_at"], - type: ["object", "null"], - }, - observed_at: { - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: "string", - }, - pipeline: { - properties: { - id: { - minLength: 1, - type: "string", - }, - observed_at: { - description: - "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: ["string", "null"], - }, - status: { - enum: [ - "failed", - "started", - "starting", - "stopped", - "stopping", - "unavailable", - "unknown", - ], - type: "string", - }, - unavailable_reason: { - enum: [ - "assignment_unavailable", - "cleanup_failed", - "cleanup_in_progress", - "identity_mismatch", - null, - "observation_unavailable", - ], - type: ["string", "null"], - }, - }, - required: ["id", "observed_at", "status", "unavailable_reason"], - type: ["object", "null"], - }, - project_ref: { - description: "Project ref", - maxLength: 20, - minLength: 20, - pattern: "^[a-z]+$", - type: "string", - examples: ["abcdefghijklmnopqrst"], - }, - query_connectivity: { - enum: ["not_checked"], - type: "string", - }, - replication: { - properties: { - apply_lag: { - description: - "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", - properties: { - active: { - type: "boolean", - }, - feedback_age_ms: { - minimum: 0, - type: ["number", "null"], - }, - flush_lag_bytes: { - maximum: 9007199254740991, - minimum: 0, - type: ["integer", "null"], - }, - flush_lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - wal_status: { - enum: ["extended", "lost", null, "reserved", "unknown", "unreserved"], - type: ["string", "null"], - }, - write_lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - }, - required: [ - "active", - "feedback_age_ms", - "flush_lag_bytes", - "flush_lag_ms", - "wal_status", - "write_lag_ms", - ], - type: ["object", "null"], - }, - observed_at: { - description: - "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: ["string", "null"], - }, - status: { - enum: [ - "available", - "not_provisioned", - "not_started", - "stopped", - "unavailable", - ], - type: "string", - }, - unavailable_reason: { - enum: [ - "assignment_unavailable", - "cleanup_failed", - "cleanup_in_progress", - "identity_mismatch", - null, - "observation_unavailable", - ], - type: ["string", "null"], - }, - }, - required: ["apply_lag", "observed_at", "status", "unavailable_reason"], - type: "object", - }, - status: { - description: - "Warehouse setup and replication status. Ready means the Warehouse connection is configured and tables are replicating ongoing changes. It does not guarantee that a query will succeed.", - enum: [ - "degraded", - "disabled", - "disabling", - "not_provisioned", - "ready", - "starting", - "stopped", - "stopping", - "unavailable", - ], - type: "string", - }, - tables: { - properties: { - items: { - items: { - properties: { - id: { - maximum: 9007199254740991, - type: "integer", - exclusiveMinimum: 0, - }, - name: { - type: "string", - }, - replication_state: { - enum: [ - "copied_table", - "copying_table", - "error", - "following_wal", - null, - "queued", - ], - type: ["string", "null"], - }, - schema: { - type: "string", - }, - sync_lag: { - description: - "Postgres replication feedback. Null means Postgres reported no value; lag times also become null shortly after a caught-up slot sees no new WAL, while flush_lag_bytes, the WAL not yet confirmed flushed, reads 0. Feedback age measures time since the last response and does not establish how current query results are.", - properties: { - active: { - type: "boolean", - }, - feedback_age_ms: { - minimum: 0, - type: ["number", "null"], - }, - flush_lag_bytes: { - maximum: 9007199254740991, - minimum: 0, - type: ["integer", "null"], - }, - flush_lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - wal_status: { - enum: [ - "extended", - "lost", - null, - "reserved", - "unknown", - "unreserved", - ], - type: ["string", "null"], - }, - write_lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - }, - required: [ - "active", - "feedback_age_ms", - "flush_lag_bytes", - "flush_lag_ms", - "wal_status", - "write_lag_ms", - ], - type: ["object", "null"], - }, - }, - required: ["id", "name", "replication_state", "schema", "sync_lag"], - type: "object", - }, - type: "array", - }, - observed_at: { - description: - "Time the API retrieved this information. This timestamp does not indicate when data was measured or last synchronized.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: ["string", "null"], - }, - status: { - enum: ["available", "not_provisioned", "unavailable"], - type: "string", - }, - unavailable_reason: { - enum: [ - "assignment_unavailable", - "cleanup_failed", - "cleanup_in_progress", - "identity_mismatch", - null, - "observation_unavailable", - ], - type: ["string", "null"], - }, - }, - required: ["items", "observed_at", "status", "unavailable_reason"], - type: "object", - }, - }, - required: [ - "capabilities", - "compute", - "configured_readiness", - "enabled", - "lifecycle", - "observed_at", - "pipeline", - "project_ref", - "query_connectivity", - "replication", - "status", - "tables", - ], - type: "object", - }, - id: { - description: "Project ref", - maxLength: 20, - minLength: 20, - pattern: "^[a-z]+$", - type: "string", - examples: ["abcdefghijklmnopqrst"], - }, - type: { - description: "Resource type.", - enum: ["warehouse_context"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-get-warehouse-table": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - properties: { - lag_ms: { - description: - "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", - minimum: 0, - type: ["number", "null"], - }, - name: { - description: "Source PostgreSQL table name.", - type: "string", - }, - observed_at: { - description: - "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: ["string", "null"], - }, - replication_feedback: { - description: - "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", - properties: { - active: { - type: "boolean", - }, - feedback_age_ms: { - minimum: 0, - type: ["number", "null"], - }, - flush_lag_bytes: { - maximum: 9007199254740991, - minimum: 0, - type: ["integer", "null"], - }, - flush_lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - source: { - description: - "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", - enum: ["pipeline_apply", "table_sync"], - type: "string", - }, - wal_status: { - enum: ["extended", "lost", null, "reserved", "unknown", "unreserved"], - type: ["string", "null"], - }, - write_lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - }, - required: [ - "active", - "feedback_age_ms", - "flush_lag_bytes", - "flush_lag_ms", - "source", - "wal_status", - "write_lag_ms", - ], - type: ["object", "null"], - }, - replication_state: { - description: - "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", - enum: ["copied_table", "copying_table", "error", "following_wal", null, "queued"], - type: ["string", "null"], - }, - schema: { - description: "Source PostgreSQL schema of the table.", - type: "string", - }, - status: { - description: - "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", - enum: ["error", "live", "stopped", "syncing", "unknown"], - type: "string", - }, - warehouse_name: { - description: - "Quoted, fully qualified name of the replicated table in the Warehouse.", - type: "string", - }, - }, - required: [ - "lag_ms", - "name", - "observed_at", - "replication_feedback", - "replication_state", - "schema", - "status", - "warehouse_name", - ], - type: "object", - }, - id: { - description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", - maxLength: 10, - pattern: "^[1-9]\\d*$", - type: "string", - examples: ["16385"], - }, - type: { - description: "Resource type.", - enum: ["warehouse_table"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-get-warehouse-table-layout": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - properties: { - application_status: { - description: - "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", - type: "string", - }, - desired: { - description: - "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", - properties: { - partition_by: { - description: - "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", - items: { - properties: { - column: { - description: "Source column name.", - type: "string", - }, - transform: { - oneOf: [ - { - properties: { - kind: { - enum: ["identity"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["year"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["month"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["day"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["hour"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - count: { - description: "Number of hash buckets.", - maximum: 2147483647, - type: "integer", - exclusiveMinimum: 0, - }, - kind: { - enum: ["bucket"], - type: "string", - }, - }, - required: ["count", "kind"], - type: "object", - }, - ], - }, - }, - required: ["column", "transform"], - type: "object", - }, - type: ["array", "null"], - }, - sort_by: { - description: - "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", - oneOf: [ - { - properties: { - kind: { - enum: ["none"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["primary_key"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - columns: { - items: { - properties: { - direction: { - enum: ["asc", "desc"], - type: "string", - }, - name: { - description: "Source column name.", - type: "string", - }, - nulls: { - description: - "Null placement. Null uses DuckLake's default placement.", - enum: ["first", "last", null], - type: ["string", "null"], - }, - }, - required: ["direction", "name", "nulls"], - type: "object", - }, - type: "array", - }, - kind: { - enum: ["columns"], - type: "string", - }, - }, - required: ["columns", "kind"], - type: "object", - }, - { - type: ["object", "null"], - enum: [null], - }, - ], - }, - }, - required: ["partition_by", "sort_by"], - type: "object", - }, - name: { - description: "Source PostgreSQL table name.", - type: "string", - }, - observation_status: { - description: - "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", - enum: ["not_requested", "observed", "table_missing", "unavailable"], - type: "string", - }, - observed: { - description: - "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", - properties: { - observed_at: { - description: "Time the catalog metadata was read.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: "string", - }, - partition_by: { - description: - "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", - items: { - properties: { - column: { - type: "string", - }, - transform: { - type: "string", - }, - }, - required: ["column", "transform"], - type: "object", - }, - type: "array", - }, - sort_by: { - description: - "Active sort expressions in key order, as the catalog reports them.", - items: { - properties: { - direction: { - type: "string", - }, - expression: { - type: "string", - }, - nulls: { - type: "string", - }, - }, - required: ["direction", "expression", "nulls"], - type: "object", - }, - type: "array", - }, - }, - required: ["observed_at", "partition_by", "sort_by"], - type: ["object", "null"], - }, - pipeline_id: { - description: "Warehouse replication pipeline identity.", - type: "string", - }, - reset_table: { - description: - "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", - type: "boolean", - }, - schema: { - description: "Source PostgreSQL schema of the table.", - type: "string", - }, - }, - required: [ - "application_status", - "desired", - "name", - "observation_status", - "observed", - "pipeline_id", - "reset_table", - "schema", - ], - type: "object", - }, - id: { - description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", - maxLength: 10, - pattern: "^[1-9]\\d*$", - type: "string", - examples: ["16385"], - }, - type: { - description: "Resource type.", - enum: ["warehouse_table_layout"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-get-warehouse-teardown": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - type: "object", - properties: { - data: { - type: "object", - properties: { - type: { - type: "string", - description: "Resource type.", - enum: ["warehouse_teardown"], - }, - id: { - type: "string", - format: "uuid", - pattern: - "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", - }, - attributes: { - type: "object", - properties: { - lifecycle_status: { - type: "string", - enum: ["disabling", "disabled", "deletion_failed"], - }, - delete_data: { - type: "boolean", - description: - "Whether this cleanup permanently deletes managed Warehouse data. Source Postgres tables are preserved in both modes.", - }, - updated_at: { - type: "string", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", - }, - cleanup_error: { - description: - "Last cleanup failure, or null when none was recorded. Failed cleanup can leave partially removed resources; retry disable with the same data policy.", - type: ["string", "null"], - }, - }, - required: ["lifecycle_status", "delete_data", "updated_at", "cleanup_error"], - }, - }, - required: ["type", "id", "attributes"], - }, - }, - required: ["data"], - }, - }, - "v2-list-warehouse-tables": { - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - items: { - properties: { - attributes: { - properties: { - lag_ms: { - description: - "Flush lag in milliseconds that Postgres reports for the slot in replication_feedback. Null when there is no feedback or Postgres reports no recent measurement, which includes a caught-up slot without new WAL; replication_feedback.flush_lag_bytes reads 0 in that case.", - minimum: 0, - type: ["number", "null"], - }, - name: { - description: "Source PostgreSQL table name.", - type: "string", - }, - observed_at: { - description: - "Time the API retrieved the replication state of the table. It does not indicate when data was last synchronized.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: ["string", "null"], - }, - replication_feedback: { - description: - "Postgres feedback from the replication slot named in source. Null when no feedback is available, including while the pipeline is stopped. Feedback age measures time since the slot last responded and does not establish how current query results are.", - properties: { - active: { - type: "boolean", - }, - feedback_age_ms: { - minimum: 0, - type: ["number", "null"], - }, - flush_lag_bytes: { - maximum: 9007199254740991, - minimum: 0, - type: ["integer", "null"], - }, - flush_lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - source: { - description: - "Replication slot that reported the feedback: the table's own sync slot until it follows changes, or the pipeline apply slot once it does.", - enum: ["pipeline_apply", "table_sync"], - type: "string", - }, - wal_status: { - enum: ["extended", "lost", null, "reserved", "unknown", "unreserved"], - type: ["string", "null"], - }, - write_lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - }, - required: [ - "active", - "feedback_age_ms", - "flush_lag_bytes", - "flush_lag_ms", - "source", - "wal_status", - "write_lag_ms", - ], - type: ["object", "null"], - }, - replication_state: { - description: - "Last replication state the pipeline recorded for the table, also while the pipeline is stopped. Null when none was observed.", - enum: [ - "copied_table", - "copying_table", - "error", - "following_wal", - null, - "queued", - ], - type: ["string", "null"], - }, - schema: { - description: "Source PostgreSQL schema of the table.", - type: "string", - }, - status: { - description: - "Replication status. error means the table failed to replicate; stopped means the pipeline is stopped, stopping or failed, so the table receives no changes; live means the table follows changes; syncing means it is queued, copying or catching up; unknown means the pipeline status or the table state was not observed, for example before replication starts.", - enum: ["error", "live", "stopped", "syncing", "unknown"], - type: "string", - }, - warehouse_name: { - description: - "Quoted, fully qualified name of the replicated table in the Warehouse.", - type: "string", - }, - }, - required: [ - "lag_ms", - "name", - "observed_at", - "replication_feedback", - "replication_state", - "schema", - "status", - "warehouse_name", - ], - type: "object", - }, - id: { - description: - "Source PostgreSQL table OID, as returned by the Warehouse tables list.", - maxLength: 10, - pattern: "^[1-9]\\d*$", - type: "string", - examples: ["16385"], - }, - type: { - description: "Resource type.", - enum: ["warehouse_table"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - type: "array", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-remove-warehouse-replication": { - request: { - contentType: "application/json", - schema: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - additionalProperties: false, - properties: { - schema: { - description: - "Literal source PostgreSQL schema. Omit table to select its current tables.", - minLength: 1, - type: "string", - }, - table: { - description: "Literal source table name. Omit to select the schema.", - minLength: 1, - type: "string", - }, - }, - required: ["schema"], - type: "object", - }, - type: { - description: "Resource type.", - enum: ["warehouse_replication_change"], - type: "string", - }, - }, - required: ["attributes", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - properties: { - action: { - enum: ["add", "remove"], - type: "string", - }, - affected_tables: { - items: { - properties: { - id: { - maximum: 4294967295, - type: "integer", - exclusiveMinimum: 0, - }, - name: { - minLength: 1, - type: "string", - }, - schema: { - minLength: 1, - type: "string", - }, - }, - required: ["id", "name", "schema"], - type: "object", - }, - type: "array", - }, - application_status: { - description: - "Immediate orchestration result. Restart acceptance does not establish runtime application or copy completion.", - enum: ["configured", "restart_requested", "unchanged"], - type: "string", - }, - changed: { - type: "boolean", - }, - includes_future_tables: { - enum: [false], - type: "boolean", - }, - pipeline_id: { - type: "string", - }, - pipeline_status_before: { - type: "string", - }, - selected_table_count: { - maximum: 9007199254740991, - minimum: 0, - type: "integer", - }, - source_data_preserved: { - enum: [true], - type: "boolean", - }, - tables: { - description: - "Resulting configured selection, with best-effort replication observations.", - items: { - properties: { - copy_name: { - type: "string", - }, - id: { - maximum: 4294967295, - type: "integer", - exclusiveMinimum: 0, - }, - lag_ms: { - minimum: 0, - type: ["number", "null"], - }, - name: { - minLength: 1, - type: "string", - }, - replication_state: { - type: ["string", "null"], - }, - schema: { - minLength: 1, - type: "string", - }, - state: { - description: - "Last observed table state; null when unavailable. Does not establish completion of this request.", - enum: ["error", "live", null, "syncing"], - type: ["string", "null"], - }, - }, - required: [ - "copy_name", - "id", - "lag_ms", - "name", - "replication_state", - "schema", - "state", - ], - type: "object", - }, - type: "array", - }, - unchanged_tables: { - items: { - properties: { - id: { - maximum: 4294967295, - type: "integer", - exclusiveMinimum: 0, - }, - name: { - minLength: 1, - type: "string", - }, - schema: { - minLength: 1, - type: "string", - }, - }, - required: ["id", "name", "schema"], - type: "object", - }, - type: "array", - }, - warehouse_data_retained: { - enum: [true], - type: "boolean", - }, - warehouse_enabled: { - enum: [true], - type: "boolean", - }, - }, - required: [ - "action", - "affected_tables", - "application_status", - "changed", - "includes_future_tables", - "pipeline_id", - "pipeline_status_before", - "selected_table_count", - "source_data_preserved", - "tables", - "unchanged_tables", - "warehouse_data_retained", - "warehouse_enabled", - ], - type: "object", - }, - id: { - type: "string", - }, - type: { - description: "Resource type.", - enum: ["warehouse_replication_change"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-resync-warehouse-replication": { - request: { - contentType: "application/json", - schema: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - additionalProperties: false, - properties: { - schema: { - description: "Literal source PostgreSQL schema of the table.", - minLength: 1, - type: "string", - }, - table: { - description: "Literal name of the single source table to reset and recopy.", - minLength: 1, - type: "string", - }, - }, - required: ["schema", "table"], - type: "object", - }, - type: { - description: "Resource type.", - enum: ["warehouse_replication_resync"], - type: "string", - }, - }, - required: ["attributes", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - properties: { - application_status: { - description: - "ETL reset replication state. Destination rebuild and recopy may still be pending.", - enum: ["reset"], - type: "string", - }, - pipeline_id: { - description: "Pipeline ID", - minLength: 1, - type: "string", - examples: ["03dg2o5teb2eucxr9ggh3uie6"], - }, - source_data_preserved: { - enum: [true], - type: "boolean", - }, - source_table: { - properties: { - id: { - maximum: 4294967295, - type: "integer", - exclusiveMinimum: 0, - }, - name: { - minLength: 1, - type: "string", - }, - schema: { - minLength: 1, - type: "string", - }, - }, - required: ["id", "name", "schema"], - type: "object", - }, - tables: { - description: "Rolled back tables", - items: { - properties: { - new_state: { - description: "Table replication state", - oneOf: [ - { - properties: { - name: { - enum: ["queued"], - type: "string", - }, - }, - required: ["name"], - type: "object", - }, - { - properties: { - name: { - enum: ["copying_table"], - type: "string", - }, - }, - required: ["name"], - type: "object", - }, - { - properties: { - name: { - enum: ["copied_table"], - type: "string", - }, - }, - required: ["name"], - type: "object", - }, - { - properties: { - name: { - enum: ["following_wal"], - type: "string", - }, - }, - required: ["name"], - type: "object", - }, - { - properties: { - name: { - enum: ["error"], - type: "string", - }, - reason: { - type: "string", - }, - retry_policy: { - oneOf: [ - { - properties: { - policy: { - enum: ["no_retry"], - type: "string", - }, - }, - required: ["policy"], - type: "object", - }, - { - properties: { - policy: { - enum: ["manual_retry"], - type: "string", - }, - }, - required: ["policy"], - type: "object", - }, - { - properties: { - next_retry: { - description: "Next retry time (RFC 3339 timestamp)", - type: "string", - examples: ["2025-01-02T03:04:05Z"], - }, - policy: { - enum: ["timed_retry"], - type: "string", - }, - }, - required: ["next_retry", "policy"], - type: "object", - }, - ], - }, - solution: { - type: ["string", "null"], - }, - }, - required: ["name", "reason", "retry_policy"], - type: "object", - }, - ], - }, - table_id: { - description: "Table id (Postgres OID)", - maximum: 4294967295, - minimum: 0, - type: "integer", - examples: [16408], - }, - }, - required: ["new_state", "table_id"], - type: "object", - }, - type: "array", - }, - }, - required: [ - "application_status", - "pipeline_id", - "source_data_preserved", - "source_table", - "tables", - ], - type: "object", - }, - id: { - type: "string", - }, - type: { - description: "Resource type.", - enum: ["warehouse_replication_resync"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - "v2-update-warehouse-table-layout": { - request: { - contentType: "application/json", - schema: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - anyOf: [ - { - additionalProperties: false, - properties: { - partition_by: { - description: - "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", - items: { - additionalProperties: false, - properties: { - column: { - description: "Source column name.", - minLength: 1, - type: "string", - }, - transform: { - oneOf: [ - { - additionalProperties: false, - properties: { - kind: { - enum: ["identity"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["year"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["month"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["day"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["hour"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - count: { - description: "Number of hash buckets.", - maximum: 2147483647, - type: "integer", - exclusiveMinimum: 0, - }, - kind: { - enum: ["bucket"], - type: "string", - }, - }, - required: ["count", "kind"], - type: "object", - }, - ], - }, - }, - required: ["column", "transform"], - type: "object", - }, - type: ["array", "null"], - }, - reset_table: { - description: - "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", - type: "boolean", - }, - sort_by: { - description: - "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", - oneOf: [ - { - additionalProperties: false, - properties: { - kind: { - enum: ["none"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["primary_key"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - columns: { - items: { - additionalProperties: false, - properties: { - direction: { - enum: ["asc", "desc"], - type: "string", - }, - name: { - description: "Source column name.", - minLength: 1, - type: "string", - }, - nulls: { - description: - "Null placement. Null uses DuckLake's default placement.", - enum: ["first", "last", null], - type: ["string", "null"], - }, - }, - required: ["direction", "name"], - type: "object", - }, - minItems: 1, - type: "array", - }, - kind: { - enum: ["columns"], - type: "string", - }, - }, - required: ["columns", "kind"], - type: "object", - }, - { - type: ["object", "null"], - enum: [null], - }, - ], - }, - }, - required: ["sort_by"], - type: "object", - }, - { - additionalProperties: false, - properties: { - partition_by: { - description: - "Omit to preserve the saved partitioning. Null makes partitioning unmanaged. An empty list explicitly clears partitioning. Otherwise, supply all ordered partition keys.", - items: { - additionalProperties: false, - properties: { - column: { - description: "Source column name.", - minLength: 1, - type: "string", - }, - transform: { - oneOf: [ - { - additionalProperties: false, - properties: { - kind: { - enum: ["identity"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["year"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["month"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["day"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["hour"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - count: { - description: "Number of hash buckets.", - maximum: 2147483647, - type: "integer", - exclusiveMinimum: 0, - }, - kind: { - enum: ["bucket"], - type: "string", - }, - }, - required: ["count", "kind"], - type: "object", - }, - ], - }, - }, - required: ["column", "transform"], - type: "object", - }, - type: ["array", "null"], - }, - reset_table: { - description: - "Defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never resets the table.", - type: "boolean", - }, - sort_by: { - description: - "Omit to preserve the saved sorting. Null makes sorting unmanaged. The none selector explicitly clears sorting. Otherwise, supply the complete sort selector.", - oneOf: [ - { - additionalProperties: false, - properties: { - kind: { - enum: ["none"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - kind: { - enum: ["primary_key"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - additionalProperties: false, - properties: { - columns: { - items: { - additionalProperties: false, - properties: { - direction: { - enum: ["asc", "desc"], - type: "string", - }, - name: { - description: "Source column name.", - minLength: 1, - type: "string", - }, - nulls: { - description: - "Null placement. Null uses DuckLake's default placement.", - enum: ["first", "last", null], - type: ["string", "null"], - }, - }, - required: ["direction", "name"], - type: "object", - }, - minItems: 1, - type: "array", - }, - kind: { - enum: ["columns"], - type: "string", - }, - }, - required: ["columns", "kind"], - type: "object", - }, - { - type: ["object", "null"], - enum: [null], - }, - ], - }, - }, - required: ["partition_by"], - type: "object", - }, - ], - }, - type: { - description: "Resource type.", - enum: ["warehouse_table_layout"], - type: "string", - }, - }, - required: ["attributes", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, - result: { - $schema: "https://json-schema.org/draft/2020-12/schema", - properties: { - data: { - properties: { - attributes: { - properties: { - application_status: { - description: - "Backend orchestration state. Runtime acceptance does not establish that the desired layout has been observed in the catalog.", - type: "string", - }, - desired: { - description: - "Saved layout rules. The replicator applies them on start and hourly, so they can differ from the observed layout.", - properties: { - partition_by: { - description: - "Configured partition keys in order. An empty list explicitly clears partitioning; null leaves it unmanaged.", - items: { - properties: { - column: { - description: "Source column name.", - type: "string", - }, - transform: { - oneOf: [ - { - properties: { - kind: { - enum: ["identity"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["year"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["month"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["day"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["hour"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - count: { - description: "Number of hash buckets.", - maximum: 2147483647, - type: "integer", - exclusiveMinimum: 0, - }, - kind: { - enum: ["bucket"], - type: "string", - }, - }, - required: ["count", "kind"], - type: "object", - }, - ], - }, - }, - required: ["column", "transform"], - type: "object", - }, - type: ["array", "null"], - }, - sort_by: { - description: - "Configured sort order. none explicitly clears sorting, primary_key sorts by the source primary-key columns in key order, and columns lists them. Null leaves sorting unmanaged.", - oneOf: [ - { - properties: { - kind: { - enum: ["none"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - kind: { - enum: ["primary_key"], - type: "string", - }, - }, - required: ["kind"], - type: "object", - }, - { - properties: { - columns: { - items: { - properties: { - direction: { - enum: ["asc", "desc"], - type: "string", - }, - name: { - description: "Source column name.", - type: "string", - }, - nulls: { - description: - "Null placement. Null uses DuckLake's default placement.", - enum: ["first", "last", null], - type: ["string", "null"], - }, - }, - required: ["direction", "name", "nulls"], - type: "object", - }, - type: "array", - }, - kind: { - enum: ["columns"], - type: "string", - }, - }, - required: ["columns", "kind"], - type: "object", - }, - { - type: ["object", "null"], - enum: [null], - }, - ], - }, - }, - required: ["partition_by", "sort_by"], - type: "object", - }, - name: { - description: "Source PostgreSQL table name.", - type: "string", - }, - observation_status: { - description: - "observed when the DuckLake catalog was read, table_missing when the catalog has no table for it yet, unavailable when the catalog could not be read, and not_requested when an update returned without reading the catalog.", - enum: ["not_requested", "observed", "table_missing", "unavailable"], - type: "string", - }, - observed: { - description: - "Layout recorded in the DuckLake catalog, null unless observation_status is observed. Catalog metadata governs files written after it changes and does not establish that existing files are sorted or partitioned.", - properties: { - observed_at: { - description: "Time the catalog metadata was read.", - format: "date-time", - pattern: - "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", - type: "string", - }, - partition_by: { - description: - "Active partition keys in key order, with transforms as the catalog reports them, for example bucket(16).", - items: { - properties: { - column: { - type: "string", - }, - transform: { - type: "string", - }, - }, - required: ["column", "transform"], - type: "object", - }, - type: "array", - }, - sort_by: { - description: - "Active sort expressions in key order, as the catalog reports them.", - items: { - properties: { - direction: { - type: "string", - }, - expression: { - type: "string", - }, - nulls: { - type: "string", - }, - }, - required: ["direction", "expression", "nulls"], - type: "object", - }, - type: "array", - }, - }, - required: ["observed_at", "partition_by", "sort_by"], - type: ["object", "null"], - }, - pipeline_id: { - description: "Warehouse replication pipeline identity.", - type: "string", - }, - reset_table: { - description: - "Whether this update reset source replication state. False for unchanged layouts and reads; reads do not retain reset history. True does not establish completion of recopy.", - type: "boolean", - }, - schema: { - description: "Source PostgreSQL schema of the table.", - type: "string", - }, - }, - required: [ - "application_status", - "desired", - "name", - "observation_status", - "observed", - "pipeline_id", - "reset_table", - "schema", - ], - type: "object", - }, - id: { - description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", - maxLength: 10, - pattern: "^[1-9]\\d*$", - type: "string", - examples: ["16385"], - }, - type: { - description: "Resource type.", - enum: ["warehouse_table_layout"], - type: "string", - }, - }, - required: ["attributes", "id", "type"], - type: "object", - }, - }, - required: ["data"], - type: "object", - }, - }, -} as const satisfies Readonly>; diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 2b88424975..5288702a9a 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -6,8 +6,6 @@ export const apiCommands = [ command: ["warehouse", "connection"], operationId: "v2-get-warehouse-connection", definition: "v2GetWarehouseConnection", - method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/connection", summary: "Get Warehouse Flight SQL connection details", description: "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.", @@ -30,8 +28,6 @@ export const apiCommands = [ command: ["warehouse", "disable"], operationId: "v2-disable-warehouse", definition: "v2DisableWarehouse", - method: "DELETE", - apiPath: "/v2/projects/{ref}/warehouse", summary: "Disable Warehouse replication and access", description: "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.", @@ -79,8 +75,6 @@ export const apiCommands = [ command: ["warehouse", "enable"], operationId: "v2-enable-warehouse", definition: "v2EnableWarehouse", - method: "POST", - apiPath: "/v2/projects/{ref}/warehouse/enable", summary: "Enable Warehouse replication", description: "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.", @@ -194,8 +188,6 @@ export const apiCommands = [ command: ["warehouse", "inspect", "capacity"], operationId: "v2-get-warehouse-capacity", definition: "v2GetWarehouseCapacity", - method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/capacity", summary: "Inspect Warehouse capacity diagnostics", description: "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.", @@ -290,8 +282,6 @@ export const apiCommands = [ command: ["warehouse", "inspect", "query-stats"], operationId: "v2-get-warehouse-query-stats", definition: "v2GetWarehouseQueryStats", - method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/query-stats", summary: "Inspect Warehouse workload query statistics", description: "Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.", @@ -386,8 +376,6 @@ export const apiCommands = [ command: ["warehouse", "replication", "add"], operationId: "v2-add-warehouse-replication", definition: "v2AddWarehouseReplication", - method: "POST", - apiPath: "/v2/projects/{ref}/warehouse/replication/add", summary: "Add source tables to Warehouse replication", description: "Adds one eligible source table or the currently eligible tables in a schema to an enabled Warehouse. Existing selections and layouts are preserved; already-selected tables are unchanged. Schema selection excludes future tables, except future partitions of selected partition roots. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline remains stopped and requires an explicit start before copying. Initial copy adds source reads; duration is unknown. Unsafe reattachment of retained data is rejected. The response describes configuration and restart acceptance, not completed copy or streaming. Failures may have partial effects; inspect table and pipeline state before retrying.", @@ -445,8 +433,6 @@ export const apiCommands = [ command: ["warehouse", "replication", "remove"], operationId: "v2-remove-warehouse-replication", definition: "v2RemoveWarehouseReplication", - method: "POST", - apiPath: "/v2/projects/{ref}/warehouse/replication/remove", summary: "Remove source tables from Warehouse replication", description: "Removes one selected source table or all selected tables in a schema as a batch. Source PostgreSQL rows and existing Warehouse data are retained. The retained copy stops receiving updates. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline stays stopped. Removing an unselected target is unchanged. Removing the last target leaves Warehouse enabled with an empty selection. Publication changes and restart acceptance do not establish observed exclusion by active replication. Failures may have partial effects; inspect the selection and pipeline before retrying.", @@ -504,8 +490,6 @@ export const apiCommands = [ command: ["warehouse", "replication", "resync"], operationId: "v2-resync-warehouse-replication", definition: "v2ResyncWarehouseReplication", - method: "POST", - apiPath: "/v2/projects/{ref}/warehouse/replication/resync", summary: "Reset and rebuild one Warehouse table", description: "Resets replication for one selected source table using its currently saved layout. Source rows, saved layouts and completed replication state for unrelated tables are preserved. In-progress initial copies of other tables may restart from scratch. The Warehouse copy is deleted and rebuilt when replication resumes; table reads may be unavailable, freshness can lag, and the source incurs additional reads. Stopping and restarting the pipeline interrupts replication for other tables. Duration is unknown. The pipeline must be started and initial sync enabled for the table before the reset. The immediate response retains ETL reset states; it does not establish recopy completion. Inspect warehouse tables get and warehouse status separately. Do not automatically retry an uncertain response: repeating this request may reset the table again. There is no server-side preview, revision check, idempotency key or operation polling.", @@ -563,8 +547,6 @@ export const apiCommands = [ command: ["warehouse", "status"], operationId: "v2-get-warehouse-status", definition: "v2GetWarehouseStatus", - method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/status", summary: "Get consolidated Warehouse status and capabilities", description: "Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions.", @@ -587,8 +569,6 @@ export const apiCommands = [ command: ["warehouse", "tables", "get"], operationId: "v2-get-warehouse-table", definition: "v2GetWarehouseTable", - method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/tables/{table_id}", summary: "Get a table replicated to Warehouse", description: "Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled.", @@ -621,8 +601,6 @@ export const apiCommands = [ command: ["warehouse", "tables", "layout", "get"], operationId: "v2-get-warehouse-table-layout", definition: "v2GetWarehouseTableLayout", - method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/tables/{table_id}/layout", summary: "Get the layout of a table replicated to Warehouse", description: "Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up.", @@ -655,8 +633,6 @@ export const apiCommands = [ command: ["warehouse", "tables", "layout", "update"], operationId: "v2-update-warehouse-table-layout", definition: "v2UpdateWarehouseTableLayout", - method: "PATCH", - apiPath: "/v2/projects/{ref}/warehouse/tables/{table_id}/layout", summary: "Update the layout of a table replicated to Warehouse", description: "Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying.", @@ -740,8 +716,6 @@ export const apiCommands = [ command: ["warehouse", "tables", "list"], operationId: "v2-list-warehouse-tables", definition: "v2ListWarehouseTables", - method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/tables", summary: "List tables replicated to Warehouse", description: "Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up.", @@ -764,8 +738,6 @@ export const apiCommands = [ command: ["warehouse", "teardowns", "get"], operationId: "v2-get-warehouse-teardown", definition: "v2GetWarehouseTeardown", - method: "GET", - apiPath: "/v2/projects/{ref}/warehouse/teardowns/current", summary: "Get Warehouse cleanup status", description: "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.", diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 92464a3b62..f5feac9775 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -42,7 +42,6 @@ import { previewRequest, readBodyOverride, } from "./api-command-request.ts"; -import { withApiCommand } from "./api-command.annotation.ts"; import type { ApiCommandEntry, ApiCommandFlag, @@ -329,7 +328,6 @@ const leafOf = (entry: ApiCommandEntry, entries: ReadonlyArray) Command.withDescription(entry.description ?? entry.summary), Command.withShortDescription(`${entry.summary} (experimental)`), Command.withExamples([{ command: exampleFor(entry), description: entry.summary }]), - withApiCommand({ operationId: entry.operationId }), withPermissions(permissionsOf(entry, resolved)), withStandardErrors, Command.withHandler((flags) => { diff --git a/turbo.json b/turbo.json index cfd309f546..551afd903d 100644 --- a/turbo.json +++ b/turbo.json @@ -95,11 +95,7 @@ "$TURBO_ROOT$/packages/api/src/generated/openapi.json", "$TURBO_ROOT$/packages/api/src/generated/contracts.ts" ], - "outputs": [ - "src/commands/api/generated.ts", - "src/commands/api/generated.schemas.ts", - "src/commands/api/generated.md" - ] + "outputs": ["src/commands/api/generated.ts", "src/commands/api/generated.md"] }, "supabase#test:live": { "cache": false, From 71d9f2e9c9b44178484483be184a367bbe810e78 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 21:15:27 +0100 Subject: [PATCH 40/45] refactor(cli): reject API shapes no warehouse command uses --- apps/cli/scripts/api-command-derive.ts | 123 ++---- .../scripts/api-command-derive.unit.test.ts | 154 ++++--- apps/cli/scripts/api-command-reference.ts | 8 +- apps/cli/scripts/generate-api-commands.ts | 4 +- .../api-command-bindings.integration.test.ts | 5 +- .../src/commands/api/api-command-execute.ts | 27 +- .../cli/src/commands/api/api-command-flags.ts | 6 +- .../src/commands/api/api-command-request.ts | 24 +- .../api-command-shapes.integration.test.ts | 381 ------------------ .../cli/src/commands/api/api-command.model.ts | 26 +- .../api/api-commands.integration.test.ts | 71 ++-- apps/cli/src/commands/api/generated.ts | 65 --- apps/cli/src/commands/api/runtime.ts | 48 +-- 13 files changed, 182 insertions(+), 760 deletions(-) delete mode 100644 apps/cli/src/commands/api/api-command-shapes.integration.test.ts diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index c53794c344..0d1ca59dfb 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -36,9 +36,8 @@ const CREDENTIAL_TOKENS: ReadonlySet = new Set([ const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const; const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u; -/** Headers the request builder owns; a spec that declares them gets no flag. */ -const UNMAPPED_HEADERS: ReadonlySet = new Set(["authorization", "content-type", "accept"]); -const NON_SECRET_HEADERS: ReadonlySet = new Set(["idempotency-key"]); +/** Headers the request builder owns; a spec may declare them, and they get no flag. */ +const CLIENT_HEADERS: ReadonlySet = new Set(["authorization", "content-type", "accept"]); export class ApiCommandGenerationError extends Schema.TaggedError()( "ApiCommandGenerationError", @@ -128,6 +127,8 @@ interface DeriveInput { interface DeriveResult { readonly entries: ReadonlyArray; readonly pollTargets: ReadonlyArray; + /** Success status code of each generated command's operation, for the reference. */ + readonly successStatuses: ReadonlyMap; readonly problems: ReadonlyArray; } @@ -235,19 +236,14 @@ const SCHEMA_LIST_KEYWORDS = ["allOf", "anyOf", "oneOf"] as const; const escapePointer = (segment: string): string => segment.replaceAll("~", "~0").replaceAll("/", "~1"); -interface SuccessResponse { - readonly status: number; - readonly kind: "json" | "text" | "empty"; -} - -/** Classifies the 2xx responses; the first one by status code is the one commands report. */ -const classifySuccess = ( +/** The first 2xx status code; every command and poll target needs its success response to be JSON. */ +const successStatus = ( spec: JsonObject, operation: Operation, fail: (reason: string) => void, -): SuccessResponse | undefined => { +): number | undefined => { const responses = asRecord(operation.node.responses) ?? {}; - const classified: Array = []; + const statuses: Array = []; for (const code of Object.keys(responses).sort()) { if (!code.startsWith("2")) continue; const status = Number(code); @@ -256,24 +252,18 @@ const classifySuccess = ( continue; } const content = asRecord(asRecord(resolve(spec, responses[code]))?.content) ?? {}; - const types = Object.keys(content); - const json = jsonMediaType(content); - if (types.length === 0) { - classified.push({ status, kind: "empty" }); - } else if (json !== undefined) { - classified.push({ status, kind: "json" }); - } else if (types.every((type) => type.startsWith("text/") && type !== "text/event-stream")) { - classified.push({ status, kind: "text" }); - } else { + if (jsonMediaType(content) === undefined) { fail( - `unsupported in this runtime: ${code} response is binary or streaming (${types.join(", ")})`, + `unsupported in this runtime: ${code} response is not JSON (${Object.keys(content).join(", ") || "no content"})`, ); + continue; } + statuses.push(status); } - if (classified.length === 0 && !Object.keys(responses).some((code) => code.startsWith("2"))) { + if (statuses.length === 0 && !Object.keys(responses).some((code) => code.startsWith("2"))) { fail("operation has no 2xx response"); } - return classified[0]; + return statuses[0]; }; const STABILITY_NOTICE = /\s*This endpoint is currently in its \*\*[^*]+\*\* stage\.\s*$/u; @@ -310,9 +300,7 @@ const describeScalar = ( if (schema === undefined) return undefined; if (["anyOf", "oneOf", "allOf", "not"].some((keyword) => keyword in schema)) return undefined; const type = schema.type; - if (type !== "string" && type !== "integer" && type !== "number" && type !== "boolean") { - return undefined; - } + if (type !== "string" && type !== "boolean") return undefined; if (schema.enum === undefined) return { type }; const choices = asArray(schema.enum); if (type !== "string" || !choices.every((choice) => typeof choice === "string")) { @@ -331,6 +319,13 @@ const describeFlagSchema = (spec: JsonObject, raw: unknown): FlagShape | undefin return scalar === undefined ? undefined : { ...scalar, repeatable: false }; }; +/** Whether a schema is a number or integer, or an array of them. */ +const isNumeric = (spec: JsonObject, raw: unknown): boolean => { + const schema = asRecord(resolve(spec, raw)); + const item = schema?.type === "array" ? asRecord(resolve(spec, schema.items)) : schema; + return item?.type === "integer" || item?.type === "number"; +}; + const isSecretField = (spec: JsonObject, raw: unknown): boolean => { const schema = asRecord(resolve(spec, raw)); return ( @@ -652,6 +647,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { const metadata = readMetadata(operations, generated, problems); const hidden = new Map(); const entries: Array = []; + const successStatuses = new Map(); const commandOwners = new Map(); const groupPaths = new Set(); @@ -703,7 +699,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { if (summary === undefined) fail("operation has no summary"); const fields: Array<{ - readonly location: "query" | "header" | "body"; + readonly location: "query" | "body"; readonly key: string; readonly pointer?: string; readonly shape: FlagShape; @@ -744,30 +740,8 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { break; } case "header": { - const lowerName = parameterName.toLowerCase(); - if (UNMAPPED_HEADERS.has(lowerName)) break; - const shape = describeFlagSchema(spec, parameter.schema); - if ( - isSecretField(spec, parameter.schema) || - (credentialLike(parameterName) && !NON_SECRET_HEADERS.has(lowerName)) - ) { - fail( - `unsupported in this runtime: header parameter "${parameterName}" carries a credential, and the dry-run preview masks only body fields`, - ); - } else if (shape === undefined || shape.repeatable) { - fail( - `unsupported in this runtime: header parameter "${parameterName}" is not a scalar`, - ); - } else { - fields.push({ - location: "header", - key: parameterName, - shape, - required: parameter.required === true, - description: - asString(parameter.description) ?? schemaDescription(spec, parameter.schema), - writeOnly: false, - }); + if (!CLIENT_HEADERS.has(parameterName.toLowerCase())) { + fail(`unsupported in this runtime: header parameter "${parameterName}"`); } break; } @@ -837,17 +811,19 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { "unsupported in this runtime: envelope attributes use a schema composition other than an anyOf of closed objects over identical properties", ); } - const isEnvelope = hasEnvelopeShape && attributeFields !== undefined; - const fieldProperties = isEnvelope ? attributeFields.properties : properties; - const required = isEnvelope ? attributeFields.required : asArray(bodySchema.required); - body = isEnvelope - ? { contentType: "application/json", kind: "json-envelope", type: envelopeType } - : { contentType: "application/json", kind: "json-object" }; - for (const [field, schema] of Object.entries(fieldProperties ?? {})) { + const required = attributeFields?.required ?? []; + if (attributeFields === undefined) { + fail("unsupported in this runtime: request body is not a data envelope"); + } else if (envelopeType !== undefined) { + body = { contentType: "application/json", type: envelopeType }; + } + for (const [field, schema] of Object.entries(attributeFields?.properties ?? {})) { const scalarShape = describeFlagSchema(spec, schema); const secret = findSecret(spec, schema, field); if (field === "dry_run") { fail('unsupported in this runtime: server-side "dry_run" body field'); + } else if (scalarShape === undefined && isNumeric(spec, schema)) { + fail(`unsupported in this runtime: numeric body field "${field}"`); } else if (scalarShape === undefined && secret !== undefined) { fail( `unsupported in this runtime: body field "${field}" ${secret === field ? "is a secret" : `holds the secret "${secret}"`}, and the dry-run preview masks only scalar flag values`, @@ -856,9 +832,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { fields.push({ location: "body", key: field, - pointer: isEnvelope - ? `/data/attributes/${escapePointer(field)}` - : `/${escapePointer(field)}`, + pointer: `/data/attributes/${escapePointer(field)}`, shape: scalarShape ?? { type: "json", repeatable: false }, required: required.includes(field), description: schemaDescription(spec, schema), @@ -926,7 +900,7 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { flag: flagName, } : { - location: field.location === "header" ? "header" : "query", + location: "query", name: field.key, source: "flag", flag: flagName, @@ -951,15 +925,16 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { lintWait({ spec, operations, operation, wait, fail }); } - const response = classifySuccess(spec, operation, fail); + const status = successStatus(spec, operation, fail); if (problems.length > failuresBefore || summary === undefined) continue; - if (response === undefined) continue; + if (status === undefined) continue; const description = stripStabilityNotice(asString(operation.node.description)); const policy = input.policies?.[operationId]; if (policy?.confirmDescription && (operation.method === "GET" || !description)) { fail("confirmation details require a mutation with an API description"); continue; } + successStatuses.set(operationId, status); entries.push({ command, operationId, @@ -970,7 +945,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { ...policy, feature: noun.feature, ...(body === undefined ? {} : { body }), - response: { status: response.status, kind: response.kind }, ...(positional === undefined ? {} : { @@ -1024,21 +998,10 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { fail("polling target is missing a summary"); continue; } - const response = classifySuccess(spec, operation, fail); - if (response === undefined) continue; - if (response.kind !== "json") { - fail("polling target must return JSON"); - continue; - } - pollTargets.push({ - operationId, - definition, - summary, - response: { status: response.status, kind: response.kind }, - inspect: inspectId, - }); + if (successStatus(spec, operation, fail) === undefined) continue; + pollTargets.push({ operationId, definition, summary, inspect: inspectId }); } - return { entries, pollTargets, problems }; + return { entries, pollTargets, successStatuses, problems }; } function lintWait(input: { diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index 791177d6a1..e970ceb533 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -149,12 +149,8 @@ describe("deriveApiCommands", () => { expect(result.problems).toEqual([]); const [entry] = result.entries; - expect(entry?.body).toEqual({ - contentType: "application/json", - kind: "json-envelope", - type: "thing", - }); - expect(entry?.response).toEqual({ status: 200, kind: "json" }); + expect(entry?.body).toEqual({ contentType: "application/json", type: "thing" }); + expect([...result.successStatuses]).toEqual([["create-thing", 200]]); expect(entry?.flags.map((flag) => [flag.name, flag.required, flag.repeatable])).toEqual([ ["name", true, false], ["tag", false, true], @@ -192,11 +188,7 @@ describe("deriveApiCommands", () => { expect(result.problems).toEqual([]); const [entry] = result.entries; - expect(entry?.body).toEqual({ - contentType: "application/json", - kind: "json-envelope", - type: "thing", - }); + expect(entry?.body).toEqual({ contentType: "application/json", type: "thing" }); expect(entry?.flags.map((flag) => [flag.name, flag.required])).toEqual([ ["name", true], ["a", false], @@ -227,36 +219,27 @@ describe("deriveApiCommands", () => { ); }); - it("binds plain body fields at the body root", () => { + it("rejects a JSON body that is not a data envelope", () => { const result = derive({ "create-thing": operation({ ...create, requestBody: { content: { "application/json": { - schema: { - type: "object", - properties: { display_name: { type: "string" } }, - }, + schema: { type: "object", properties: { display_name: { type: "string" } } }, }, }, }, - responses: jsonResponse({ $ref: "#/components/schemas/Tags" }), }), }); - expect(result.problems).toEqual([]); - expect(result.entries[0]?.body?.kind).toBe("json-object"); - expect(result.entries[0]?.bindings).toContainEqual({ - location: "body", - name: "display_name", - pointer: "/display_name", - source: "flag", - flag: "display-name", - }); + expect(result.entries).toEqual([]); + expect(result.problems).toEqual([ + "create-thing: unsupported in this runtime: request body is not a data envelope", + ]); }); - it("turns a string enum query parameter into flag choices and records an empty response", () => { + it("turns a string enum query parameter into flag choices", () => { const result = derive({ "list-things": operation({ ...named("list"), @@ -264,13 +247,11 @@ describe("deriveApiCommands", () => { { name: "ref", in: "path", required: true, schema: { type: "string" } }, { name: "sort", in: "query", schema: { type: "string", enum: ["asc", "desc"] } }, ], - responses: { "204": { description: "none" } }, }), }); expect(result.problems).toEqual([]); expect(result.entries[0]?.flags[0]).toMatchObject({ name: "sort", choices: ["asc", "desc"] }); - expect(result.entries[0]?.response).toEqual({ status: 204, kind: "empty" }); }); it("derives a plain token-named query parameter as a flag", () => { @@ -288,16 +269,48 @@ describe("deriveApiCommands", () => { expect(result.entries[0]?.flags[0]).toMatchObject({ name: "page-token" }); }); - it("rejects a binary success response", () => { + it.each([ + ["a binary", { "200": { description: "file", content: { "application/octet-stream": {} } } }], + ["a text", { "200": { description: "text", content: { "text/plain": {} } } }], + ["an empty", { "204": { description: "none" } }], + ])("rejects %s success response", (_label, responses) => { + const result = derive({ "create-thing": operation({ ...create, responses }) }); + + expect(result.entries).toEqual([]); + expect(result.problems.join("\n")).toContain("response is not JSON"); + }); + + it.each([ + ["a numeric body field", { requestBody: envelope({ size: { type: "integer" } }) }, "size"], + [ + "an array of numbers in a body field", + { requestBody: envelope({ sizes: { type: "array", items: { type: "number" } } }) }, + "sizes", + ], + ])("rejects %s", (_label, node, field) => { + const result = derive({ "create-thing": operation({ ...create, ...node }) }); + + expect(result.entries).toEqual([]); + expect(result.problems).toEqual([ + `create-thing: unsupported in this runtime: numeric body field "${field}"`, + ]); + }); + + it("rejects a numeric query parameter", () => { const result = derive({ - "create-thing": operation({ - ...create, - responses: { "200": { description: "file", content: { "application/octet-stream": {} } } }, + "get-thing": operation({ + ...named("get"), + parameters: [ + { name: "ref", in: "path", required: true, schema: { type: "string" } }, + { name: "limit", in: "query", schema: { type: "integer" } }, + ], }), }); expect(result.entries).toEqual([]); - expect(result.problems.join("\n")).toContain("binary or streaming"); + expect(result.problems).toEqual([ + 'get-thing: unsupported in this runtime: query parameter "limit" is not a scalar', + ]); }); describe("nested body fields", () => { @@ -739,12 +752,23 @@ describe("deriveApiCommands", () => { operationId: "get-thing", definition: "v2EnableWarehouse", summary: "Do the thing", - response: { status: 200, kind: "json" }, inspect: "get-inspect", }, ]); }); + it("rejects a poll-only read whose success response is not JSON", () => { + const result = deriveHidden({ + "create-thing": changeThing( + link({ ref: "$request.path.ref", thing_id: "$response.body#/data/id" }), + ), + "get-thing": hiddenWith(poll, { "200": { description: "none" } }), + }); + + expect(result.pollTargets).toEqual([]); + expect(result.problems.join("\n")).toContain("get-thing: unsupported in this runtime"); + }); + it("records a poll-only read once when several mutations link to it", () => { const result = derive( { @@ -1212,7 +1236,7 @@ describe("deriveApiCommands", () => { ], [ "a path parameter that is not a string", - withParameters(pathParameter("version", { schema: { type: "integer" } })), + withParameters(pathParameter("version", { schema: { type: "boolean" } })), 'unsupported in this runtime: path parameter "version" is not a string', ], [ @@ -1255,46 +1279,16 @@ describe("deriveApiCommands", () => { ...extra, }); - it("turns a header parameter into a flag that is required only when the header is", () => { - const result = derive({ - "create-thing": withHeaders( - header("Idempotency-Key", { description: "Deduplicates retries." }), - header("X-Trace-Id", { required: true }), - ), - }); - - expect(result.problems).toEqual([]); - const [entry] = result.entries; - expect(entry?.flags).toEqual([ - { - name: "idempotency-key", - type: "string", - repeatable: false, - required: false, - description: "Deduplicates retries.", - }, - { name: "x-trace-id", type: "string", repeatable: false, required: true }, - ]); - expect(entry?.bindings).toContainEqual({ - location: "header", - name: "Idempotency-Key", - source: "flag", - flag: "idempotency-key", - }); - }); - it.each([ + ["a header parameter", header("Idempotency-Key")], + ["a required header parameter", header("X-Trace-Id", { required: true })], ["a credential-named header", header("X-Api-Key")], - [ - "a password-format header", - header("X-Pin", { schema: { type: "string", format: "password" } }), - ], - ])("rejects %s because the dry-run preview masks only body fields", (_label, parameter) => { + ])("rejects %s", (_label, parameter) => { const result = derive({ "create-thing": withHeaders(parameter) }); expect(result.entries).toEqual([]); expect(result.problems).toEqual([ - `create-thing: unsupported in this runtime: header parameter "${parameter.name}" carries a credential, and the dry-run preview masks only body fields`, + `create-thing: unsupported in this runtime: header parameter "${parameter.name}"`, ]); }); @@ -1311,31 +1305,21 @@ describe("deriveApiCommands", () => { expect(result.entries[0]?.flags).toEqual([]); }); - it.each([ - [ - "a cookie parameter", - { name: "session", in: "cookie", schema: { type: "string" } }, - 'unsupported in this runtime: cookie parameter "session"', - ], - [ - "a header that is not a scalar", - header("X-Tags", { schema: { type: "array", items: { type: "string" } } }), - 'header parameter "X-Tags" is not a scalar', - ], - ["a header named like a body field", header("name"), '"name" is used by more than one of'], - ])("rejects %s", (_label, parameter, message) => { + it("rejects a cookie parameter", () => { const result = derive({ "create-thing": operation({ ...create, requestBody: envelope({}), parameters: [ { name: "ref", in: "path", required: true, schema: { type: "string" } }, - parameter, + { name: "session", in: "cookie", schema: { type: "string" } }, ], }), }); - expect(result.problems.join("\n")).toContain(message); + expect(result.problems.join("\n")).toContain( + 'unsupported in this runtime: cookie parameter "session"', + ); }); }); diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts index 0c3a51bf57..ec0a374479 100644 --- a/apps/cli/scripts/api-command-reference.ts +++ b/apps/cli/scripts/api-command-reference.ts @@ -10,6 +10,8 @@ import type { export interface ApiCommandReferenceInput { readonly entries: ReadonlyArray; readonly pollTargets: ReadonlyArray; + /** Success status code per operation id. */ + readonly successStatuses: ReadonlyMap; } const code = (text: string): string => `\`${text}\``; @@ -124,9 +126,7 @@ const waitSection = ( const bodyLine = (entry: ApiCommandEntry): string | undefined => { const { body } = entry; if (body === undefined) return undefined; - return body.kind === "json-envelope" - ? `JSON envelope ${code(`data.type = ${body.type ?? ""}`)}, fields under ${code("data.attributes")}` - : "JSON object"; + return `JSON envelope ${code(`data.type = ${body.type}`)}, fields under ${code("data.attributes")}`; }; const commandSection = ( @@ -147,7 +147,7 @@ const commandSection = ( ...(entry.confirmDescription ? ["- Consent: prints the API description before the interactive confirmation."] : []), - `- Request: ${route(entry)} (${code(entry.operationId)}), success ${entry.response.status} ${entry.response.kind}.`, + `- Request: ${route(entry)} (${code(entry.operationId)}), success ${input.successStatuses.get(entry.operationId)} json.`, ...(body === undefined ? [] : [`- Body: ${body}.`]), ...(argument === undefined ? [] : [`- ${argument}`]), ...(flags.length === 0 diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index d4359eeae5..6fb89978cf 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -89,7 +89,7 @@ const main = Effect.gen(function* () { return yield* new ApiCommandGenerationError({ problems: ["openapi.json is not an object"] }); } - const { entries, pollTargets, problems } = deriveApiCommands({ + const { entries, pollTargets, successStatuses, problems } = deriveApiCommands({ spec, generated: generatedOperations, policies: commandPolicies, @@ -106,7 +106,7 @@ const main = Effect.gen(function* () { }, { relative: "src/commands/api/generated.md", - source: renderApiCommandReference({ entries, pollTargets }), + source: renderApiCommandReference({ entries, pollTargets, successStatuses }), }, ]; diff --git a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts index 280b2858cf..1b5fcf97ba 100644 --- a/apps/cli/src/commands/api/api-command-bindings.integration.test.ts +++ b/apps/cli/src/commands/api/api-command-bindings.integration.test.ts @@ -94,9 +94,6 @@ const sampleOf = (schema: unknown): unknown => { switch (node["type"]) { case "boolean": return true; - case "integer": - case "number": - return 1; case "array": return [sampleOf(node["items"]), `${String(sampleOf(node["items"]))}-2`]; case "string": { @@ -167,7 +164,7 @@ const inputsOf = ( const [firstBranch] = asList(attributes["anyOf"]).map(resolveRef); const container = firstBranch ?? (envelope ? attributes : operation.requestSchema); const required = asList(container["required"]); - const scalarTypes = ["boolean", "integer", "number", "string"]; + const scalarTypes = ["boolean", "string"]; const fields = Object.entries(asRecord(container["properties"])).map(([field, schema]): Input => { const node = resolveRef(schema); const scalar = diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index 7ba3ae45ba..6f18680324 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -149,31 +149,22 @@ const parseResponse = (response: ApiCommandResponse): unknown => Option.getOrUndefined(decodeJsonText(textDecoder.decode(response.bytes))); /** - * Writes a success response. `json` passes JSON bytes through untouched, prints text as a JSON - * string and an empty body as `null`; `text` renders the response for a person. + * Writes a success response. JSON bytes pass through untouched in machine output; a 2xx without a + * body prints as `null` there and as `Done.` for a person. */ export const writeApiResponse = Effect.fnUntraced(function* ( - entry: Pick, response: ApiCommandResponse, format: ApiOutputFormat, ) { const output = yield* Output; - const hasBody = response.bytes.length > 0; - const text = textDecoder.decode(response.bytes); - if (format === "text") { - if (!hasBody || entry.response.kind === "empty") return yield* output.raw("Done.\n"); - const parsed = entry.response.kind === "json" ? decodeJsonText(text) : Option.none(); - if (Option.isNone(parsed)) return yield* output.raw(text.endsWith("\n") ? text : `${text}\n`); - return yield* output.raw(renderResponseText(parsed.value)); + if (response.bytes.length === 0) { + return yield* output.raw(format === "text" ? "Done.\n" : "null\n"); } - if (entry.response.kind === "json" && hasBody) return yield* output.rawBytes(response.bytes); - const document = - !hasBody || entry.response.kind === "empty" - ? null - : entry.response.kind === "text" - ? text - : Option.getOrElse(decodeJsonText(text), () => text); - return yield* output.raw(`${encodeJsonValue(document)}\n`); + if (format === "json") return yield* output.rawBytes(response.bytes); + const text = textDecoder.decode(response.bytes); + const parsed = decodeJsonText(text); + if (Option.isNone(parsed)) return yield* output.raw(text.endsWith("\n") ? text : `${text}\n`); + return yield* output.raw(renderResponseText(parsed.value)); }); interface WaitInput { diff --git a/apps/cli/src/commands/api/api-command-flags.ts b/apps/cli/src/commands/api/api-command-flags.ts index 1dfff13153..865cc43d15 100644 --- a/apps/cli/src/commands/api/api-command-flags.ts +++ b/apps/cli/src/commands/api/api-command-flags.ts @@ -15,17 +15,13 @@ const scalarFlag = (flag: ApiCommandFlag): Flag.Flag return Flag.String(flag.name); case "json": return Flag.String(flag.name).pipe(Flag.withMetavar("json")); - case "integer": - return Flag.Int(flag.name); - case "number": - return Flag.Finite(flag.name); case "boolean": return Flag.Boolean(flag.name); } }; /** Where a generated flag's value lands in the request. */ -export type ApiFlagLocation = "query" | "header" | "body"; +export type ApiFlagLocation = "query" | "body"; const describedFlag = (flag: ApiCommandFlag, location: ApiFlagLocation): string => { const base = flag.description ?? `Set ${flag.name}.`; diff --git a/apps/cli/src/commands/api/api-command-request.ts b/apps/cli/src/commands/api/api-command-request.ts index 895c0ae3ce..3ee613bc93 100644 --- a/apps/cli/src/commands/api/api-command-request.ts +++ b/apps/cli/src/commands/api/api-command-request.ts @@ -82,10 +82,7 @@ export const readBodyOverride = Effect.fn("api-command.read-body")(function* (in const initialBody = (entry: ApiCommandEntry): Readonly> | undefined => { if (entry.body === undefined) return undefined; - if (entry.body.kind === "json-envelope") { - return { data: { type: entry.body.type, attributes: {} } }; - } - return {}; + return { data: { type: entry.body.type, attributes: {} } }; }; const parseJsonFlag = (flag: string, text: ApiFlagValue) => @@ -100,7 +97,7 @@ const parseJsonFlag = (flag: string, text: ApiFlagValue) => ); /** - * The flat operation input `{...bodyFields, ...query, ...headers, ref, }`. A body + * The flat operation input `{...bodyFields, ...query, ref, }`. A body * override is the starting point when given, else the synthesized envelope; only flags that were * passed are written, each at its own pointer. An override may only carry top-level fields the * request body declares, and the path values are applied last so body data cannot retarget the @@ -132,7 +129,6 @@ export const assembleInput = Effect.fnUntraced(function* ( ); let body: unknown = Option.getOrElse(bodyOverride, () => initialBody(entry)); const query: Record = {}; - const headers: Record = {}; const positional: Record = {}; for (const binding of entry.bindings) { if (binding.source === "argument") { @@ -151,7 +147,6 @@ export const assembleInput = Effect.fnUntraced(function* ( const value = flagValues[binding.flag]; if (value === undefined || Option.isNone(value)) continue; if (binding.location === "query") query[binding.name] = value.value; - if (binding.location === "header") headers[binding.name] = value.value; if (binding.location === "body") { const parsed = jsonFlagNames.has(binding.flag) ? yield* parseJsonFlag(binding.flag, value.value) @@ -159,7 +154,7 @@ export const assembleInput = Effect.fnUntraced(function* ( body = writePointer(body, binding.pointer, parsed); } } - return { ...(isRecord(body) ? body : {}), ...query, ...headers, ref, ...positional }; + return { ...(isRecord(body) ? body : {}), ...query, ref, ...positional }; }); type Path = ReadonlyArray; @@ -217,11 +212,7 @@ const flagAt = (entry: ApiCommandEntry, path: Path) => { for (const binding of entry.bindings) { if (binding.source !== "flag") continue; if (binding.location === "body" && binding.pointer === pointer) return binding; - if ( - (binding.location === "query" || binding.location === "header") && - path.length === 1 && - path[0] === binding.name - ) { + if (binding.location === "query" && path.length === 1 && path[0] === binding.name) { return binding; } } @@ -331,12 +322,7 @@ export const consentDetails = (entry: ApiCommandEntry, decoded: object): Readonl const { pathParams } = definitionOf(entry); const preview = previewRequest(entry, decoded); const attributes = readPointer(preview.body, "/data/attributes"); - const bodyFields = - entry.body?.kind === "json-envelope" && isRecord(attributes) - ? attributes - : isRecord(preview.body) - ? preview.body - : {}; + const bodyFields = isRecord(attributes) ? attributes : {}; return [ ...pathParams .filter((name) => name !== "ref") diff --git a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts b/apps/cli/src/commands/api/api-command-shapes.integration.test.ts deleted file mode 100644 index 8724c20ad4..0000000000 --- a/apps/cli/src/commands/api/api-command-shapes.integration.test.ts +++ /dev/null @@ -1,381 +0,0 @@ -import { BunServices } from "@effect/platform-bun"; -import { describe, expect, it } from "@effect/vitest"; -import { openApiOperationIdMap } from "@supabase/api/effect"; -import openApiSpec from "@supabase/api/openapi.json"; -import { Console, Effect, Exit, FileSystem, Layer, Path, Predicate, Schema, Stdio } from "effect"; -import { CliOutput, Command } from "effect/cli"; - -import { deriveApiCommands } from "../../../scripts/api-command-derive.ts"; -import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; -import { ExperimentalFlag, GLOBAL_FLAGS } from "../../command-internal/global-flags.ts"; -import { textCliOutputFormatter } from "../../shared/output/text-formatter.ts"; -import { - VALID_REF, - VALID_TOKEN, - buildTestRuntime, - mockCommandPlatformApi, - mockCommandSettings, - useTempWorkdir, - withConfigEnv, -} from "../../../tests/helpers/command-mocks.ts"; -import { - fakeConsole, - mockOutput, - mockRuntimeInfo, - mockStdin, - mockTelemetryRuntime, - mockTty, -} from "../../../tests/helpers/mocks.ts"; -import type { ApiNoun } from "./api-command-policy.ts"; -import { withApiCommands } from "./runtime.ts"; - -const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown)); -const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); - -const isRecord = (value: unknown): value is Record => - Predicate.isObject(value) && !Array.isArray(value); - -const fixtureNoun: ApiNoun = { - description: "Fixture commands", - feature: "warehouse", - groups: { - migrations: "Migration fixtures", - auth: "Auth fixtures", - "auth.signing-keys": "Signing key fixtures", - jit: "JIT access fixtures", - keys: "Legacy key fixtures", - }, -}; - -const FIXTURE_OPERATIONS = { - "v1-apply-a-migration": { group: "fixture.migrations", method: "create" }, - "v1-get-a-migration": { group: "fixture.migrations", method: "get" }, - "v1-get-project-signing-key": { group: "fixture.auth.signing-keys", method: "get" }, - "v1-update-jit-access": { group: "fixture.jit", method: "update" }, - "v1-update-project-legacy-api-keys": { group: "fixture.keys", method: "update" }, -}; - -/** The committed spec with an experimental `x-operation` on a few real operations. */ -const fixtureSpec = () => { - const spec: Record = structuredClone(openApiSpec); - for (const item of Object.values(isRecord(spec["paths"]) ? spec["paths"] : {})) { - for (const operation of Object.values(isRecord(item) ? item : {})) { - if (!isRecord(operation)) continue; - const operationId = String(operation["operationId"]); - if (!Object.hasOwn(FIXTURE_OPERATIONS, operationId)) continue; - operation["x-operation"] = Reflect.get(FIXTURE_OPERATIONS, operationId); - operation["x-scalar-stability"] = "experimental"; - } - } - return spec; -}; - -const derived = deriveApiCommands({ - spec: fixtureSpec(), - generated: Object.keys(FIXTURE_OPERATIONS), - nouns: { fixture: fixtureNoun }, - operationIdMap: openApiOperationIdMap, - handWrittenRoots: new Set(), -}); - -const fixtureRoot = Command.make("supabase").pipe( - Command.withSubcommands( - withApiCommands([], [fixtureNoun.feature], { - nouns: { fixture: fixtureNoun }, - entries: derived.entries, - }), - ), - Command.withGlobalFlags(GLOBAL_FLAGS), -); - -const MIGRATION_VERSION = "20250312000000"; -const SIGNING_KEY_ID = "33333333-3333-4333-8333-333333333333"; -const MIGRATIONS_PATH = `/v1/projects/${VALID_REF}/database/migrations`; -const TARGET_LOOKUP_PATH = `/v1/projects/${VALID_REF}`; - -interface Sent { - readonly method: string; - readonly path: string; - readonly headers: Headers; - readonly body: unknown; -} - -/** Replaces `globalThis.fetch` while the command runs; every API request is recorded and answered with `{}`. */ -const withApi = (sent: Array) => { - const answer = () => - new Response("{}", { status: 200, headers: { "content-type": "application/json" } }); - const stub = (input: string | URL | Request, init?: RequestInit): Promise => { - const request = input instanceof Request ? input : new Request(String(input), init); - const url = new URL(request.url); - if (url.pathname === TARGET_LOOKUP_PATH) return Promise.resolve(answer()); - return request.text().then((text) => { - sent.push({ - method: request.method, - path: url.pathname, - headers: request.headers, - body: text === "" ? undefined : decodeJson(text), - }); - return answer(); - }); - }; - return (body: Effect.Effect) => - Effect.acquireUseRelease( - Effect.sync(() => { - const previous = globalThis.fetch; - globalThis.fetch = Object.assign(stub, { preconnect: previous.preconnect }); - return previous; - }), - () => body, - (previous) => - Effect.sync(() => { - globalThis.fetch = previous; - }), - ); -}; - -const tempRoot = useTempWorkdir("supabase-api-shapes-int-"); - -const run = (argv: ReadonlyArray) => { - const args = [...argv, `--remote=${VALID_REF}`, "--yes"]; - const sent: Array = []; - const out = mockOutput({ format: "text" }); - const { console, calls } = fakeConsole(); - const layer = Layer.mergeAll( - buildTestRuntime({ - out, - api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), - cliSettings: mockCommandSettings({ workdir: tempRoot.current }), - tty: mockTty({ stdinIsTty: false, stdoutIsTty: false }), - stdin: mockStdin(false), - cliArgs: args, - }), - BunServices.layer, - CliOutput.layer(textCliOutputFormatter()), - Layer.succeed(ExperimentalFlag, false), - mockTelemetryRuntime({ configDir: tempRoot.current }), - mockRuntimeInfo({ cwd: tempRoot.current, homeDir: tempRoot.current }), - Stdio.layerTest({ args: Effect.succeed(args) }), - ); - const effect = withConfigEnv( - { SUPABASE_ACCESS_TOKEN: VALID_TOKEN, SUPABASE_NO_KEYRING: "1" }, - Command.runWith(fixtureRoot, { version: "0.0.0-test" })(args), - ).pipe(withApi(sent), Effect.provideService(Console.Console, console), Effect.provide(layer)); - return { sent, out, help: () => calls.join("\n"), effect }; -}; - -describe("generated command shapes", () => { - it("derives the fixture commands without problems", () => { - expect(derived.problems).toEqual([]); - expect(derived.entries.map((entry) => entry.command.join(" "))).toEqual([ - "fixture auth signing-keys get", - "fixture jit update", - "fixture keys update", - "fixture migrations create", - "fixture migrations get", - ]); - }); - - describe("a positional path parameter", () => { - it.effect("is path-encoded into the request of a three-word command", () => { - const { sent, effect } = run(["fixture", "migrations", "get", MIGRATION_VERSION]); - return Effect.gen(function* () { - yield* effect; - expect(sent.map(({ method, path }) => `${method} ${path}`)).toEqual([ - `GET ${MIGRATIONS_PATH}/${MIGRATION_VERSION}`, - ]); - }); - }); - - it.effect("reaches a four-word command through two nested groups", () => { - const { sent, effect } = run(["fixture", "auth", "signing-keys", "get", SIGNING_KEY_ID]); - return Effect.gen(function* () { - yield* effect; - expect(sent.map(({ path }) => path)).toEqual([ - `/v1/projects/${VALID_REF}/config/auth/signing-keys/${SIGNING_KEY_ID}`, - ]); - }); - }); - - it.effect("fails the parse and sends nothing when it is missing", () => { - const { sent, help, effect } = run(["fixture", "migrations", "get"]); - return Effect.gen(function* () { - const exit = yield* Effect.exit(effect); - expect(Exit.isFailure(exit)).toBe(true); - expect(help()).toContain(""); - expect(sent).toEqual([]); - }); - }); - - it.effect.each(["", ".."])( - "rejects the value %j as a usage error and sends nothing", - (value) => { - const { sent, effect } = run(["fixture", "migrations", "get", value]); - return Effect.gen(function* () { - const failure = yield* Effect.flip(effect); - expect(failure).toBeInstanceOf(ApiCommandUsageError); - expect(failure).toMatchObject({ - message: ' must not be empty, "." or "..".', - }); - expect(sent).toEqual([]); - }); - }, - ); - - it.effect("is interpolated into the dry-run path", () => { - const { sent, out, effect } = run([ - "fixture", - "migrations", - "get", - MIGRATION_VERSION, - "--dry-run", - ]); - return Effect.gen(function* () { - yield* effect; - expect(sent).toEqual([]); - expect(decodeJson(out.stdoutText)).toEqual({ - method: "GET", - path: `${MIGRATIONS_PATH}/${MIGRATION_VERSION}`, - query: {}, - headers: {}, - body: null, - }); - }); - }); - }); - - describe("a header flag", () => { - const create = ["fixture", "migrations", "create", "--query", "select 1"]; - - it.effect("is sent as the header when passed", () => { - const { sent, effect } = run([...create, "--idempotency-key", "retry-1"]); - return Effect.gen(function* () { - yield* effect; - expect(sent.map((request) => request.headers.get("idempotency-key"))).toEqual(["retry-1"]); - }); - }); - - it.effect("is left out of the request when absent", () => { - const { sent, effect } = run(create); - return Effect.gen(function* () { - yield* effect; - expect(sent.map((request) => request.headers.has("idempotency-key"))).toEqual([false]); - }); - }); - - it.effect("appears under headers in the dry-run document", () => { - const { out, effect } = run([...create, "--idempotency-key", "retry-1", "--dry-run"]); - return Effect.gen(function* () { - yield* effect; - expect(decodeJson(out.stdoutText)).toEqual({ - method: "POST", - path: MIGRATIONS_PATH, - query: {}, - headers: { "Idempotency-Key": "retry-1" }, - body: { query: "select 1" }, - }); - }); - }); - }); - - describe("a nested body field", () => { - const USER_ID = "55555555-5555-4555-8555-555555555555"; - const roles = [ - { role: "postgres", allowed_networks: { allowed_cidrs: [{ cidr: "10.0.0.0/8" }] } }, - ]; - const update = ["fixture", "jit", "update"]; - - it.effect("is sent from --body together with a flag-supplied scalar field", () => { - const { sent, effect } = run([ - ...update, - "--user-id", - USER_ID, - "--body", - encodeJson({ roles }), - ]); - return Effect.gen(function* () { - yield* effect; - expect(sent.map(({ method, path }) => `${method} ${path}`)).toEqual([ - `PUT /v1/projects/${VALID_REF}/database/jit`, - ]); - expect(sent.map((request) => request.body)).toEqual([{ user_id: USER_ID, roles }]); - }); - }); - - it.effect("is sent from --file together with a flag-supplied scalar field", () => { - const { sent, effect } = run([ - ...update, - "--user-id", - USER_ID, - "--file", - `${tempRoot.current}/jit.json`, - ]); - return Effect.gen(function* () { - const fs = yield* FileSystem.FileSystem; - const path = yield* Path.Path; - yield* fs.writeFileString(path.join(tempRoot.current, "jit.json"), encodeJson({ roles })); - yield* effect; - expect(sent.map((request) => request.body)).toEqual([{ user_id: USER_ID, roles }]); - }).pipe(Effect.provide(BunServices.layer)); - }); - - it.effect("is a JSON-valued flag in --help, named after the field", () => { - const { help, effect } = run([...update, "--help"]); - return Effect.gen(function* () { - yield* effect; - const rolesLine = help() - .split("\n") - .find((line) => line.includes("--roles ")); - expect(rolesLine).toContain("Takes a JSON value."); - expect(help()).not.toContain("--role "); - }); - }); - - it.effect("is sent from its own flag", () => { - const { sent, effect } = run([...update, "--user-id", USER_ID, "--roles", encodeJson(roles)]); - return Effect.gen(function* () { - yield* effect; - expect(sent.map((request) => request.body)).toEqual([{ user_id: USER_ID, roles }]); - }); - }); - }); - - describe("a required query flag", () => { - it.effect("reports a missing flag with the plain hint and sends nothing", () => { - const { sent, effect } = run(["fixture", "keys", "update"]); - return Effect.gen(function* () { - const failure = yield* effect.pipe(Effect.flip); - expect(failure).toMatchObject({ hint: "Pass the flag." }); - expect(sent).toEqual([]); - }); - }); - }); - - describe("help", () => { - it.effect("lists the nested group under its parent", () => { - const { help, effect } = run(["fixture", "auth", "--help"]); - return Effect.gen(function* () { - yield* effect; - expect(help()).toContain("signing-keys"); - expect(help()).toContain("Signing key fixtures (experimental)"); - }); - }); - - it.effect("shows the positional in the usage and the header as an optional flag", () => { - const read = run(["fixture", "migrations", "get", "--help"]); - const create = run(["fixture", "migrations", "create", "--help"]); - return Effect.gen(function* () { - yield* read.effect; - yield* create.effect; - expect(read.help()).toContain(""); - const flagLine = create - .help() - .split("\n") - .find((line) => line.includes("--idempotency-key ")); - expect(flagLine).toContain( - "A unique key to ensure the same migration is tracked only once.", - ); - expect(flagLine).not.toContain("Required"); - }); - }); - }); -}); diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index 91d2c89b12..7f2ce7d311 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -25,13 +25,6 @@ export type ApiCommandBinding = /** Name of the flag that supplies the value. */ readonly flag: string; } - | { - readonly location: "header"; - /** Header name as declared in the spec. */ - readonly name: string; - readonly source: "flag"; - readonly flag: string; - } | { readonly location: "body"; /** Body field name. */ @@ -42,12 +35,12 @@ export type ApiCommandBinding = readonly flag: string; }; -/** One flag of a generated command, derived from a query parameter, a header parameter or a request body field. */ +/** One flag of a generated command, derived from a query parameter or a request body field. */ export interface ApiCommandFlag { /** Kebab-case flag name without the leading dashes. */ readonly name: string; /** `json` takes a JSON value for a body field that is not a scalar or an array of scalars. */ - readonly type: "string" | "integer" | "number" | "boolean" | "json"; + readonly type: "string" | "boolean" | "json"; readonly choices?: readonly string[]; readonly repeatable: boolean; readonly required: boolean; @@ -85,17 +78,11 @@ export interface ApiCommandEntry { readonly confirmDescription?: true; /** Feature that gates the command's noun. */ readonly feature: string; - /** Request body shape; `json-envelope` bodies wrap fields in `data.attributes`. */ + /** Request body: an envelope that wraps the fields in `data.attributes`. */ readonly body?: { readonly contentType: "application/json"; - readonly kind: "json-object" | "json-envelope"; /** The envelope's `data.type` value. */ - readonly type?: string; - }; - /** Success response shape from the first 2xx response. */ - readonly response: { - readonly status: number; - readonly kind: "json" | "text" | "empty"; + readonly type: string; }; /** The positional argument that carries the operation's one non-`ref` path parameter. */ readonly argument?: { @@ -108,10 +95,7 @@ export interface ApiCommandEntry { } /** The operation a wait polls: a generated command's entry or a hidden {@link ApiPollTarget}. */ -export type ApiPollRead = Pick< - ApiCommandEntry, - "operationId" | "definition" | "summary" | "response" ->; +export type ApiPollRead = Pick; /** A response-linked read used for polling without registering a CLI command. */ export interface ApiPollTarget extends ApiPollRead { diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 4bc27fbb06..3a3007a864 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -70,7 +70,6 @@ const entryOf = (path: string): ApiCommandEntry => { }; const enable = entryOf("warehouse enable"); -const status = entryOf("warehouse status"); const ENABLE_PATH = `/v2/projects/${VALID_REF}/warehouse/enable`; const STATUS_PATH = `/v2/projects/${VALID_REF}/warehouse/status`; @@ -917,6 +916,19 @@ describe("generated warehouse commands", () => { }); }, ); + + it.effect.each(["", ".."])( + "rejects the table id %j as a usage error and sends nothing", + (value) => { + const { sent, run } = setup(["warehouse", "tables", "get", value], { route: ok(body) }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(failure).toBeInstanceOf(ApiCommandUsageError); + expect(failure).toMatchObject({ message: ' must not be empty, "." or "..".' }); + expect(sent).toEqual([]); + }); + }, + ); }); describe("warehouse tables layout get", () => { const layoutPath = `/v2/projects/${VALID_REF}/warehouse/tables/16385/layout`; @@ -2266,52 +2278,25 @@ describe("generated warehouse commands", () => { }); describe("generic response writing", () => { - const fixture: ApiCommandEntry = { - ...status, - command: ["fixture", "read"], - }; - const fixtureRoot = (entry: ApiCommandEntry) => - Command.make("supabase").pipe( - Command.withSubcommands( - withApiCommands([], ["warehouse"], { - nouns: { fixture: { description: "Fixture commands", feature: "warehouse" } }, - entries: [entry], - }), - ), - Command.withGlobalFlags(ROOT_GLOBAL_FLAGS), - ); + it.effect("writes a JSON body byte for byte, unknown fields and spacing included", () => { + const raw = '{"z": 1, "known": {"future": [1, 2]}}'; + const { out, run } = setup(["warehouse", "status"], { + route: () => ({ status: 200, body: raw }), + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(raw); + }); + }); - it.effect.each([ - { - name: "a text body as one JSON string", - kind: "text" as const, - reply: { status: 200, body: "plain text\nsecond line" }, - stdout: '"plain text\\nsecond line"\n', - }, - { - name: "an empty body as null", - kind: "empty" as const, - reply: { status: 204 }, - stdout: "null\n", - }, - { - name: "a JSON body byte for byte, unknown fields and spacing included", - kind: "json" as const, - reply: { status: 200, body: '{"z": 1, "known": {"future": [1, 2]}}' }, - stdout: '{"z": 1, "known": {"future": [1, 2]}}', - }, - ])("writes $name", ({ kind, reply, stdout }) => { - const entry: ApiCommandEntry = { - ...fixture, - response: { status: reply.status, kind }, - }; - const { out, run } = setup(["fixture", "read"], { - root: fixtureRoot(entry), - route: () => reply, + it.effect("writes an empty accepted body as null", () => { + const { out, run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: () => ({ status: 202 }), }); return Effect.gen(function* () { yield* run; - expect(out.stdoutText).toBe(stdout); + expect(out.stdoutText).toBe("null\n"); }); }); }); diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 5288702a9a..9bae03d156 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -11,10 +11,6 @@ export const apiCommands = [ "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.", readOnly: true, feature: "warehouse", - response: { - status: 200, - kind: "json", - }, flags: [], bindings: [ { @@ -33,10 +29,6 @@ export const apiCommands = [ "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.", readOnly: false, feature: "warehouse", - response: { - status: 202, - kind: "json", - }, flags: [ { name: "delete-data", @@ -82,13 +74,8 @@ export const apiCommands = [ feature: "warehouse", body: { contentType: "application/json", - kind: "json-envelope", type: "warehouse_setup", }, - response: { - status: 202, - kind: "json", - }, flags: [ { name: "warehouse-region", @@ -193,10 +180,6 @@ export const apiCommands = [ "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.", readOnly: true, feature: "warehouse", - response: { - status: 200, - kind: "json", - }, flags: [ { name: "attributes", @@ -287,10 +270,6 @@ export const apiCommands = [ "Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.", readOnly: true, feature: "warehouse", - response: { - status: 200, - kind: "json", - }, flags: [ { name: "attributes", @@ -384,13 +363,8 @@ export const apiCommands = [ feature: "warehouse", body: { contentType: "application/json", - kind: "json-envelope", type: "warehouse_replication_change", }, - response: { - status: 202, - kind: "json", - }, flags: [ { name: "schema", @@ -441,13 +415,8 @@ export const apiCommands = [ feature: "warehouse", body: { contentType: "application/json", - kind: "json-envelope", type: "warehouse_replication_change", }, - response: { - status: 202, - kind: "json", - }, flags: [ { name: "schema", @@ -498,13 +467,8 @@ export const apiCommands = [ feature: "warehouse", body: { contentType: "application/json", - kind: "json-envelope", type: "warehouse_replication_resync", }, - response: { - status: 202, - kind: "json", - }, flags: [ { name: "schema", @@ -552,10 +516,6 @@ export const apiCommands = [ "Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions.", readOnly: true, feature: "warehouse", - response: { - status: 200, - kind: "json", - }, flags: [], bindings: [ { @@ -574,10 +534,6 @@ export const apiCommands = [ "Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled.", readOnly: true, feature: "warehouse", - response: { - status: 200, - kind: "json", - }, argument: { name: "table-id", description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", @@ -606,10 +562,6 @@ export const apiCommands = [ "Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up.", readOnly: true, feature: "warehouse", - response: { - status: 200, - kind: "json", - }, argument: { name: "table-id", description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", @@ -640,13 +592,8 @@ export const apiCommands = [ feature: "warehouse", body: { contentType: "application/json", - kind: "json-envelope", type: "warehouse_table_layout", }, - response: { - status: 202, - kind: "json", - }, argument: { name: "table-id", description: "Source Postgres table OID from the Warehouse tables list.", @@ -721,10 +668,6 @@ export const apiCommands = [ "Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up.", readOnly: true, feature: "warehouse", - response: { - status: 200, - kind: "json", - }, flags: [], bindings: [ { @@ -743,10 +686,6 @@ export const apiCommands = [ "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.", readOnly: true, feature: "warehouse", - response: { - status: 200, - kind: "json", - }, flags: [ { name: "operation-id", @@ -786,10 +725,6 @@ export const apiPollTargets = [ operationId: "v2-get-warehouse-setup", definition: "v2GetWarehouseSetup", summary: "Get Warehouse initial synchronization status", - response: { - status: 200, - kind: "json", - }, inspect: "v2-get-warehouse-status", }, ] as const satisfies readonly ApiPollTarget[]; diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index f5feac9775..4c8b236a99 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -60,16 +60,13 @@ interface ResolvedWait { readonly statusEntry: ApiCommandEntry; } -const resolveWait = ( - entry: ApiCommandEntry, - entries: ReadonlyArray, -): ResolvedWait | undefined => { +const resolveWait = (entry: ApiCommandEntry): ResolvedWait | undefined => { const { wait } = entry; if (wait === undefined) return undefined; - const publicRead = entries.find((candidate) => candidate.operationId === wait.read); + const publicRead = apiCommands.find((candidate) => candidate.operationId === wait.read); if (publicRead !== undefined) return { wait, readEntry: publicRead, statusEntry: publicRead }; const hidden = apiPollTargets.find((candidate) => candidate.operationId === wait.read); - const inspect = entries.find((candidate) => candidate.operationId === hidden?.inspect); + const inspect = apiCommands.find((candidate) => candidate.operationId === hidden?.inspect); return hidden === undefined || inspect === undefined ? undefined : { wait, readEntry: hidden, statusEntry: inspect }; @@ -265,13 +262,13 @@ const handle = Effect.fn("api-command.run")(function* ( }), ); yield* Effect.annotateCurrentSpan("run.outcome", "waited"); - return yield* writeApiResponse(resolved.readEntry, settled, format); + return yield* writeApiResponse(settled, format); } const response = yield* withTask(progress, summaryText(entry), () => sendApiRequest(api, entry, decoded), ); yield* Effect.annotateCurrentSpan("run.outcome", "sent"); - return yield* writeApiResponse(entry, response, format); + return yield* writeApiResponse(response, format); }).pipe(Effect.ensuring(flags.dryRun ? Effect.void : cache.cache(ref))); }).pipe(Effect.ensuring(telemetryState.flush)); }); @@ -320,9 +317,9 @@ const permissionsOf = (entry: ApiCommandEntry, resolved: ResolvedWait | undefine ); }; -const leafOf = (entry: ApiCommandEntry, entries: ReadonlyArray) => { +const leafOf = (entry: ApiCommandEntry) => { const verb = entry.command[entry.command.length - 1] ?? entry.operationId; - const resolved = resolveWait(entry, entries); + const resolved = resolveWait(entry); const config = flagConfig(entry, resolved !== undefined); return Command.make(verb, config).pipe( Command.withDescription(entry.description ?? entry.summary), @@ -354,21 +351,15 @@ type ApiLeaf = ReturnType; /** A generated group: it fails and requires what its generated leaves do. */ type ApiGroup = Command.Command, Command.Services>; -/** The noun definitions and entries the generated commands are built from. */ -interface ApiCommandSource { - readonly nouns: Readonly>; - readonly entries: ReadonlyArray; -} - const startsWith = (command: ReadonlyArray, prefix: ReadonlyArray): boolean => prefix.every((word, index) => command[index] === word); const leafCache = new WeakMap(); -const cachedLeaf = (entry: ApiCommandEntry, entries: ReadonlyArray): ApiLeaf => { +const cachedLeaf = (entry: ApiCommandEntry): ApiLeaf => { const cached = leafCache.get(entry); if (cached !== undefined) return cached; - const leaf = leafOf(entry, entries); + const leaf = leafOf(entry); leafCache.set(entry, leaf); return leaf; }; @@ -377,13 +368,9 @@ const groupDescription = (path: ReadonlyArray, noun: ApiNoun): string | path.length === 1 ? noun.description : noun.groups?.[path.slice(1).join(".")]; /** The group at `path`, holding the generated commands below it. */ -const groupAt = ( - path: ReadonlyArray, - noun: ApiNoun, - entries: ReadonlyArray, -): ApiGroup => { +const groupAt = (path: ReadonlyArray, noun: ApiNoun): ApiGroup => { const name = path[path.length - 1] ?? ""; - const under = entries.filter((entry) => startsWith(entry.command, path)); + const under = apiCommands.filter((entry) => startsWith(entry.command, path)); const childNames = new Set( under.flatMap((entry) => entry.command.length > path.length + 1 @@ -393,8 +380,8 @@ const groupAt = ( ); const leaves = under .filter((entry) => entry.command.length === path.length + 1) - .map((entry) => cachedLeaf(entry, entries)); - const groups = [...childNames].map((child) => groupAt([...path, child], noun, entries)); + .map((entry) => cachedLeaf(entry)); + const groups = [...childNames].map((child) => groupAt([...path, child], noun)); const description = `${groupDescription(path, noun) ?? name} (experimental)`; return Command.make(name).pipe( Command.withDescription(description), @@ -410,17 +397,12 @@ const groupAt = ( export const withApiCommands = >( handWritten: C, enabledFeatures: ReadonlyArray, - source: ApiCommandSource = { nouns, entries: apiCommands }, ): ReadonlyArray => { const merged: Array = [...handWritten]; - for (const [name, noun] of Object.entries(source.nouns)) { + for (const [name, noun] of Object.entries(nouns)) { if (!enabledFeatures.includes(noun.feature)) continue; const position = merged.findIndex((command) => command.name > name); - merged.splice( - position < 0 ? merged.length : position, - 0, - groupAt([name], noun, source.entries), - ); + merged.splice(position < 0 ? merged.length : position, 0, groupAt([name], noun)); } return merged; }; From 3431c6b0647cd4983aeaa03302de024802d17082 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 21:40:23 +0100 Subject: [PATCH 41/45] fix(cli): align generated command consent, permissions and output sanitizing --- apps/cli/src/commands/api/SIDE_EFFECTS.md | 7 +- .../src/commands/api/api-command-execute.ts | 12 +-- .../src/commands/api/api-command-policy.ts | 2 + .../src/commands/api/api-command-request.ts | 3 +- .../src/commands/api/api-command.format.ts | 11 ++- .../api/api-command.format.unit.test.ts | 6 ++ .../api/api-commands.integration.test.ts | 84 +++++++++++++++++-- apps/cli/src/commands/api/generated.md | 2 + apps/cli/src/commands/api/generated.ts | 2 + apps/cli/src/commands/api/runtime.ts | 33 ++++---- apps/cli/src/shared/cli/run.ts | 3 +- apps/cli/src/shared/cli/standard-errors.ts | 16 +--- 12 files changed, 131 insertions(+), 50 deletions(-) diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md index a7b07b1d70..cdd8086570 100644 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ b/apps/cli/src/commands/api/SIDE_EFFECTS.md @@ -110,7 +110,7 @@ before any command request. - The failure and timeout hint names the command that re-reads the state. When the polled read is a generated command, the hint names it with the identity the wait polled with, for example `supabase -- --remote=`. When the polled read is a hidden - read, the hint names the command its `poll.inspect` operation generates, with only `--remote=`. + read, the hint names the command its `x-operation.poll.inspect` operation generates, with only `--remote=`. - With `--wait`, stdout carries the final read response instead of the change response. ## Exit Codes @@ -119,7 +119,7 @@ before any command request. | ----- | ----------------------------------------------------------------------------------------------- | | `0` | success: the request was accepted, the dry run printed, or the wait ended on a succeeded status | | `2` | `usage_error`: invalid flags, body or timeout, or consent needed without `--yes` | -| `130` | consent declined at the prompt (`cancelled`) | +| `130` | consent declined at the prompt, or the run interrupted with Ctrl-C (`cancelled`) | | `1` | API error (non-2xx) | | `1` | with `--wait`: `operation_failed` (a failed status) or `wait_timeout` | @@ -128,6 +128,9 @@ adds `entitlement: {feature, upgrade_url}` to the stderr error document in place token-permission hint; a terminal run prints the upgrade hint, and `cli_upgrade_suggested` fires. Other statuses and bodies carry no `entitlement` key. +An interrupt (Ctrl-C) during the request or a `--wait` poll prints the `cancelled` failure with the +message `Interrupted` and exits `130`; it stops local work only and does not change server state. + Errors use the standard stderr envelope. `wait_timeout` includes `timeout_ms`, a nullable `last_status` and the hint command; terminal text includes the last status. `operation_failed` includes the failed status and the reported failure message. diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index 6f18680324..9be35c7976 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -5,7 +5,7 @@ import * as HttpClientError from "effect/http/HttpClientError"; import * as Headers from "effect/http/Headers"; import type * as HttpClientResponse from "effect/http/HttpClientResponse"; -import { parsePlanGateEnvelope, sanitizeErrorBody } from "../../command-internal/http-errors.ts"; +import { planGateFromResponse, sanitizeErrorBody } from "../../command-internal/http-errors.ts"; import { Output } from "../../shared/output/output.service.ts"; import { readPointer } from "./api-command-pointer.ts"; import { definitionOf, type ApiRequestPreview } from "./api-command-request.ts"; @@ -101,8 +101,7 @@ const statusError = Effect.fnUntraced(function* ( ); const body = Option.getOrUndefined(decodeJsonText(text)); const fields = apiErrorFields(body); - const entitlement = - response.status >= 400 && response.status < 500 ? parsePlanGateEnvelope(body) : undefined; + const { entitlement } = planGateFromResponse(response.status, text); return yield* new ApiCommandStatusError({ status: response.status, message: @@ -111,8 +110,11 @@ const statusError = Effect.fnUntraced(function* ( : sanitizeErrorBody(fields.message), apiCode: fields.apiCode, hint: - fields.hint ?? - (entitlement === undefined ? statusHint(operationId, response.status) : undefined), + fields.hint === undefined + ? entitlement === undefined + ? statusHint(operationId, response.status) + : undefined + : sanitizeErrorBody(fields.hint), ...(entitlement === undefined ? {} : { entitlement }), }); }); diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index a0169c40f2..ca50ff0a06 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -34,6 +34,8 @@ export interface ApiCommandPolicy { /** CLI presentation choices, independent of the API's operation metadata. */ export const commandPolicies = { + "v2-disable-warehouse": { confirmDescription: true }, + "v2-update-warehouse-table-layout": { confirmDescription: true }, "v2-add-warehouse-replication": { confirmDescription: true }, "v2-remove-warehouse-replication": { confirmDescription: true }, "v2-resync-warehouse-replication": { confirmDescription: true }, diff --git a/apps/cli/src/commands/api/api-command-request.ts b/apps/cli/src/commands/api/api-command-request.ts index 3ee613bc93..4348528299 100644 --- a/apps/cli/src/commands/api/api-command-request.ts +++ b/apps/cli/src/commands/api/api-command-request.ts @@ -6,6 +6,7 @@ import type { ApiFlagValue } from "./api-command-flags.ts"; import { readPointer, writePointer } from "./api-command-pointer.ts"; import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; import type { ApiCommandEntry } from "./api-command.model.ts"; +import { singleLine } from "./api-command.format.ts"; /** Parsed flag values keyed by flag name; `None` means the flag was absent. */ export type ApiFlagValues = Readonly>>; @@ -311,7 +312,7 @@ export const previewRequest = (entry: ApiCommandEntry, decoded: object): ApiRequ }; const detailLine = (name: string, value: unknown): string => - `${name}: ${typeof value === "string" ? value : (JSON.stringify(value) ?? "null")}`; + singleLine(`${name}: ${typeof value === "string" ? value : (JSON.stringify(value) ?? "null")}`); /** * The `name: value` lines a consent prompt lists for a validated request: each path parameter diff --git a/apps/cli/src/commands/api/api-command.format.ts b/apps/cli/src/commands/api/api-command.format.ts index e957e853bb..7d20361aca 100644 --- a/apps/cli/src/commands/api/api-command.format.ts +++ b/apps/cli/src/commands/api/api-command.format.ts @@ -19,11 +19,14 @@ const CONTROL_ESCAPES: Readonly> = { "\t": "\\t", }; -/** Keeps a value on one line by escaping line breaks, tabs and other control characters. */ -const singleLine = (text: string): string => +/** + * Keeps a value on one line and inert in a terminal: line breaks, tabs and the other control + * characters (C0, DEL, C1), bidi controls and line separators become visible `\uXXXX` escapes. + */ +export const singleLine = (text: string): string => text.replace( // oxlint-disable-next-line no-control-regex -- escaping control characters is the purpose - /[\u0000-\u001f\u007f]/gu, + /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu, (char) => CONTROL_ESCAPES[char] ?? `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`, ); @@ -231,7 +234,7 @@ export const renderDryRunText = (preview: ApiRequestPreview): string => { "Body", ...JSON.stringify(preview.body, null, 2) .split("\n") - .map((line) => `${INDENT}${line}`), + .map((line) => `${INDENT}${singleLine(line)}`), ]; return `${[ `Dry run: ${singleLine(preview.method)} ${singleLine(preview.path)}`, diff --git a/apps/cli/src/commands/api/api-command.format.unit.test.ts b/apps/cli/src/commands/api/api-command.format.unit.test.ts index 68b1f2784c..22be6bab9c 100644 --- a/apps/cli/src/commands/api/api-command.format.unit.test.ts +++ b/apps/cli/src/commands/api/api-command.format.unit.test.ts @@ -12,6 +12,12 @@ describe("renderResponseText", () => { expect(renderResponseText({ message: "a\nb\tc\u0001d" })).toBe("Message a\\nb\\tc\\u0001d\n"); }); + it("escapes C1, bidi and line-separator characters so terminals cannot reorder or split a value", () => { + expect(renderResponseText({ message: "a\u202eb\u009bc\u2028d" })).toBe( + "Message a\\u202eb\\u009bc\\u2028d\n", + ); + }); + it("escapes control characters in keys so labels stay on one line", () => { expect(renderResponseText({ "a\nb\u001bc": 1 })).toBe("A\\nb\\u001bc 1\n"); }); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 3a3007a864..9a5d2c43e0 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -55,6 +55,7 @@ import { import type { ApiCommandEntry } from "./api-command.model.ts"; import { assembleInput, decodeInput, previewRequest } from "./api-command-request.ts"; import { apiCommands } from "./generated.ts"; +import { readPermissions } from "../../command-internal/command-permissions/command-permissions.annotation.ts"; import { withApiCommands } from "./runtime.ts"; import { isMachineFailureMode, standardFailureFor } from "../../shared/cli/standard-errors.ts"; import { EventUpgradeSuggested } from "../../shared/telemetry/event-catalog.ts"; @@ -286,9 +287,10 @@ const execute = (argv: ReadonlyArray, opts: CliOpts) => { const setup = (argv: ReadonlyArray, opts: CliOpts) => { const interactive = opts.confirmResponses !== undefined; + const stdoutIsTty = opts.stdoutIsTty ?? interactive; const out = mockOutput({ format: opts.outputFormat ?? "text", - interactive, + interactive: stdoutIsTty && (opts.outputFormat ?? "text") === "text", ...(interactive ? { promptConfirmResponses: opts.confirmResponses } : {}), }); const { args, sent, seen, run } = execute(argv, opts); @@ -298,7 +300,7 @@ const setup = (argv: ReadonlyArray, opts: CliOpts) => { api: mockCommandPlatformApi({ response: { status: 200, body: {} } }), ...(opts.analytics === undefined ? {} : { analytics: opts.analytics }), cliSettings: mockCommandSettings({ workdir: tempRoot.current }), - tty: mockTty({ stdinIsTty: interactive, stdoutIsTty: opts.stdoutIsTty ?? interactive }), + tty: mockTty({ stdinIsTty: interactive, stdoutIsTty }), stdin: mockStdin(false), cliArgs: args, }), @@ -1793,6 +1795,20 @@ describe("generated warehouse commands", () => { }); }); + it.effect("neutralizes terminal control characters in an API-provided hint", () => { + const { run } = setup(["warehouse", "enable", "--schema", "public"], { + yes: true, + route: () => ({ + status: 401, + body: { message: "Expired", hint: "Rotate\u202e the\u009b token\u2028" }, + }), + }); + return Effect.gen(function* () { + const failure = failureOf(yield* Effect.exit(run)); + expect(failure).toMatchObject({ hint: "Rotate the token" }); + }); + }); + it.effect("reports a plan-gated 403 with its entitlement in the document and telemetry", () => { const analytics = mockAnalytics(); const planGate = { @@ -1854,6 +1870,45 @@ describe("generated warehouse commands", () => { }); }); + describe("permissions", () => { + const tree = commandTreeFor({ apiFeatures: ["warehouse"] }); + const operationsOf = (path: string) => { + const command = tree.get(path)?.command; + const permissions = Option.getOrUndefined( + command === undefined ? Option.none() : readPermissions(command), + ); + return permissions?.status === "mapped" ? permissions.operations : []; + }; + const sendsRequests = (entry: { + readonly when?: ReadonlyArray<{ flag?: string; is?: boolean }>; + }) => + entry.when?.some((condition) => condition.flag === "dry-run" && condition.is === false) === + true; + + it.each(["warehouse enable", "warehouse disable", "warehouse tables layout update"])( + "%s needs no API operation beyond target resolution on a dry run", + (path) => { + const operations = operationsOf(path); + expect(operations.some((entry) => entry.source === undefined)).toBe(true); + const unconditional = operations.filter((entry) => !sendsRequests(entry)); + expect(unconditional.length).toBeGreaterThan(0); + expect( + unconditional.every( + (entry) => entry.source === "project-ref" || entry.source === "branch-resolution", + ), + ).toBe(true); + }, + ); + + it("requires the wait poll operation only for a request that is sent", () => { + const poll = operationsOf("warehouse enable").find((entry) => + entry.when?.some((condition) => condition.flag === "wait"), + ); + expect(poll).toBeDefined(); + expect(poll !== undefined && sendsRequests(poll)).toBe(true); + }); + }); + describe("help", () => { it.effect("shows a body file in the layout update example", () => { const { console, calls } = fakeConsole(); @@ -1868,6 +1923,15 @@ describe("generated warehouse commands", () => { }); }); + it.effect("lists a required body-bound flag in the usage example", () => { + const { console, calls } = fakeConsole(); + const { run } = setup(["warehouse", "replication", "add", "--help"], { route: accepted }); + return Effect.gen(function* () { + yield* run.pipe(Effect.provideService(Console.Console, console)); + expect(calls.join("\n")).toContain("supabase warehouse replication add --schema "); + }); + }); + it.effect("marks a required API flag as required in its description", () => { const { console, calls } = fakeConsole(); const { run } = setup(["warehouse", "enable", "--help"], { route: accepted }); @@ -2136,7 +2200,7 @@ describe("generated warehouse commands", () => { const exit = yield* Effect.exit(failed.run); expect(failureOf(exit)).toBeInstanceOf(ApiCommandStatusError); expect(failed.out.stdoutText).toBe(""); - expect(isMachineFailureMode(failed.args, false, "text")).toBe(true); + expect(isMachineFailureMode(failed.args, false)).toBe(true); }); }); @@ -2437,7 +2501,7 @@ describe("hosted consent details", () => { { name: "a disable that deletes data", argv: ["warehouse", "disable", "--delete-data"], - shown: ["delete_data: true"], + shown: ["delete_data: true", "permanently delete the managed catalog schema"], }, { name: "a layout update with a reset", @@ -2455,7 +2519,17 @@ describe("hosted consent details", () => { }, }), ], - shown: ["table_id: 16385", "sort_by: null", "reset_table: true"], + shown: [ + "table_id: 16385", + "sort_by: null", + "reset_table: true", + "Reads are disrupted during the copy", + ], + }, + { + name: "a body field with terminal control characters", + argv: ["warehouse", "replication", "add", "--schema", "a\u202eb\u009bc"], + shown: ["schema: a\\u202eb\\u009bc"], }, ])("lists what $name will send before asking", ({ argv, shown }) => { const { out, sent, run } = setup(argv, { route: accepted, confirmResponses: [false] }); diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index 1266041431..2155714a01 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -22,6 +22,7 @@ Stops replication and removes the Warehouse publication, FDW and dependent forei - Access: mutation, consent defaults to No (`--yes` when it cannot prompt). - Feature: `warehouse`. +- Consent: prints the API description before the interactive confirmation. - Request: `DELETE /v2/projects/{ref}/warehouse` (`v2-disable-warehouse`), success 202 json. ### Flags @@ -212,6 +213,7 @@ Updates saved sorting and partitioning rules for one source table object identif - Access: mutation, consent defaults to No (`--yes` when it cannot prompt). - Feature: `warehouse`. +- Consent: prints the API description before the interactive confirmation. - Request: `PATCH /v2/projects/{ref}/warehouse/tables/{table_id}/layout` (`v2-update-warehouse-table-layout`), success 202 json. - Body: JSON envelope `data.type = warehouse_table_layout`, fields under `data.attributes`. - Positional argument ``, bound to path parameter `table_id`. diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 9bae03d156..1037374213 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -28,6 +28,7 @@ export const apiCommands = [ description: "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.", readOnly: false, + confirmDescription: true, feature: "warehouse", flags: [ { @@ -589,6 +590,7 @@ export const apiCommands = [ description: "Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying.", readOnly: false, + confirmDescription: true, feature: "warehouse", body: { contentType: "application/json", diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 4c8b236a99..5b28c87e92 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -5,7 +5,11 @@ import { CommandPlatformApiFactory } from "../../auth/command-platform-api-facto import { ApiCommandUsageError } from "../../command-internal/command-errors/api-command.errors.ts"; import { withStandardErrors } from "../../command-internal/command-errors/command-errors.annotation.ts"; import { withPermissions } from "../../command-internal/command-permissions/command-permissions.annotation.ts"; -import { compose, type OperationEntry } from "../../command-internal/command-permissions/model.ts"; +import { + compose, + type OperationEntry, + withCondition, +} from "../../command-internal/command-permissions/model.ts"; import { parseDuration } from "../../command-internal/duration.ts"; import { GLOBAL_OUTPUT_FORMATS, OutputFlag } from "../../command-internal/global-flags.ts"; import { requireHostedMutationConsent } from "../../command-internal/hosted-consent/hosted-consent.ts"; @@ -17,10 +21,8 @@ import { resolveProjectTarget } from "../../command-internal/target/resolve-proj import { projectTargetFlags } from "../../command-internal/target/target-flags.ts"; import { withTargetPolicy } from "../../command-internal/target/target-policy.ts"; import { projectRefPicker } from "../../config/project-ref.layer.ts"; -import { isMachineOutput } from "../../shared/cli/standard-errors.ts"; import { Output } from "../../shared/output/output.service.ts"; import { stdinLayer } from "../../shared/runtime/stdin.layer.ts"; -import { Tty } from "../../shared/runtime/tty.service.ts"; import { withCommandTelemetry } from "../../telemetry/command-telemetry.ts"; import { LinkedProjectCache } from "../../telemetry/linked-project-cache.service.ts"; import { linkedProjectCache } from "../../telemetry/linked-project-cache.layer.ts"; @@ -196,9 +198,7 @@ const handle = Effect.fn("api-command.run")(function* ( const cache = yield* LinkedProjectCache; const output = yield* Output; const outputFlag = yield* OutputFlag; - const format: ApiOutputFormat = isMachineOutput((yield* Tty).stdoutIsTty, output.format) - ? "json" - : "text"; + const format: ApiOutputFormat = output.interactive ? "text" : "json"; const progress = format === "text"; yield* Effect.annotateCurrentSpan("output.presentation", format); yield* Effect.gen(function* () { @@ -275,35 +275,32 @@ const handle = Effect.fn("api-command.run")(function* ( const exampleFor = (entry: ApiCommandEntry): string => { const required = entry.flags - .filter( - (flag) => - flag.required && - !entry.bindings.some( - (binding) => binding.location === "body" && binding.flag === flag.name, - ), - ) + .filter((flag) => flag.required) .map((flag) => `--${flag.name}${flag.type === "boolean" ? "" : ` <${flag.name}>`}`); const positional = entry.argument === undefined ? [] : [`<${entry.argument.name}>`]; - const body = entry.body === undefined ? [] : ["--file "]; + const body = entry.body === undefined || required.length > 0 ? [] : ["--file "]; return ["supabase", ...entry.command, ...positional, ...required, ...body].join(" "); }; +// `--dry-run` returns before the API client exists, so the command, the poll and the cache lookup +// run only without it. +const sendsRequests = { flag: "dry-run", is: false } as const; + const permissionsOf = (entry: ApiCommandEntry, resolved: ResolvedWait | undefined) => { const polled = resolved?.readEntry.operationId; const operations: ReadonlyArray = [ - { operationId: entry.operationId, kind: "required" }, + { operationId: entry.operationId, kind: "required", when: [sendsRequests] }, ...(polled === undefined || polled === entry.operationId ? [] : [ { operationId: polled, kind: "required" as const, - when: [{ flag: "wait", is: true }], + when: [sendsRequests, { flag: "wait", is: true }], }, ]), ]; const noApiEffectFlags = [ - "dry-run", ...(entry.body === undefined ? [] : ["body", "file"]), ...(resolved === undefined ? [] : ["timeout"]), ...(polled === entry.operationId ? ["wait"] : []), @@ -312,7 +309,7 @@ const permissionsOf = (entry: ApiCommandEntry, resolved: ResolvedWait | undefine return compose( { operations, noApiEffectFlags }, projectRefPicker, - linkedProjectCache, + withCondition(linkedProjectCache, sendsRequests), branchResolution, ); }; diff --git a/apps/cli/src/shared/cli/run.ts b/apps/cli/src/shared/cli/run.ts index 934ac3087b..d7aeb207a4 100644 --- a/apps/cli/src/shared/cli/run.ts +++ b/apps/cli/src/shared/cli/run.ts @@ -853,13 +853,12 @@ export const runCli = Effect.fnUntraced(function* < } const exitCode = exitCodeForFailure(cause); if (usesStandardErrors && exitCode !== 0) { - const tty = yield* Tty; const mapped = standardFailureFor(cause, suggestionContext); return { exitCode: mapped.exitCode, pending: { ...mapped, - machine: isMachineFailureMode(args, tty.stdoutIsTty, outputFormat), + machine: isMachineFailureMode(args, output.interactive), }, } satisfies RunOutcome; } diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index 88743aced4..199f542290 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -32,7 +32,6 @@ import { CliErrorKind, } from "../telemetry/error-actionability.ts"; import { isMachineResourceFormat } from "../output/resource-format.ts"; -import type { OutputFormat } from "../output/types.ts"; import { readOutputFlag } from "./agent-output.ts"; import { findCommand, @@ -258,18 +257,9 @@ export const errorsContractForRun = ( return node === undefined ? "legacy" : readCommandErrorsContract(node); }; -/** Whether output is machine-readable: stdout is not a TTY or the resolved output format is not text. */ -export const isMachineOutput = (stdoutIsTty: boolean, outputFormat: OutputFormat): boolean => - !stdoutIsTty || outputFormat !== "text"; - -/** Whether failures render as the JSON document: a machine `-o` or machine output. */ -export const isMachineFailureMode = ( - args: ReadonlyArray, - stdoutIsTty: boolean, - outputFormat: OutputFormat, -): boolean => - isMachineOutput(stdoutIsTty, outputFormat) || - isMachineResourceFormat(Option.fromNullishOr(readOutputFlag(args))); +/** Whether failures render as the JSON document: a machine `-o` or output that is not interactive. */ +export const isMachineFailureMode = (args: ReadonlyArray, interactive: boolean): boolean => + !interactive || isMachineResourceFormat(Option.fromNullishOr(readOutputFlag(args))); /** Renders the failure as the stderr text: a leading blank line plus JSON, or a human message and hint. */ const renderStandardFailure = (pending: PendingStandardFailure): string => { From 2b8c63ce9b80658933192fc5a15de723b255eed1 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 21:52:47 +0100 Subject: [PATCH 42/45] fix(cli): narrow ambiguous-remote auth mapping, escape poll status, route help An ambiguous --remote maps only 401, 403 and token failures to auth documents; a 404 branch listing stays a usage error. The --wait spinner status and a non-JSON text-mode success body are escaped for display, while JSON output keeps the original bytes. Routing args drop a leading help so `help warehouse` and `help compute` resolve their feature, and the stack backend reuses that. Help tests assert the cache and poll permissions outside dry runs. --- apps/cli/src/command-internal/routing-args.ts | 9 +-- .../cli/src/command-internal/stack-backend.ts | 5 +- .../src/commands/api/api-command-execute.ts | 7 +- .../api/api-commands.integration.test.ts | 76 +++++++++++++++++++ apps/cli/src/commands/api/runtime.ts | 3 +- apps/cli/src/shared/cli/standard-errors.ts | 2 +- .../shared/cli/standard-errors.unit.test.ts | 11 +++ 7 files changed, 101 insertions(+), 12 deletions(-) diff --git a/apps/cli/src/command-internal/routing-args.ts b/apps/cli/src/command-internal/routing-args.ts index 8bb1f6b47d..ddb38a6f55 100644 --- a/apps/cli/src/command-internal/routing-args.ts +++ b/apps/cli/src/command-internal/routing-args.ts @@ -6,7 +6,8 @@ const isCompletionToken = (arg: string | undefined): boolean => /** * Splits argv into the args and command path that backend and feature routing read, or * `undefined` for `--version`. Completion passes the final token as the cursor word, so it is - * dropped from both. + * dropped from both, and a leading `help` is dropped from the path so `help ` routes like + * ``. */ export const routingArgsFor = ( args: ReadonlyArray, @@ -16,8 +17,6 @@ export const routingArgsFor = ( const routingArgs = isCompletionToken(args[0]) ? args.slice(0, -1) : args; if (hasRootVersionFlag(routingArgs)) return undefined; const commandPath = extractCommandPath(routingArgs); - return { - routingArgs, - path: isCompletionToken(commandPath[0]) ? commandPath.slice(1) : commandPath, - }; + const path = isCompletionToken(commandPath[0]) ? commandPath.slice(1) : commandPath; + return { routingArgs, path: path[0] === "help" ? path.slice(1) : path }; }; diff --git a/apps/cli/src/command-internal/stack-backend.ts b/apps/cli/src/command-internal/stack-backend.ts index 3cacfed7bb..ac79ada7a0 100644 --- a/apps/cli/src/command-internal/stack-backend.ts +++ b/apps/cli/src/command-internal/stack-backend.ts @@ -100,13 +100,12 @@ export const resolveProjectStateSelection = Effect.fn("ProjectState.resolveSelec const routing = routingArgsFor(input.args); if (routing === undefined) return { projectState: undefined, stackBackend: undefined }; const { routingArgs, path } = routing; - const routedPath = path[0] === "help" ? path.slice(1) : path; - const command = routedPath[0]; + const command = path[0]; const routed = command === undefined || command === "stack" || STACK_BACKEND_COMMANDS.has(command) || - isFunctionsServePath(routedPath); + isFunctionsServePath(path); const projectState = yield* Effect.exit(projectStateMode({ ...input, args: routingArgs })); const stackBackend = routed diff --git a/apps/cli/src/commands/api/api-command-execute.ts b/apps/cli/src/commands/api/api-command-execute.ts index 9be35c7976..7d38c8e0f1 100644 --- a/apps/cli/src/commands/api/api-command-execute.ts +++ b/apps/cli/src/commands/api/api-command-execute.ts @@ -9,7 +9,7 @@ import { planGateFromResponse, sanitizeErrorBody } from "../../command-internal/ import { Output } from "../../shared/output/output.service.ts"; import { readPointer } from "./api-command-pointer.ts"; import { definitionOf, type ApiRequestPreview } from "./api-command-request.ts"; -import { renderDryRunText, renderResponseText } from "./api-command.format.ts"; +import { renderDryRunText, renderResponseText, singleLine } from "./api-command.format.ts"; import { ApiCommandOperationFailedError, ApiCommandStatusError, @@ -165,7 +165,10 @@ export const writeApiResponse = Effect.fnUntraced(function* ( if (format === "json") return yield* output.rawBytes(response.bytes); const text = textDecoder.decode(response.bytes); const parsed = decodeJsonText(text); - if (Option.isNone(parsed)) return yield* output.raw(text.endsWith("\n") ? text : `${text}\n`); + if (Option.isNone(parsed)) { + const lines = text.endsWith("\n") ? text.slice(0, -1) : text; + return yield* output.raw(`${lines.split("\n").map(singleLine).join("\n")}\n`); + } return yield* output.raw(renderResponseText(parsed.value)); }); diff --git a/apps/cli/src/commands/api/api-commands.integration.test.ts b/apps/cli/src/commands/api/api-commands.integration.test.ts index 9a5d2c43e0..ea4be87899 100644 --- a/apps/cli/src/commands/api/api-commands.integration.test.ts +++ b/apps/cli/src/commands/api/api-commands.integration.test.ts @@ -513,6 +513,29 @@ describe("generated warehouse commands", () => { }); }); + it.effect("escapes control characters in a non-JSON success body as text", () => { + const { out, run } = setup(["warehouse", "status"], { + route: ok("\u001b[31mred\nsecond\u0007 line\n"), + stdoutIsTty: true, + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe("\\u001b[31mred\nsecond\\u0007 line\n"); + }); + }); + + it.effect("passes a non-JSON success body through untouched as json", () => { + const raw = "\u001b[31mred\nsecond\n"; + const { out, run } = setup(["warehouse", "status", "--output-format", "json"], { + route: ok(raw), + outputFormat: "json", + }); + return Effect.gen(function* () { + yield* run; + expect(out.stdoutText).toBe(raw); + }); + }); + it.effect("labels configured readiness and unavailable observations in terminal output", () => { const { out, run } = setup(["warehouse", "status"], { route: ok(body), stdoutIsTty: true }); return Effect.gen(function* () { @@ -1907,6 +1930,20 @@ describe("generated warehouse commands", () => { expect(poll).toBeDefined(); expect(poll !== undefined && sendsRequests(poll)).toBe(true); }); + + it.effect("renders the cache and poll permissions in help only for a sent request", () => { + const { console, calls } = fakeConsole(); + const { run } = setup(["warehouse", "enable", "--help"], { route: accepted }); + return Effect.gen(function* () { + yield* run.pipe(Effect.provideService(Console.Console, console)); + const lines = calls.join("\n").split("\n"); + const section = lines.slice(lines.indexOf("PERMISSIONS")).join("\n"); + expect(section).toContain( + "Optional, without --dry-run (command still runs without these):\n project_admin_read", + ); + expect(section).toContain("Required with --wait, without --dry-run:\n database_read"); + }); + }); }); describe("help", () => { @@ -2277,6 +2314,25 @@ describe("generated warehouse commands", () => { }); }); + it.effect("escapes control characters in the polled status shown in the task", () => { + const { out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { + yes: true, + stdoutIsTty: true, + route: enableThenPoll([ + { status: 200, body: statusBody("\u001b[31mred") }, + { status: 200, body: statusBody("succeeded") }, + ]), + }); + return Effect.gen(function* () { + const fiber = yield* run.pipe(Effect.forkChild({ startImmediately: true })); + yield* driveClock(fiber); + yield* Fiber.join(fiber); + const shown = out.progressEvents.map((event) => event.message).join("\n"); + expect(shown).toContain("(status: \\u001b[31mred)"); + expect(shown).not.toContain("\u001b"); + }); + }); + it.effect("fails the polling task and keeps the standard error when the setup fails", () => { const { out, run } = setup(["warehouse", "enable", "--schema", "public", "--wait"], { yes: true, @@ -2409,6 +2465,20 @@ describe("generated warehouse commands", () => { }), ); + it.effect("completes the group and its subcommands after help", () => + Effect.gen(function* () { + const env = { SUPABASE_EXPERIMENTAL_WAREHOUSE: "1" }; + const names = (args: ReadonlyArray) => + Effect.gen(function* () { + const apiFeatures = yield* resolve(env, tempRoot.current, args); + const completion = respondToComplete(rootCommandForFeatures({ apiFeatures }), args); + return completion?.candidates.map((candidate) => candidate.name) ?? []; + }); + expect(yield* names(["__complete", "help", "ware"])).toContain("warehouse"); + expect(yield* names(["__complete", "help", "warehouse", "en"])).toContain("enable"); + }), + ); + it.effect("is on with experimental.warehouse in the project config", () => Effect.gen(function* () { yield* withConfig("[experimental]\nwarehouse = true\n"); @@ -2423,6 +2493,12 @@ describe("generated warehouse commands", () => { args: ["__complete", "ware"], features: ["warehouse"], }, + { + name: "help completion of the group", + args: ["__complete", "help", "ware"], + features: ["warehouse"], + }, + { name: "help for the group", args: ["help", "warehouse"], features: ["warehouse"] }, { name: "inspection parent help", args: ["inspect"], features: [] }, { name: "Warehouse inspection", diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index 5b28c87e92..ecb6c42ca0 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -37,6 +37,7 @@ import { } from "./api-command-execute.ts"; import { type ApiFlagLocation, apiFlag } from "./api-command-flags.ts"; import { type ApiNoun, nouns } from "./api-command-policy.ts"; +import { singleLine } from "./api-command.format.ts"; import { assembleInput, consentDetails, @@ -258,7 +259,7 @@ const handle = Effect.fn("api-command.run")(function* ( ref, timeoutMillis, onPoll: (status) => - update(status === undefined ? polling : `${polling} (status: ${status})`), + update(status === undefined ? polling : `${polling} (status: ${singleLine(status)})`), }), ); yield* Effect.annotateCurrentSpan("run.outcome", "waited"); diff --git a/apps/cli/src/shared/cli/standard-errors.ts b/apps/cli/src/shared/cli/standard-errors.ts index 199f542290..f3536d881d 100644 --- a/apps/cli/src/shared/cli/standard-errors.ts +++ b/apps/cli/src/shared/cli/standard-errors.ts @@ -158,7 +158,7 @@ const failureForError = ( } if ( error instanceof TargetRemoteAmbiguousError && - (error.status !== undefined || error.authFailure !== undefined) + (error.status === 401 || error.status === 403 || error.authFailure !== undefined) ) { const hint = error.suggestion ?? null; return error.status === undefined diff --git a/apps/cli/src/shared/cli/standard-errors.unit.test.ts b/apps/cli/src/shared/cli/standard-errors.unit.test.ts index 76e658cec0..fb3c380c02 100644 --- a/apps/cli/src/shared/cli/standard-errors.unit.test.ts +++ b/apps/cli/src/shared/cli/standard-errors.unit.test.ts @@ -231,6 +231,17 @@ describe("standardFailureFor", () => { ), expected: { exitCode: 1, code: "forbidden", status: 403, hint: "Ask for branch access" }, }, + { + name: "ambiguous remote whose branch listing was not found", + cause: Cause.fail( + new TargetRemoteAmbiguousError({ + message: "Could not check branches", + suggestion: "Pass --project-ref", + status: 404, + }), + ), + expected: { exitCode: 2, code: "usage_error", status: null, hint: "Pass --project-ref" }, + }, { name: "ambiguous remote with an invalid token", cause: Cause.fail( From 9a8fe2ba04c57e56e203f840fb4060db2ace5b62 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 22:32:25 +0100 Subject: [PATCH 43/45] refactor(cli): name the generated noun gate experimental The noun's gate field is now `experimental`, matching the `experimental.` config key it reads. Entries no longer copy it; the reference reads the noun and prints how to enable it. --- apps/cli/scripts/api-command-derive.ts | 1 - .../scripts/api-command-derive.unit.test.ts | 8 ++++-- apps/cli/scripts/api-command-reference.ts | 16 ++++++++++- apps/cli/scripts/generate-api-commands.ts | 2 +- .../src/commands/api/api-command-features.ts | 5 ++-- .../src/commands/api/api-command-policy.ts | 6 ++-- .../cli/src/commands/api/api-command.model.ts | 2 -- apps/cli/src/commands/api/generated.md | 28 +++++++++---------- apps/cli/src/commands/api/generated.ts | 14 ---------- apps/cli/src/commands/api/runtime.ts | 2 +- 10 files changed, 43 insertions(+), 41 deletions(-) diff --git a/apps/cli/scripts/api-command-derive.ts b/apps/cli/scripts/api-command-derive.ts index 0d1ca59dfb..323ab91905 100644 --- a/apps/cli/scripts/api-command-derive.ts +++ b/apps/cli/scripts/api-command-derive.ts @@ -943,7 +943,6 @@ export function deriveApiCommands(input: DeriveInput): DeriveResult { ...(description === undefined ? {} : { description }), readOnly: operation.method === "GET", ...policy, - feature: noun.feature, ...(body === undefined ? {} : { body }), ...(positional === undefined ? {} diff --git a/apps/cli/scripts/api-command-derive.unit.test.ts b/apps/cli/scripts/api-command-derive.unit.test.ts index e970ceb533..864b318bab 100644 --- a/apps/cli/scripts/api-command-derive.unit.test.ts +++ b/apps/cli/scripts/api-command-derive.unit.test.ts @@ -65,7 +65,7 @@ const closedBranch = (properties: Record, required: ReadonlyArr const thingNoun: ApiNoun = { description: "Manage things", - feature: "warehouse", + experimental: "warehouse", groups: { sub: "Manage sub things", "sub.deep": "Manage deep things", status: "Status" }, }; @@ -1543,7 +1543,11 @@ describe("deriveApiCommands", () => { "create-thing": operation({ "x-operation": { group: "thing.sub", method: "create" } }), }, undefined, - { overrides: { nouns: { thing: { description: "Manage things", feature: "warehouse" } } } }, + { + overrides: { + nouns: { thing: { description: "Manage things", experimental: "warehouse" } }, + }, + }, ); expect(result.problems).toContain( diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts index ec0a374479..a629f6d15b 100644 --- a/apps/cli/scripts/api-command-reference.ts +++ b/apps/cli/scripts/api-command-reference.ts @@ -6,12 +6,14 @@ import type { ApiCommandWait, ApiPollTarget, } from "../src/commands/api/api-command.model.ts"; +import type { ApiNoun } from "../src/commands/api/api-command-policy.ts"; export interface ApiCommandReferenceInput { readonly entries: ReadonlyArray; readonly pollTargets: ReadonlyArray; /** Success status code per operation id. */ readonly successStatuses: ReadonlyMap; + readonly nouns: Readonly>; } const code = (text: string): string => `\`${text}\``; @@ -129,6 +131,18 @@ const bodyLine = (entry: ApiCommandEntry): string | undefined => { return `JSON envelope ${code(`data.type = ${body.type}`)}, fields under ${code("data.attributes")}`; }; +const experimentalLine = ( + entry: ApiCommandEntry, + input: ApiCommandReferenceInput, +): ReadonlyArray => { + const flag = input.nouns[entry.command[0] ?? ""]?.experimental; + return flag === undefined + ? [] + : [ + `- Experimental: enable with ${code(`experimental.${flag}`)} or ${code(`SUPABASE_EXPERIMENTAL_${flag.toUpperCase()}=1`)}.`, + ]; +}; + const commandSection = ( entry: ApiCommandEntry, input: ApiCommandReferenceInput, @@ -143,7 +157,7 @@ const commandSection = ( "", ...(entry.description === undefined ? [] : [prose(entry.description), ""]), `- Access: ${entry.readOnly ? "read-only, no consent" : "mutation, consent defaults to No (`--yes` when it cannot prompt)"}.`, - `- Feature: ${code(entry.feature)}.`, + ...experimentalLine(entry, input), ...(entry.confirmDescription ? ["- Consent: prints the API description before the interactive confirmation."] : []), diff --git a/apps/cli/scripts/generate-api-commands.ts b/apps/cli/scripts/generate-api-commands.ts index 6fb89978cf..90274762e7 100644 --- a/apps/cli/scripts/generate-api-commands.ts +++ b/apps/cli/scripts/generate-api-commands.ts @@ -106,7 +106,7 @@ const main = Effect.gen(function* () { }, { relative: "src/commands/api/generated.md", - source: renderApiCommandReference({ entries, pollTargets, successStatuses }), + source: renderApiCommandReference({ entries, pollTargets, successStatuses, nouns }), }, ]; diff --git a/apps/cli/src/commands/api/api-command-features.ts b/apps/cli/src/commands/api/api-command-features.ts index 190bffc818..4cc459eb2a 100644 --- a/apps/cli/src/commands/api/api-command-features.ts +++ b/apps/cli/src/commands/api/api-command-features.ts @@ -10,9 +10,10 @@ import { import { nouns } from "./api-command-policy.ts"; const nounFeatures = (noun: string | undefined): ReadonlyArray => { - if (noun === undefined) return [...new Set(Object.values(nouns).map(({ feature }) => feature))]; + if (noun === undefined) + return [...new Set(Object.values(nouns).map(({ experimental }) => experimental))]; const definition = Object.entries(nouns).find(([name]) => name === noun)?.[1]; - return definition === undefined ? [] : [definition.feature]; + return definition === undefined ? [] : [definition.experimental]; }; /** diff --git a/apps/cli/src/commands/api/api-command-policy.ts b/apps/cli/src/commands/api/api-command-policy.ts index ca50ff0a06..68993f0230 100644 --- a/apps/cli/src/commands/api/api-command-policy.ts +++ b/apps/cli/src/commands/api/api-command-policy.ts @@ -4,8 +4,8 @@ import type { ExperimentalFeature } from "../../shared/config/experimental-featu export interface ApiNoun { /** Help text of the noun's group. */ readonly description: string; - /** Feature that gates every command under the noun. */ - readonly feature: ExperimentalFeature; + /** Experimental flag (`experimental.`) that gates every command under the noun. */ + readonly experimental: ExperimentalFeature; /** Help text of each sub-group, keyed by its dotted path below the noun, e.g. `"tables.layout"`. */ readonly groups?: Readonly>; } @@ -44,7 +44,7 @@ export const commandPolicies = { export const nouns = { warehouse: { description: "Manage the data warehouse for a project", - feature: "warehouse", + experimental: "warehouse", groups: { replication: "Manage Warehouse replication selections and rebuilds", inspect: "Inspect Warehouse workload metrics", diff --git a/apps/cli/src/commands/api/api-command.model.ts b/apps/cli/src/commands/api/api-command.model.ts index 7f2ce7d311..65e087a17e 100644 --- a/apps/cli/src/commands/api/api-command.model.ts +++ b/apps/cli/src/commands/api/api-command.model.ts @@ -76,8 +76,6 @@ export interface ApiCommandEntry { readonly readOnly: boolean; /** Show the API description as impact details before hosted consent. */ readonly confirmDescription?: true; - /** Feature that gates the command's noun. */ - readonly feature: string; /** Request body: an envelope that wraps the fields in `data.attributes`. */ readonly body?: { readonly contentType: "application/json"; diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index 2155714a01..ddf83bbc19 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -11,7 +11,7 @@ Get Warehouse Flight SQL connection details Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@\:443?tls=enabled'. - Access: read-only, no consent. -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `GET /v2/projects/{ref}/warehouse/connection` (`v2-get-warehouse-connection`), success 200 json. ## `supabase warehouse disable` @@ -21,7 +21,7 @@ Disable Warehouse replication and access Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures. - Access: mutation, consent defaults to No (`--yes` when it cannot prompt). -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Consent: prints the API description before the interactive confirmation. - Request: `DELETE /v2/projects/{ref}/warehouse` (`v2-disable-warehouse`), success 202 json. @@ -46,7 +46,7 @@ Enable Warehouse replication Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization. - Access: mutation, consent defaults to No (`--yes` when it cannot prompt). -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `POST /v2/projects/{ref}/warehouse/enable` (`v2-enable-warehouse`), success 202 json. - Body: JSON envelope `data.type = warehouse_setup`, fields under `data.attributes`. @@ -83,7 +83,7 @@ Point timestamps are evaluation times; `last_sample_at` is the original source-s Each request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted. - Access: read-only, no consent. -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `GET /v2/projects/{ref}/warehouse/capacity` (`v2-get-warehouse-capacity`), success 200 json. ### Flags @@ -103,7 +103,7 @@ Inspect Warehouse workload query statistics Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results. - Access: read-only, no consent. -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `GET /v2/projects/{ref}/warehouse/query-stats` (`v2-get-warehouse-query-stats`), success 200 json. ### Flags @@ -123,7 +123,7 @@ Add source tables to Warehouse replication Adds one eligible source table or the currently eligible tables in a schema to an enabled Warehouse. Existing selections and layouts are preserved; already-selected tables are unchanged. Schema selection excludes future tables, except future partitions of selected partition roots. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline remains stopped and requires an explicit start before copying. Initial copy adds source reads; duration is unknown. Unsafe reattachment of retained data is rejected. The response describes configuration and restart acceptance, not completed copy or streaming. Failures may have partial effects; inspect table and pipeline state before retrying. - Access: mutation, consent defaults to No (`--yes` when it cannot prompt). -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Consent: prints the API description before the interactive confirmation. - Request: `POST /v2/projects/{ref}/warehouse/replication/add` (`v2-add-warehouse-replication`), success 202 json. - Body: JSON envelope `data.type = warehouse_replication_change`, fields under `data.attributes`. @@ -142,7 +142,7 @@ Remove source tables from Warehouse replication Removes one selected source table or all selected tables in a schema as a batch. Source PostgreSQL rows and existing Warehouse data are retained. The retained copy stops receiving updates. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline stays stopped. Removing an unselected target is unchanged. Removing the last target leaves Warehouse enabled with an empty selection. Publication changes and restart acceptance do not establish observed exclusion by active replication. Failures may have partial effects; inspect the selection and pipeline before retrying. - Access: mutation, consent defaults to No (`--yes` when it cannot prompt). -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Consent: prints the API description before the interactive confirmation. - Request: `POST /v2/projects/{ref}/warehouse/replication/remove` (`v2-remove-warehouse-replication`), success 202 json. - Body: JSON envelope `data.type = warehouse_replication_change`, fields under `data.attributes`. @@ -161,7 +161,7 @@ Reset and rebuild one Warehouse table Resets replication for one selected source table using its currently saved layout. Source rows, saved layouts and completed replication state for unrelated tables are preserved. In-progress initial copies of other tables may restart from scratch. The Warehouse copy is deleted and rebuilt when replication resumes; table reads may be unavailable, freshness can lag, and the source incurs additional reads. Stopping and restarting the pipeline interrupts replication for other tables. Duration is unknown. The pipeline must be started and initial sync enabled for the table before the reset. The immediate response retains ETL reset states; it does not establish recopy completion. Inspect warehouse tables get and warehouse status separately. Do not automatically retry an uncertain response: repeating this request may reset the table again. There is no server-side preview, revision check, idempotency key or operation polling. - Access: mutation, consent defaults to No (`--yes` when it cannot prompt). -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Consent: prints the API description before the interactive confirmation. - Request: `POST /v2/projects/{ref}/warehouse/replication/resync` (`v2-resync-warehouse-replication`), success 202 json. - Body: JSON envelope `data.type = warehouse_replication_resync`, fields under `data.attributes`. @@ -180,7 +180,7 @@ Get consolidated Warehouse status and capabilities Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions. - Access: read-only, no consent. -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `GET /v2/projects/{ref}/warehouse/status` (`v2-get-warehouse-status`), success 200 json. ## `supabase warehouse tables get` @@ -190,7 +190,7 @@ Get a table replicated to Warehouse Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled. - Access: read-only, no consent. -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `GET /v2/projects/{ref}/warehouse/tables/{table_id}` (`v2-get-warehouse-table`), success 200 json. - Positional argument ``, bound to path parameter `table_id`. @@ -201,7 +201,7 @@ Get the layout of a table replicated to Warehouse Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up. - Access: read-only, no consent. -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `GET /v2/projects/{ref}/warehouse/tables/{table_id}/layout` (`v2-get-warehouse-table-layout`), success 200 json. - Positional argument ``, bound to path parameter `table_id`. @@ -212,7 +212,7 @@ Update the layout of a table replicated to Warehouse Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying. - Access: mutation, consent defaults to No (`--yes` when it cannot prompt). -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Consent: prints the API description before the interactive confirmation. - Request: `PATCH /v2/projects/{ref}/warehouse/tables/{table_id}/layout` (`v2-update-warehouse-table-layout`), success 202 json. - Body: JSON envelope `data.type = warehouse_table_layout`, fields under `data.attributes`. @@ -233,7 +233,7 @@ List tables replicated to Warehouse Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up. - Access: read-only, no consent. -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `GET /v2/projects/{ref}/warehouse/tables` (`v2-list-warehouse-tables`), success 200 json. ## `supabase warehouse teardowns get` @@ -243,7 +243,7 @@ Get Warehouse cleanup status Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation. - Access: read-only, no consent. -- Feature: `warehouse`. +- Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. - Request: `GET /v2/projects/{ref}/warehouse/teardowns/current` (`v2-get-warehouse-teardown`), success 200 json. ### Flags diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 1037374213..815e0d7a28 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -10,7 +10,6 @@ export const apiCommands = [ description: "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.", readOnly: true, - feature: "warehouse", flags: [], bindings: [ { @@ -29,7 +28,6 @@ export const apiCommands = [ "Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.", readOnly: false, confirmDescription: true, - feature: "warehouse", flags: [ { name: "delete-data", @@ -72,7 +70,6 @@ export const apiCommands = [ description: "Enables replication for the currently eligible tables in a schema, or the named tables in that schema. Resolves source identities under the mutation lock without a preview or revision. Repeating the same selection is safe; a different existing selection is rejected. Schema selection excludes future tables; selected partition roots include future partitions. Acceptance does not imply completed synchronization.", readOnly: false, - feature: "warehouse", body: { contentType: "application/json", type: "warehouse_setup", @@ -180,7 +177,6 @@ export const apiCommands = [ description: "Returns capacity, admission, assignment-wait, and activation measurements over a bounded time range, using the project’s stored Warehouse placement. Use `--since` or specify both `--from` and `--to`; the default is the last 30 minutes.\n\nEach measurement includes its definition, unit, aggregation, requested and effective ranges, `rate_window_seconds`, source-sample freshness, availability, coverage, and full series with dimension labels such as `reason`, `kind`, and `result`.\n\nExecutor invocations in flight are distinct from worker admission grants. Occupied admission includes active plus pending grants. The configured admission limit does not imply an open gate or spare capacity. Missing, stale, and insufficient observations remain unavailable or `null`; they do not establish healthy or idle capacity.\n\nPoint timestamps are evaluation times; `last_sample_at` is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range.\n\nEach request returns up to eight measurements, and a failure of one measurement does not discard the other results. No raw queries or backend selectors are accepted.", readOnly: true, - feature: "warehouse", flags: [ { name: "attributes", @@ -270,7 +266,6 @@ export const apiCommands = [ description: "Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.", readOnly: true, - feature: "warehouse", flags: [ { name: "attributes", @@ -361,7 +356,6 @@ export const apiCommands = [ "Adds one eligible source table or the currently eligible tables in a schema to an enabled Warehouse. Existing selections and layouts are preserved; already-selected tables are unchanged. Schema selection excludes future tables, except future partitions of selected partition roots. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline remains stopped and requires an explicit start before copying. Initial copy adds source reads; duration is unknown. Unsafe reattachment of retained data is rejected. The response describes configuration and restart acceptance, not completed copy or streaming. Failures may have partial effects; inspect table and pipeline state before retrying.", readOnly: false, confirmDescription: true, - feature: "warehouse", body: { contentType: "application/json", type: "warehouse_replication_change", @@ -413,7 +407,6 @@ export const apiCommands = [ "Removes one selected source table or all selected tables in a schema as a batch. Source PostgreSQL rows and existing Warehouse data are retained. The retained copy stops receiving updates. An active pipeline restarts once, interrupting replication for other tables; their in-progress initial copies may restart from scratch. A stopped pipeline stays stopped. Removing an unselected target is unchanged. Removing the last target leaves Warehouse enabled with an empty selection. Publication changes and restart acceptance do not establish observed exclusion by active replication. Failures may have partial effects; inspect the selection and pipeline before retrying.", readOnly: false, confirmDescription: true, - feature: "warehouse", body: { contentType: "application/json", type: "warehouse_replication_change", @@ -465,7 +458,6 @@ export const apiCommands = [ "Resets replication for one selected source table using its currently saved layout. Source rows, saved layouts and completed replication state for unrelated tables are preserved. In-progress initial copies of other tables may restart from scratch. The Warehouse copy is deleted and rebuilt when replication resumes; table reads may be unavailable, freshness can lag, and the source incurs additional reads. Stopping and restarting the pipeline interrupts replication for other tables. Duration is unknown. The pipeline must be started and initial sync enabled for the table before the reset. The immediate response retains ETL reset states; it does not establish recopy completion. Inspect warehouse tables get and warehouse status separately. Do not automatically retry an uncertain response: repeating this request may reset the table again. There is no server-side preview, revision check, idempotency key or operation polling.", readOnly: false, confirmDescription: true, - feature: "warehouse", body: { contentType: "application/json", type: "warehouse_replication_resync", @@ -516,7 +508,6 @@ export const apiCommands = [ description: "Returns provisioning, configured compute, replication, cleanup lifecycle and supported capabilities, including when individual dependencies are unavailable. Enabled Warehouse state is independent of the selected table count. Readiness is inferred from configuration and replication; query connectivity is not checked. Does not inspect the FDW. Observation timestamps are retrieval times, separate from table sync lag, pipeline apply lag and feedback age. Read access remains available without a replication entitlement; mutation endpoints enforce their own entitlements and permissions.", readOnly: true, - feature: "warehouse", flags: [], bindings: [ { @@ -534,7 +525,6 @@ export const apiCommands = [ description: "Returns one source table selected for Warehouse replication by its source OID, from the same observations and with the same status and freshness attributes as the Warehouse tables list. Returns 404 when the table is not selected for replication, including when Warehouse is not set up, its publication is missing, or it is being disabled.", readOnly: true, - feature: "warehouse", argument: { name: "table-id", description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", @@ -562,7 +552,6 @@ export const apiCommands = [ description: "Returns the sorting and partitioning rules saved for one replicated table, by source OID, beside the layout the DuckLake catalog records for it. The two are reported separately and can differ: the replicator applies saved rules when it starts and then hourly, and a stopped pipeline applies them on its next start. observation_status reports whether the catalog was read; desired rules are returned even when it was not. A catalog layout governs files written after it changes and does not establish that existing files are sorted or partitioned. Returns 404 when the table is not replicated, including when Warehouse is not set up, is being disabled or failed to clean up.", readOnly: true, - feature: "warehouse", argument: { name: "table-id", description: "Source PostgreSQL table OID, as returned by the Warehouse tables list.", @@ -591,7 +580,6 @@ export const apiCommands = [ "Updates saved sorting and partitioning rules for one source table object identifier (OID). Provide sort_by or partition_by; empty and reset-only patches are rejected. Omitted settings are preserved. Null makes a setting unmanaged. An empty partition list clears partitioning, and the none sort selector clears sorting. The backend validates the source schema and preserves other tables. When the layout changes, an active pipeline is restarted. A stopped pipeline stays stopped. reset_table defaults to false, preserving historical files and replication progress. When the layout changes, --reset-table resets the table and copies it again. This requires initial sync to be enabled. Reads are disrupted during the copy. An unchanged layout never restarts the pipeline or resets the table. Acceptance and application_status report orchestration. Run warehouse tables layout get to compare the desired and observed rules. Run warehouse tables get to check table replication status. These reads do not establish completion of this specific update. There is no revision, idempotency, resolved preview, or durable operation contract. A failed update can leave partial effects, including a completed reset. Inspect the saved layout, pipeline, and table state before retrying.", readOnly: false, confirmDescription: true, - feature: "warehouse", body: { contentType: "application/json", type: "warehouse_table_layout", @@ -669,7 +657,6 @@ export const apiCommands = [ description: "Lists the source tables selected for Warehouse replication with their replication status and freshness, from the same observations as the Warehouse status. Freshness comes from the replication slot that carries each table: its own sync slot until it follows changes, then the pipeline apply slot; one slot never stands in for the other. lag_ms is that slot's flush lag. Postgres reports no lag time for a caught-up slot without new WAL, so lag_ms can be null while replication_feedback.flush_lag_bytes is 0; neither is ever filled with zero when unknown. observed_at is when the API read the replication state, not when data last synchronized. A stopped, failed or unreadable pipeline reports its tables as stopped or unknown rather than live, and keeps each table's last recorded state. Returns an empty list when Warehouse is not set up, its publication is missing, or it is being disabled or failed to clean up.", readOnly: true, - feature: "warehouse", flags: [], bindings: [ { @@ -687,7 +674,6 @@ export const apiCommands = [ description: "Reads the current durable cleanup state without contacting ETL or inspecting the FDW. Disabling means cleanup is in progress; disabled means cleanup completed; deletion_failed means cleanup may be partial. The original data policy and failure reason remain available. Optionally supply operation_id to observe a specific disable attempt. Returns a conflict if no cleanup state is available or the supplied identity does not match the current operation.", readOnly: true, - feature: "warehouse", flags: [ { name: "operation-id", diff --git a/apps/cli/src/commands/api/runtime.ts b/apps/cli/src/commands/api/runtime.ts index ecb6c42ca0..c31013e096 100644 --- a/apps/cli/src/commands/api/runtime.ts +++ b/apps/cli/src/commands/api/runtime.ts @@ -398,7 +398,7 @@ export const withApiCommands = => { const merged: Array = [...handWritten]; for (const [name, noun] of Object.entries(nouns)) { - if (!enabledFeatures.includes(noun.feature)) continue; + if (!enabledFeatures.includes(noun.experimental)) continue; const position = merged.findIndex((command) => command.name > name); merged.splice(position < 0 ? merged.length : position, 0, groupAt([name], noun)); } From 3c932c04e0b662f8b6ab5f14702c07b5e519a8b7 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 22:35:44 +0100 Subject: [PATCH 44/45] chore(cli): drop the shared side-effects doc for generated commands Develop removed every per-command SIDE_EFFECTS.md; the generated per-command reference and the tests now carry the generated command contract. --- apps/cli/scripts/api-command-reference.ts | 2 +- apps/cli/src/commands/api/SIDE_EFFECTS.md | 177 ---------------------- apps/cli/src/commands/api/generated.md | 2 +- 3 files changed, 2 insertions(+), 179 deletions(-) delete mode 100644 apps/cli/src/commands/api/SIDE_EFFECTS.md diff --git a/apps/cli/scripts/api-command-reference.ts b/apps/cli/scripts/api-command-reference.ts index a629f6d15b..5beef0c3ed 100644 --- a/apps/cli/scripts/api-command-reference.ts +++ b/apps/cli/scripts/api-command-reference.ts @@ -186,7 +186,7 @@ export const renderApiCommandReference = (input: ApiCommandReferenceInput): stri "", "# Generated API commands", "", - "Reference for the commands generated from the Management API contract. The behavior every one of them shares (feature gates, consent, files, exit codes, output, `--wait`) is in [SIDE_EFFECTS.md](./SIDE_EFFECTS.md).", + "Reference for the commands generated from the Management API contract.", "", ...input.entries.flatMap((entry) => commandSection(entry, input)), ].join("\n"); diff --git a/apps/cli/src/commands/api/SIDE_EFFECTS.md b/apps/cli/src/commands/api/SIDE_EFFECTS.md deleted file mode 100644 index cdd8086570..0000000000 --- a/apps/cli/src/commands/api/SIDE_EFFECTS.md +++ /dev/null @@ -1,177 +0,0 @@ -# Generated API commands - -Target: hosted, see [Command target](../../../docs/command-target.md). Read-only commands ask for no -consent; mutations default to No (confirm unless `--yes`; a run that cannot prompt and has no `--yes` -is a usage error). - -Every command generated from the Management API contract shares this contract: one central policy -(`api-command-policy.ts`) selects the operations, `generated.ts` holds the derived command data, and -one runtime executes it. Hand-written commands keep their own `SIDE_EFFECTS.md`. The per-command -details (request route, request body, flags and where each binds, the `--wait` read) are in the -generated [per-command reference](./generated.md); that file is the source for routes, flag -bindings and wait settings, and the sections below do not repeat them. - -## Feature gate - -Each noun belongs to one feature. Its commands are registered only when `experimental.` is -enabled: set `[experimental] = true` or `SUPABASE_EXPERIMENTAL_=1`. The setting -is resolved before the command tree is built, so `--experimental` alone does not expose the -commands. When the feature is disabled the noun is absent from help, completion and the generated -command documentation. - -## Files Read - -| Path | Format | When | -| --------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- | -| `/supabase/config.json` | JSON | when present, to resolve `experimental.` before the command tree is built | -| `/supabase/config.toml` | TOML | when no `config.json` exists, for the same setting | -| `` | JSON | only with `--file `: the whole request body (`--file -` reads stdin) | -| `/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` is unset and the keyring holds no credential, unless `--dry-run` | -| `/supabase/.temp/project-ref` | plain text | legacy mode, when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | -| `/supabase/.link.json` | JSON | stack mode, when neither `--project-ref`/`--remote=` nor `SUPABASE_PROJECT_ID` is set | -| `/profile` | plain text | when neither `--profile` nor `SUPABASE_PROFILE` is set | - -Stack mode is on with `[experimental] stack = true` or `SUPABASE_EXPERIMENTAL_STACK=1`; otherwise the -project state is legacy. `` is the `--workdir` flag, else `SUPABASE_WORKDIR`, else the -nearest ancestor of the cwd holding `supabase/config.json` or `supabase/config.toml`, else the cwd. - -Commands never write project configuration, execute SQL locally or read stdin, except `--file -`. - -## Files Written - -| Path | Format | When | -| --------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/telemetry.json` | JSON | always, flushed on success and on failure | -| `/supabase/.temp/linked-project.json` | JSON | legacy mode, post-run, once the project ref resolved, only when no such file exists for that ref; never with `--dry-run` | -| `/project-cache/.json` | JSON | stack mode, post-run, once the project ref resolved, only when that file does not exist and `` is a well-formed project ref; never with `--dry-run` | - -## API Routes - -Each command sends the one request described in the [per-command reference](./generated.md), with -Bearer token authentication, and passes the JSON response through unchanged. The calls every command -can add: - -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | -------------------------------- | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `GET` | `/v1/projects` | Bearer token | none | only when no ref resolved and the session is interactive (project picker) | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}`; linked-project cache miss only (best-effort, after the command, never with `--dry-run`) | -| `GET` | `/v1/projects/{parent}/branches` | Bearer token | none | `[{id, name, project_ref, is_default}]` — only for `--remote=`, and for a bare `--remote` followed by a word that could name a branch; `{parent}` is `SUPABASE_PROJECT_ID`, else the linked project | -| `GET` | `/v1/branches/{id}` | Bearer token | none | `{ref, status, …}` — only for `--remote=` when no project is linked | - -With `--wait`, the command also polls the read operation named in its reference entry. - -### Request input - -- `--body` or `--file` supply the whole body; a flag replaces its own field and nothing else. -- A flag for a nested body field (an object, an array of objects or a union) takes a JSON value for - that field, `null` included; text that is not JSON is a usage error naming the flag. -- The input is validated before consent and before the command request: a top-level body key - outside the declared request-body fields, an unknown nested field or a missing required flag - fails with no command request sent. `-o`/`--output` and an invalid `--timeout` fail first, before - target resolution; for other input errors target resolution runs first, so the project picker and - branch lookups in the table above can still run. -- A body whose fields form alternatives (the request needs one of several fields) reports a missing - choice as `Pass at least one of --a, --b`. -- `--dry-run` prints `{method, path, query, headers, body}` and sends no command request, before - consent. A literal ref target (`--remote=`, `--project-ref`) needs no access token, sends no - request and writes no linked-project cache; only local files are read. A branch name, a bare - `--remote` or the project picker still call the API as listed above. It shows the local request, - not a server-resolved impact. -- Consent uses the command's summary as the action and lists what the validated request does: one - `name: value` line per non-ref path parameter, query parameter and body field (for an envelope - body, the fields under `data.attributes`). Scalars print as is; objects and arrays print as - compact JSON. Commands with `confirmDescription` also show their API description before an - interactive prompt. These describe effects without a resolved plan. -- Resync supports the same local request preview as add/remove, without a server-side dry-run - contract. Executing it resets one selected table through ETL and returns the immediate result; - it has no wait, idempotency or revision flags. Pipeline restarts can restart unfinished copies - of unrelated tables. - -## `--wait` - -A command whose reference entry has a Wait section accepts `--wait` and `--timeout ` -(a duration such as `90s` or `10m`; default `10m`; an invalid or non-positive value is a usage -error). `--timeout` is validated whenever it is passed, even without `--wait`, before consent and -before any command request. - -- A mutation first sends its request, then reads the identity the wait needs from the response by - the pointers in its reference entry. A missing value is a defect in the response and ends the wait - with an internal error, never a silent success. -- A read that polls itself sends no separate change request: its own input is polled. -- Polling repeats the read with backoff from 1s doubling to a 10s cap; a longer `Retry-After` on the - last response wins. -- The wait succeeds on a status in the succeeded set and fails (`operation_failed`) on a status in - the failed set. The failure pointer only supplies the error message and never ends the wait by - itself. -- Each poll read goes through the API client's own retries (429 and 5xx). Any non-2xx response left - after them, a 409 included, ends the command with the API error; the wait never resumes. -- At the timeout the command fails with `wait_timeout`. Timeout and cancellation stop local polling - only and do not change server state. -- The failure and timeout hint names the command that re-reads the state. When the polled read is a - generated command, the hint names it with the identity the wait polled with, for example - `supabase -- --remote=`. When the polled read is a hidden - read, the hint names the command its `x-operation.poll.inspect` operation generates, with only `--remote=`. -- With `--wait`, stdout carries the final read response instead of the change response. - -## Exit Codes - -| Code | Condition | -| ----- | ----------------------------------------------------------------------------------------------- | -| `0` | success: the request was accepted, the dry run printed, or the wait ended on a succeeded status | -| `2` | `usage_error`: invalid flags, body or timeout, or consent needed without `--yes` | -| `130` | consent declined at the prompt, or the run interrupted with Ctrl-C (`cancelled`) | -| `1` | API error (non-2xx) | -| `1` | with `--wait`: `operation_failed` (a failed status) or `wait_timeout` | - -A 4xx `entitlement_required` body (`{"error":{"code":"entitlement_required","feature","upgrade_url"}}`) -adds `entitlement: {feature, upgrade_url}` to the stderr error document in place of the -token-permission hint; a terminal run prints the upgrade hint, and `cli_upgrade_suggested` fires. -Other statuses and bodies carry no `entitlement` key. - -An interrupt (Ctrl-C) during the request or a `--wait` poll prints the `cancelled` failure with the -message `Interrupted` and exits `130`; it stops local work only and does not change server state. - -Errors use the standard stderr envelope. `wait_timeout` includes `timeout_ms`, a nullable -`last_status` and the hint command; terminal text includes the last status. `operation_failed` -includes the failed status and the reported failure message. - -## Environment Variables - -| Variable | Purpose | Required? | -| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -| `SUPABASE_EXPERIMENTAL_` | command registration (boolean `1`/`true` enables, `0`/`false` disables; unset/empty uses `experimental.`) | no | -| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring, then `access-token`) | -| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile`) | -| `SUPABASE_PROJECT_ID` | project ref, consulted after `--project-ref` | no (falls back to the linked project ref) | -| `SUPABASE_WORKDIR` | project directory the command acts on, consulted after `--workdir` | no (falls back to the discovered project root, then the cwd) | -| `SUPABASE_EXPERIMENTAL_STACK` | selects stack mode (`1`/`true`) or legacy mode (`0`/`false`) | no (falls back to `experimental.stack`) | -| `SUPABASE_HOME` | directory holding `telemetry.json`, and `project-cache/` in stack mode | no (falls back to `~/.supabase`) | -| `SUPABASE_YES` | consent for mutations in a shell; `supabase/.env` and a cwd `.env*` file do not count | no (falls back to `--yes`) | - -## Telemetry Events Fired - -| Event | When | Notable properties / groups | -| ---------------------- | ------------------------------------------ | ----------------------------------- | -| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | - -Only the names of flags passed appear in `flags`. Target flags record their values, and `--dry-run` -and `--wait` record `true`. Generated field flags, `--body`, `--file` and `--timeout` are recorded as -``. Response and error contents never become telemetry properties. - -## Output - -The presentation is text only when `--output-format` is `text` and stdout is a terminal; successes -and failures follow the same rule. Piped runs (even with `--output-format text`), agent runs and -`--output-format json|stream-json` keep the API's JSON bytes. `-o`/`--output` is a usage error that -points to `--output-format`, raised before target resolution, consent or any request. - -| Mode | stdout | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| text presentation | the response as labelled fields and tables, nested objects as indented blocks; a collection prints its scalar fields as a table, with each item's nested fields, null shown as `-`, in a block below it, and a `points` sample series shows its last 10 samples in response order with an omission notice (`--output-format json` shows all of them), `-` for null or empty values; with `--wait` the final read response; an empty response prints `Done.` and an empty collection `No results` | -| JSON presentation | the API's JSON response bytes, unchanged, preserving unknown and null fields; with `--wait` the final read response | -| `--dry-run`, text presentation | `Dry run: `, then `Query`, `Headers` and indented JSON `Body` blocks | -| `--dry-run` otherwise | the request preview in the selected JSON presentation | - -With the text presentation, each request, and with `--wait` the whole polling phase, runs under a -task that shows the polled status after 200 ms, as a spinner on the terminal. JSON output shows no -progress. diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index ddf83bbc19..e5af583312 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -2,7 +2,7 @@ # Generated API commands -Reference for the commands generated from the Management API contract. The behavior every one of them shares (feature gates, consent, files, exit codes, output, `--wait`) is in [SIDE_EFFECTS.md](./SIDE_EFFECTS.md). +Reference for the commands generated from the Management API contract. ## `supabase warehouse connection` From cdcbb7b140360f986a4a1926cfdd730e2c1c1fe2 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 23:03:06 +0100 Subject: [PATCH 45/45] fix(cli): keep generated command descriptions within the help Markdown contract The description contract test now builds the warehouse command tree, and the warehouse connection example is wrapped in a code span so `` no longer parses as HTML. --- apps/cli/src/commands/api/generated.md | 2 +- apps/cli/src/commands/api/generated.ts | 2 +- apps/cli/src/shared/output/description-contract.unit.test.ts | 1 + packages/api/scripts/openapi-overrides.json | 2 +- packages/api/src/generated/contracts.ts | 2 +- packages/api/src/generated/openapi.json | 2 +- 6 files changed, 6 insertions(+), 5 deletions(-) diff --git a/apps/cli/src/commands/api/generated.md b/apps/cli/src/commands/api/generated.md index e5af583312..c9240601ba 100644 --- a/apps/cli/src/commands/api/generated.md +++ b/apps/cli/src/commands/api/generated.md @@ -8,7 +8,7 @@ Reference for the commands generated from the Management API contract. Get Warehouse Flight SQL connection details -Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@\:443?tls=enabled'. +Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: `usql -W 'flightsql://postgres@\:443?tls=enabled'`. - Access: read-only, no consent. - Experimental: enable with `experimental.warehouse` or `SUPABASE_EXPERIMENTAL_WAREHOUSE=1`. diff --git a/apps/cli/src/commands/api/generated.ts b/apps/cli/src/commands/api/generated.ts index 815e0d7a28..977e85bd82 100644 --- a/apps/cli/src/commands/api/generated.ts +++ b/apps/cli/src/commands/api/generated.ts @@ -8,7 +8,7 @@ export const apiCommands = [ definition: "v2GetWarehouseConnection", summary: "Get Warehouse Flight SQL connection details", description: - "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.", + "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: `usql -W 'flightsql://postgres@:443?tls=enabled'`.", readOnly: true, flags: [], bindings: [ diff --git a/apps/cli/src/shared/output/description-contract.unit.test.ts b/apps/cli/src/shared/output/description-contract.unit.test.ts index c5435666d4..26f9dd5bea 100644 --- a/apps/cli/src/shared/output/description-contract.unit.test.ts +++ b/apps/cli/src/shared/output/description-contract.unit.test.ts @@ -65,6 +65,7 @@ describe("command description contract", () => { const root = rootCommandForFeatures({ stackBackend, computeEnabled, + apiFeatures: ["warehouse"], projectState: Exit.succeed(stackBackend), }); expect(violationsForTree(root)).toEqual([]); diff --git a/packages/api/scripts/openapi-overrides.json b/packages/api/scripts/openapi-overrides.json index 84c5de3b6e..a7329da8a0 100644 --- a/packages/api/scripts/openapi-overrides.json +++ b/packages/api/scripts/openapi-overrides.json @@ -690,7 +690,7 @@ "path": "/paths/~1v2~1projects~1{ref}~1warehouse~1connection", "value": { "get": { - "description": "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.\n\nThis endpoint is currently in its **Alpha** stage.", + "description": "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: `usql -W 'flightsql://postgres@:443?tls=enabled'`.\n\nThis endpoint is currently in its **Alpha** stage.", "operationId": "v2-get-warehouse-connection", "parameters": [ { diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts index e70553b138..ef808f05a2 100644 --- a/packages/api/src/generated/contracts.ts +++ b/packages/api/src/generated/contracts.ts @@ -24853,7 +24853,7 @@ export const operationDefinitions = { v2GetWarehouseConnection: { id: "v2GetWarehouseConnection", description: - "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.\n\nThis endpoint is currently in its **Alpha** stage.", + "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: `usql -W 'flightsql://postgres@:443?tls=enabled'`.\n\nThis endpoint is currently in its **Alpha** stage.", method: "GET", path: "/v2/projects/{ref}/warehouse/connection", pathParams: ["ref"], diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json index dbbcd3e4f0..17ff751cca 100644 --- a/packages/api/src/generated/openapi.json +++ b/packages/api/src/generated/openapi.json @@ -33015,7 +33015,7 @@ }, "/v2/projects/{ref}/warehouse/connection": { "get": { - "description": "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: usql -W 'flightsql://postgres@:443?tls=enabled'.\n\nThis endpoint is currently in its **Alpha** stage.", + "description": "Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: `usql -W 'flightsql://postgres@:443?tls=enabled'`.\n\nThis endpoint is currently in its **Alpha** stage.", "operationId": "v2-get-warehouse-connection", "parameters": [ {