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
22 changes: 22 additions & 0 deletions changes/feat-service-api-uploads-sign-in.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
### Added

- **A generated `api` command uploads a file's bytes.** For an operation whose body is an upload, as Petstore 3's
`application/octet-stream` image, `--body-file <path>` (or `-` for stdin) sends the file as it is, with the
operation's content type; such a command has no `--body`. A file in the CLI's own folders is refused, as for a JSON
body. Needs cli-base 0.112.0, whose generator reads such a body.
- **`serviceApiOperations(manifest)`** lists the operations the `api` group offers and why it leaves out the rest, so
a CLI's test runs exactly the commands that exist. `sendsBytes(operation)`, `readApiBytes(path)` and
`unsendableBody(operation)` are exported beside it.
- **`serviceApiCommand` and `serviceApiCall` take no `token` for a CLI without sign-in.** Left out, no call carries a
token, whatever the spec says; a CLI made with cli-template's `--sign-in none` passes none.

### Changed — may break callers

- **A call sends no token where the spec names no sign-in.** The `api` group and `serviceApiCall` now follow cli-base's
`signInRequirements`: the operation's own `security`, else the document's, and nothing when neither says anything.
Before, a manifest without `securitySchemes`, or an operation without requirements, got `Authorization: Bearer
<token>`. A CLI whose spec omits its sign-in now gets the service's refusal (401): generate with `auth`
(`{ securitySchemes, security, reason }`) to name it. A Discovery manifest gets its OAuth from cli-base 0.112.0's
generator; regenerate before taking this version.
- **An operation whose body is neither JSON nor an upload's bytes, such as a multipart form, is no longer offered.**
It always failed when run; now `api list` leaves it out and `api show <operation>` says why.
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,7 @@
"@types/pngjs": "6.0.5",
"@types/ssh2": "1.15.5",
"@vitest/coverage-v8": "^5.0.5",
"@wirecat/cli-base": "0.111.0",
"@wirecat/cli-base": "0.112.0",
"@wirecat/cli-core-legacy-tags": "npm:@wirecat/cli-core@0.414.0",
"ajv": "8.17.1",
"commander": "15.0.0",
Expand All @@ -325,7 +325,7 @@
},
"peerDependencies": {
"@napi-rs/canvas": ">=0.1.69 <2",
"@wirecat/cli-base": ">=0.108.0 <1.0.0",
"@wirecat/cli-base": ">=0.112.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.

10 changes: 8 additions & 2 deletions src/cli/app-mcp-command.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -351,7 +351,7 @@ describe("appDoctorCommand", () => {
"})",
].join("\n")

const check = async (signedIn: NonNullable<AppMcpOptions["signedIn"]>, keyring: KeyringStore) => {
const check = async (signedIn: AppMcpOptions["signedIn"], keyring: KeyringStore) => {
const env = home()
const scriptPath = join(env.CAL_STATE_DIR, "..", "server.mjs")
writeFileSync(scriptPath, FAKE_SERVER)
Expand All @@ -360,7 +360,7 @@ describe("appDoctorCommand", () => {
name: "Calendar",
untrusted: ["event titles"],
permissionExample: "events.delete=deny",
signedIn,
...(signedIn ? { signedIn } : {}),
})
const code = await run(["work", "mcp", "check", "--json"], { app, configuration, commands: () => [mcp] }, {
streams,
Expand Down Expand Up @@ -388,5 +388,11 @@ describe("appDoctorCommand", () => {
expect(code).toBe(0)
expect(item).toMatchObject({ healthy: false, signed_in: false })
})

it("is healthy for a CLI without sign-in, which gives no signedIn, and says nothing of an account", async () => {
const { code, item } = await check(undefined, memoryKeyring())
expect(code).toBe(0)
expect(item).toMatchObject({ healthy: true, signed_in: null })
})
})
})
24 changes: 19 additions & 5 deletions src/cli/bot/api-http.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,14 @@ 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 } from "./api-input.js"
import { parseApiJson, sendsBytes } from "./api-input.js"

export interface HttpApiRequest {
method: string
url: URL
headers: Headers
body?: string
/** JSON text, or an upload's bytes. */
body?: string | Uint8Array<ArrayBuffer>
/** `manual` for a request whose sign-in header a redirect to another host would carry along. */
redirect?: "follow" | "manual" | "error"
}
Expand Down Expand Up @@ -50,6 +51,14 @@ const segment = (name: string, value: string | undefined): string => {
return encodeURIComponent(value)
}

/** Why the generated command cannot send the operation's body, or `undefined` when it can: JSON, or an upload's bytes. */
export const unsendableBody = (operation: ManifestOperation): string | undefined => {
const type = operation.request?.contentType
return type === undefined || sendsBytes(operation)
? undefined
: `it sends ${type}, which the generated command cannot send`
}

/** One generated HTTP operation and its flags as the request they stand for; nothing is sent. */
export const httpApiRequest = (
operation: ManifestOperation,
Expand All @@ -59,10 +68,10 @@ export const httpApiRequest = (
const { binding } = operation
if (binding.kind !== "http")
throw new CliError("configuration_error", `${operation.command} is not an HTTP operation`)
if (operation.request?.contentType)
if (unsendableBody(operation))
throw new CliError(
"validation_error",
`${operation.command} sends ${operation.request.contentType}, which the generated command cannot send; nothing was sent`,
`${operation.command} sends ${operation.request?.contentType}, which the generated command cannot send; nothing was sent`,
{ sent: false },
)
if (operation.response?.sensitive)
Expand All @@ -85,11 +94,16 @@ export const httpApiRequest = (
else url.searchParams.set(name, raw)
}
const headers = new Headers(input.headers)
headers.set("accept", "application/json")
if (sendsBytes(operation)) {
if (input.bytes === undefined) return { method: binding.method, url, headers }
headers.set("content-type", operation.request?.contentType as string)
return { method: binding.method, url, headers, body: input.bytes }
}
const body = input.body?.trim() ? input.body : undefined
// The command's checkBody may not parse the body; text that is not JSON never reaches the service.
if (body !== undefined) parseApiJson(body)
if (body !== undefined) headers.set("content-type", "application/json")
headers.set("accept", "application/json")
return { method: binding.method, url, headers, ...(body === undefined ? {} : { body }) }
}

Expand Down
15 changes: 15 additions & 0 deletions src/cli/bot/api-input.ts
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,21 @@ export const checkApiParameter = (
}
}

const JSON_BODY = /[/+]json\s*(;|$)/i
const FORM_BODY = /^(multipart\/form-data|application\/x-www-form-urlencoded)\s*(;|$)/i

/** An upload sent as the bytes themselves, as the spec types a binary body: `application/octet-stream`, `image/png`. */
export const sendsBytes = (operation: ManifestOperation): boolean => {
const type = operation.request?.contentType
return type !== undefined && !JSON_BODY.test(type) && !FORM_BODY.test(type)
}

/** The file `--body-file` names, `-` for stdin, as the bytes an upload sends. */
export const readApiBytes = (
path: string,
read: (path: string | number) => Uint8Array<ArrayBuffer> = (from) => new Uint8Array(readFileSync(from)),
): Uint8Array<ArrayBuffer> => read(path === "-" ? 0 : path)

export const readApiBody = (
options: { body?: string; bodyFile?: string },
read: (path: string | number) => string = (path) => readFileSync(path, "utf8"),
Expand Down
24 changes: 22 additions & 2 deletions src/cli/bot/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,16 @@ 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 } from "./api-input.js"
import { apiFlagOf, apiOptionKey, readApiBody, readApiBytes, sendsBytes } from "./api-input.js"

export interface ApiCommandInput {
path: Record<string, string>
query: Record<string, string>
headers: Record<string, string>
fields: Record<string, string>
body?: string
/** An upload's bytes, from `--body-file`. */
bytes?: Uint8Array<ArrayBuffer>
bodySource?: "argument" | "stdin" | "file"
tokenProfile?: string
}
Expand All @@ -23,6 +25,8 @@ export interface ApiCommands {
checkBody?: (operation: ManifestOperation, text: string | undefined) => string | undefined
before?: (command: Command, operation: ManifestOperation) => void | Promise<void>
readBody?: (command: Command, options: { body?: string; bodyFile?: string }) => string | undefined
/** An upload's file, `-` for stdin. */
readBytes?: (command: Command, path: string) => Uint8Array<ArrayBuffer>
execute: (command: Command, operation: ManifestOperation, input: ApiCommandInput) => Promise<void>
}

Expand Down Expand Up @@ -50,7 +54,9 @@ export const generatedApiCommand = (api: ApiCommands): Command => {
)
command.addOption(parameter.required && parameter.in !== "body" ? option.makeOptionMandatory() : option)
}
if (operation.request) {
if (operation.request && sendsBytes(operation)) {
command.option("--body-file <path>", `the file to upload, sent as ${operation.request.contentType}; - is stdin`)
} else if (operation.request) {
// A field the schema marks secret may ride in an inline body, and the flags never see it.
command.addOption(secretInput(new Option("--body <json>", "the request body as JSON; - reads it from stdin")))
command.option("--body-file <path>", "the request body from a JSON file; - is stdin")
Expand Down Expand Up @@ -91,6 +97,20 @@ export const generatedApiCommand = (api: ApiCommands): Command => {
target[parameter.name] = raw
}
await api.before?.(this, operation)
if (sendsBytes(operation)) {
const path = options.bodyFile
if (path === undefined && operation.request?.required)
throw new CliError(
"validation_error",
`${operation.command} uploads a file: give --body-file <path>, or - for stdin`,
)
if (path !== undefined) {
input.bytes = (api.readBytes ?? ((_command, from) => readApiBytes(from)))(this, path)
input.bodySource = path === "-" ? "stdin" : "file"
}
await api.execute(this, operation, input)
return
}
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"
Expand Down
11 changes: 10 additions & 1 deletion src/cli/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,13 @@ export { askBeforeWrite } from "./ask-before-write.js"
export { actorOf } from "./author.js"
export { type BaseStagesCommandOptions, baseStagesCommand } from "./base-stages-command.js"
export type { ApiCommandInput, ApiCommands } from "./bot/api.js"
export { type HttpApiExecutorOptions, type HttpApiRequest, httpApiExecutor, httpApiRequest } from "./bot/api-http.js"
export {
type HttpApiExecutorOptions,
type HttpApiRequest,
httpApiExecutor,
httpApiRequest,
unsendableBody,
} from "./bot/api-http.js"
export {
apiFlagOf,
apiJson,
Expand All @@ -265,6 +271,8 @@ export {
checkApiParameter,
parseApiJson,
readApiBody,
readApiBytes,
sendsBytes,
} from "./bot/api-input.js"
export { prepareRpcApiBody, type RpcApiBody } from "./bot/api-rpc.js"
export { type BotContext, botContext, botWords } from "./bot/context.js"
Expand Down Expand Up @@ -675,6 +683,7 @@ export {
type ServiceApiOptions,
type ServiceApiPermissionsInput,
serviceApiKeys,
serviceApiOperations,
serviceApiPermissions,
} from "./service-api.js"
export { type ServiceApiCall, type ServiceApiCallOptions, serviceApiCall } from "./service-api-call.js"
Expand Down
3 changes: 2 additions & 1 deletion src/cli/service-api-call.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ export interface ServiceApiCallOptions {
service: string
/** The host-checked fetch with the CLI's pace and retry of reads, as the `api` group gets it. */
fetch: FetchLike
token: () => string | Promise<string>
/** Left out, for a CLI without sign-in, no call carries one. */
token?: () => string | Promise<string>
/** In place of the manifest's first server. */
baseUrl?: string
/** Headers beside the sign-in, such as the API version. */
Expand Down
Loading
Loading