Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions changes/feat-graphql-executor.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
### Added

- **The `api` group and `serviceApiCall` send a GraphQL operation** of a manifest that cli-base 0.115.0 generates
from a schema. Each call is one POST of the document `graphqlDocument` builds, never sent again on a redirect.
The variables are `--body` as one object with each flag over it, read by its schema: digits as written, `true` or
`false`, JSON for an input object. A variable the operation does not declare, or a required one left out, is
refused before anything is sent. The flags of a GraphQL operation are its body and stay out of the run's files.
- **`errors[]` is a failure even at HTTP 200.** A CLI's own `failure` names it first; else its `extensions.code`
does, repeated only when it is a plain constant, never the service's message. A write is `outcome_unknown` unless
the code says nothing ran and no data came back. The answer is `data.<field>`; `--all` pages by `pageInfo`.
- **`ApiCommandInput.selection`** gives a source a deeper selection than the generated one. `api list` and the run
record name a GraphQL operation as `POST` `query/issues`.

### Changed — may break callers

- **cli-core needs `@wirecat/cli-base` 0.115.0 or later**, whose manifest has the `graphql` binding.
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -313,7 +313,7 @@
"@types/pngjs": "6.0.5",
"@types/ssh2": "1.15.5",
"@vitest/coverage-v8": "^5.0.5",
"@wirecat/cli-base": "0.112.0",
"@wirecat/cli-base": "0.115.0",
"@wirecat/cli-core-legacy-tags": "npm:@wirecat/cli-core@0.414.0",
"ajv": "8.17.1",
"commander": "15.0.0",
Expand All @@ -337,7 +337,7 @@
},
"peerDependencies": {
"@napi-rs/canvas": ">=0.1.69 <2",
"@wirecat/cli-base": ">=0.112.0 <1.0.0",
"@wirecat/cli-base": ">=0.115.0 <1.0.0",
"commander": ">=15",
"mysql2": "^3.24.6",
"pg": "^8.23.1",
Expand Down
16 changes: 8 additions & 8 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

95 changes: 88 additions & 7 deletions src/cli/bot/api-http.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
import { CliError, wallClock } from "@wirecat/cli-base"
import type { ManifestOperation } from "@wirecat/cli-base/codegen"
import { CliError, type ErrorCode, wallClock } from "@wirecat/cli-base"
import { type GraphqlBinding, graphqlDocument, type ManifestOperation } from "@wirecat/cli-base/codegen"
import { type FetchLike, providerWaitMs, readJsonResponse, statusToCode } from "@wirecat/cli-base/http"
import type { Command } from "commander"
import { providerRequest } from "../command-runs.js"
import { outputFor } from "../context.js"
import { itemOf, renderAnswer } from "../envelope.js"
import type { ApiCommandInput } from "./api.js"
import { parseApiJson, sendsBytes } from "./api-input.js"
import { apiJson, graphqlVariables, parseApiJson, sendsBytes } from "./api-input.js"

export interface HttpApiRequest {
method: string
Expand Down Expand Up @@ -66,7 +66,7 @@ export const httpApiRequest = (
baseUrl: string,
): HttpApiRequest => {
const { binding } = operation
if (binding.kind !== "http")
if (binding.kind !== "http" && binding.kind !== "graphql")
throw new CliError("configuration_error", `${operation.command} is not an HTTP operation`)
if (unsendableBody(operation))
throw new CliError(
Expand All @@ -80,6 +80,7 @@ export const httpApiRequest = (
`${operation.command} answers with a credential, which the generated command never prints; nothing was sent`,
{ sent: false },
)
if (binding.kind === "graphql") return graphqlRequest(operation, binding, input, baseUrl)
if (Object.keys(input.fields).length > 0)
throw new CliError("configuration_error", `${operation.command} has body fields as flags, which HTTP cannot send`)
if (!/^\/(?!\/)/.test(binding.path))
Expand Down Expand Up @@ -107,9 +108,83 @@ export const httpApiRequest = (
return { method: binding.method, url, headers, ...(body === undefined ? {} : { body }) }
}

/** One GraphQL operation as a POST of its one document to the endpoint, with its variables. */
const graphqlRequest = (
operation: ManifestOperation,
binding: GraphqlBinding,
input: ApiCommandInput,
baseUrl: string,
): HttpApiRequest => {
const variables = graphqlVariables(operation, input.body, input.fields)
const headers = new Headers(input.headers)
headers.set("accept", "application/json")
headers.set("content-type", "application/json")
const query = graphqlDocument(binding, input.selection)
// A 307 or 308 would send the variables again, to wherever it points.
return { method: "POST", url: new URL(baseUrl), headers, body: apiJson({ query, variables }), redirect: "error" }
}

/** `/v1/pages/{page_id}` → `/v1/pages/:page_id`: the run record keeps the template, never an id. */
const templateOf = (path: string): string => path.replace(/\{([^}]+)\}/g, ":$1")

/** What the run record names a request by: the path template, or a GraphQL operation's root field. */
const endpointOf = (operation: ManifestOperation): string =>
operation.binding.kind === "http"
? templateOf(operation.binding.path)
: operation.binding.kind === "graphql"
? `${operation.binding.operation}/${operation.binding.field}`
: ""

// Common GraphQL server codes (Apollo's names) as the CLI's; any other is the provider's.
const GRAPHQL_CODES = {
UNAUTHENTICATED: "authentication_error",
AUTHENTICATION_ERROR: "authentication_error",
FORBIDDEN: "permission_error",
RATELIMITED: "rate_limited",
BAD_USER_INPUT: "validation_error",
GRAPHQL_VALIDATION_FAILED: "validation_error",
INVALID_INPUT: "validation_error",
} satisfies Record<string, ErrorCode>

// A refusal of these kinds means the service did nothing, so a write that got one is not in doubt.
const NOTHING_RAN = new Set<ErrorCode>(["authentication_error", "permission_error", "rate_limited", "validation_error"])

/**
* A GraphQL answer comes with HTTP 200 even when it failed: `errors[]` is the failure, named by the CLI's own
* `failure`, else by its first `extensions.code`, never by the service's message (WC-SECR-6). A write that failed in
* any other way, or answered data too, may have landed (WC-LIFE-9). Otherwise the answer is `data.<field>`.
*/
const graphqlAnswer = (options: HttpApiSendOptions, operation: ManifestOperation, answer: unknown): unknown => {
const { binding } = operation
if (binding.kind !== "graphql") return answer
const { data, errors } = (answer ?? {}) as { data?: Record<string, unknown> | null; errors?: unknown }
if (Array.isArray(errors) && errors.length > 0) {
const own = options.failure?.(200, answer, operation)
if (own) throw own
const raw = (errors[0] as { extensions?: { code?: unknown } } | null)?.extensions?.code
// The code is the service's text too: only a plain constant is repeated.
const code = typeof raw === "string" && /^[A-Z][A-Z0-9_]{0,40}$/.test(raw) ? raw : undefined
const known: ErrorCode = (code && GRAPHQL_CODES[code as keyof typeof GRAPHQL_CODES]) || "provider_error"
const writes = operation.effect !== "read"
if (writes && (!NOTHING_RAN.has(known) || data?.[binding.field] != null)) return outcomeUnknown(options.service)
throw new CliError(known, `${options.service} refused ${operation.command}${code ? ` (${code})` : ""}`, {
retryable: known === "rate_limited",
})
}
if (!data || !(binding.field in data))
throw new CliError(
"invalid_response",
`${options.service} answered ${operation.command} without data.${binding.field}`,
)
return data[binding.field]
}

const outcomeUnknown = (service: string): never => {
throw new CliError("outcome_unknown", `${service} did not confirm a write; check it before repeating the write`, {
retryable: false,
})
}

const answerOf = async (response: Response, maxBytes: number): Promise<unknown> => {
if (response.status === 204 || !response.body || response.headers.get("content-length") === "0") return {}
return readJsonResponse(response, { maxBytes })
Expand All @@ -126,7 +201,7 @@ export const httpApiSend =
(options: HttpApiSendOptions) =>
async (command: Command, operation: ManifestOperation, request: HttpApiRequest): Promise<unknown> => {
const writes = operation.effect !== "read"
const template = templateOf(operation.binding.kind === "http" ? operation.binding.path : "")
const template = endpointOf(operation)
const end = providerRequest(`${request.method} ${template}`, undefined, {
method: request.method,
endpointTemplate: template,
Expand Down Expand Up @@ -163,8 +238,14 @@ export const httpApiSend =
end({ status, error: failed })
throw failed
}
end({ status })
return answer
try {
const result = graphqlAnswer(options, operation, answer)
end({ status })
return result
} catch (error) {
end({ status, error })
throw error
}
}

/**
Expand Down
62 changes: 62 additions & 0 deletions src/cli/bot/api-input.ts
Original file line number Diff line number Diff line change
Expand Up @@ -160,3 +160,65 @@ export const apiPlainJson = (value: unknown): unknown =>
isLosslessNumber(inner) && !isSafeNumber(inner.value) ? inner.toString() : finite(key, inner),
) ?? "null",
)

/** A JSON object with no lossless number at its top: what a GraphQL body of variables must be. */
const isVariables = (value: unknown): value is Record<string, unknown> =>
value !== null && typeof value === "object" && !Array.isArray(value) && !isLosslessNumber(value)

/**
* A GraphQL operation's variables: the body's (`--body`, all of them as one object) with each flag over it, read by
* the variable's schema. A name the operation does not declare, or a required one left out, is refused unsent.
*/
export const graphqlVariables = (
operation: ManifestOperation,
body: string | undefined,
fields: Readonly<Record<string, string>>,
): Record<string, unknown> => {
const { binding } = operation
if (binding.kind !== "graphql")
throw new CliError("configuration_error", `${operation.command} is not a GraphQL operation`)
const given = body?.trim() ? parseApiJson(body) : {}
if (!isVariables(given))
throw new CliError("validation_error", `${operation.command} takes its variables as one JSON object`, {
sent: false,
})
const variables: Record<string, unknown> = { ...given }
for (const [name, raw] of Object.entries(fields)) {
const schema = operation.parameters.find((one) => one.in === "body" && one.name === name)?.schema
variables[name] = flagValue(operation, name, raw, schema?.type)
}
const unknown = Object.keys(variables).filter((name) => !(name in binding.variables))
if (unknown.length > 0)
throw new CliError("validation_error", `${operation.command} has no variable ${unknown.join(", ")}`, {
sent: false,
})
const missing = Object.entries(binding.variables)
.filter(([name, type]) => type.endsWith("!") && variables[name] == null)
.map(([name]) => `--${apiFlagOf(name)}`)
if (missing.length > 0)
throw new CliError("validation_error", `${operation.command} needs ${missing.join(", ")}`, { sent: false })
return variables
}

const DECIMAL = /^-?\d+(\.\d+)?$/

const flagValue = (operation: ManifestOperation, name: string, raw: string, type: string | undefined): unknown => {
const flag = `--${apiFlagOf(name)} of ${operation.command}`
if (type === "integer" || type === "number") {
// Number() would take 0x10 and 1e1, and round a long id; the digits go as written.
if (!(type === "integer" ? DIGITS : DECIMAL).test(raw.trim()))
throw new CliError("validation_error", `${flag} takes ${type === "integer" ? "a whole number" : "a number"}`, {
sent: false,
})
return new LosslessNumber(raw.trim())
}
if (type === "boolean") {
if (raw !== "true" && raw !== "false")
throw new CliError("validation_error", `${flag} takes true or false`, { sent: false })
return raw === "true"
}
if (type === "object" || type === "array" || type === "unknown") return parseApiJson(raw)
// An input object or a list given as JSON; an enum's value, behind a ref too, is a bare word.
if (type === "ref" && /^\s*[{["]/.test(raw)) return parseApiJson(raw)
return raw
}
24 changes: 21 additions & 3 deletions src/cli/bot/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,15 @@ import { annotate } from "@wirecat/cli-base/commands"
import { Command, Option } from "commander"
import { secretInput } from "../../runs/run-context.js"
import { REMOTE_READ, REMOTE_WRITE } from "../effects.js"
import { apiFlagOf, apiOptionKey, readApiBody, readApiBytes, sendsBytes } from "./api-input.js"
import {
apiFlagOf,
apiJson,
apiOptionKey,
graphqlVariables,
readApiBody,
readApiBytes,
sendsBytes,
} from "./api-input.js"

export interface ApiCommandInput {
path: Record<string, string>
Expand All @@ -16,6 +24,8 @@ export interface ApiCommandInput {
bytes?: Uint8Array<ArrayBuffer>
bodySource?: "argument" | "stdin" | "file"
tokenProfile?: string
/** A GraphQL operation's selection in place of its default, for a source that needs more than one level. */
selection?: string
}

export interface ApiCommands {
Expand Down Expand Up @@ -45,7 +55,9 @@ export const generatedApiCommand = (api: ApiCommands): Command => {
const binding =
operation.binding.kind === "http"
? `${operation.binding.method} ${operation.binding.path}`
: operation.binding.name
: operation.binding.kind === "graphql"
? `${operation.binding.operation} ${operation.binding.field}`
: operation.binding.name
const command = annotate(new Command(operation.command), {
effects: operation.effect === "read" ? REMOTE_READ : REMOTE_WRITE,
}).description(`${operation.summary ?? operation.id} — ${operation.effect} (${binding})`)
Expand All @@ -55,6 +67,8 @@ export const generatedApiCommand = (api: ApiCommands): Command => {
`--${apiFlagOf(parameter.name)} <value>`,
parameter.description?.split("\n")[0] ?? parameter.name,
)
// A GraphQL flag is the request body, which never reaches the run's files (SEC-196).
if (operation.binding.kind === "graphql" && parameter.in === "body") secretInput(option)
if (parameter.required && parameter.in !== "body") {
// A required parameter the spec gives a default (Notion's `Notion-Version`) is sent with it, never asked for.
const fallback = scalarOf(parameter.schema.default)
Expand Down Expand Up @@ -123,7 +137,11 @@ export const generatedApiCommand = (api: ApiCommands): Command => {
const text = (api.readBody ?? ((_command, body) => readApiBody(body)))(this, options)
if (options.body !== undefined) input.bodySource = options.body === "-" ? "stdin" : "argument"
else if (options.bodyFile !== undefined) input.bodySource = options.bodyFile === "-" ? "stdin" : "file"
const body = operation.binding.kind === "rpc" ? text : api.checkBody ? api.checkBody(operation, text) : text
// A GraphQL body is all the variables: the flags join it here, so the schema check sees what is sent.
const given =
operation.binding.kind === "graphql" ? apiJson(graphqlVariables(operation, text, input.fields)) : text
if (operation.binding.kind === "graphql") input.fields = {}
const body = operation.binding.kind === "rpc" ? text : api.checkBody ? api.checkBody(operation, given) : given
if (body !== undefined) input.body = body
await api.execute(this, operation, input)
})
Expand Down
Loading
Loading