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
28 changes: 28 additions & 0 deletions src/blocks/capability/CapabilityInputs.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import type { CapabilityInput } from '@/core/capabilities/manifest';
import { looksLikeKey } from '@/core/capabilities/credentialName';
import type { ValueType } from '@/core/capabilities/valueType';
import { isPlainList } from '@/core/capabilities/httpTarget';

export { looksLikeKey };

Expand Down Expand Up @@ -59,6 +60,20 @@ export function coerceInput(input: CapabilityInput, draft: unknown): unknown {
const value = Number(draft);
return Number.isFinite(value) ? value : draft;
}
if (isPlainList(input.schema) && !draft.trim().startsWith('[')) {
// "snippet, statistics": a list of plain values is typed comma-separated.
const itemKind = input.schema.items?.kind;
const parts = draft.split(',').map(part => part.trim()).filter(Boolean);
if (parts.length === 0) return undefined;
return parts.map(part => {
if (itemKind === 'number' || itemKind === 'integer') {
const value = Number(part);
return Number.isFinite(value) ? value : part;
}
if (itemKind === 'boolean') return part === 'true' ? true : part === 'false' ? false : part;
return part;
});
}
if (kind === 'object' || kind === 'array') {
try {
return JSON.parse(draft);
Expand Down Expand Up @@ -98,6 +113,7 @@ export function argumentsFrom(inputs: readonly CapabilityInput[], params: Record
function draftOf(value: unknown): FieldDraft {
if (typeof value === 'boolean') return value;
if (value === undefined || value === null) return '';
if (Array.isArray(value) && value.every(element => typeof element !== 'object' && !String(element).includes(','))) return value.join(', ');
if (typeof value === 'object') return JSON.stringify(value);
return String(value);
}
Expand Down Expand Up @@ -231,6 +247,18 @@ function Field({ input, idPrefix, value, wiredValue, onChange, disabled }: {
<option key={String(option)} value={String(option)}>{String(option)}</option>
))}
</select>
) : isPlainList(input.schema) ? (
<input
id={id}
type="text"
value={typeof draft === 'string' ? draft : ''}
placeholder={placeholder || 'one, two, three'}
disabled={disabled}
autoComplete="off"
aria-describedby={describedBy}
onChange={event => onChange(event.target.value)}
className={FIELD_CLASS}
/>
) : input.schema.kind === 'object' || input.schema.kind === 'array' ? (
<textarea
id={id}
Expand Down
22 changes: 19 additions & 3 deletions src/core/capabilities/compoundParameters.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@ function spec(parameter: Record<string, unknown>, method = 'get') {
}

describe('compound query and header parameters', () => {
it('leaves an optional array parameter out, and keeps the operation', () => {
const { manifests, errors } = compileOpenApi(spec({ name: 'eventTypes', in: 'query', style: 'form', explode: true, schema: { type: 'array', items: { type: 'string' } } }));
it('leaves an optional list it cannot send out, and keeps the operation', () => {
// Comma-joined (explode: false) is not sent; a plain exploded list is (listQueryParameters.test.ts).
const { manifests, errors } = compileOpenApi(spec({ name: 'eventTypes', in: 'query', style: 'form', explode: false, schema: { type: 'array', items: { type: 'string' } } }));
expect(errors).toEqual([]);
expect(manifests[0].inputs.map(input => input.name)).toEqual(['q']);
});
Expand All @@ -40,8 +41,23 @@ describe('compound query and header parameters', () => {
});

it('still refuses an operation whose required parameter is compound', () => {
const { manifests, errors } = compileOpenApi(spec({ name: 'ids', in: 'query', required: true, schema: { type: 'array', items: { type: 'string' } } }));
const { manifests, errors } = compileOpenApi(spec({ name: 'ids', in: 'query', required: true, schema: { type: 'array', items: { type: 'object', properties: { a: { type: 'string' } } } } }));
expect(manifests).toEqual([]);
expect(errors[0].message).toBe('ids: compound query parameters are outside the supported subset');
});
});

describe('optional parameters whose name cannot be an input', () => {
const xgafv = { name: '$.xgafv', in: 'query', schema: { type: 'string', enum: ['1', '2'] } };

it('leaves the Google $.xgafv parameter out of a read', () => {
const { manifests, errors } = compileOpenApi(spec(xgafv));
expect(errors).toEqual([]);
expect(manifests[0].inputs.map(input => input.name)).toEqual(['q']);
});

it('still refuses it on a write, and when it is required', () => {
expect(compileOpenApi(spec(xgafv, 'post')).manifests).toEqual([]);
expect(compileOpenApi(spec({ ...xgafv, required: true })).manifests).toEqual([]);
});
});
4 changes: 2 additions & 2 deletions src/core/capabilities/execute.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
// Side effects stop here until approveCapability has moved them to `approved`.

import { canonicalize, sha256 } from './hash';
import { joinUrl, resolveHttpPath, stringifyParam } from './httpTarget';
import { joinUrl, resolveHttpPath, setQueryParam, stringifyParam } from './httpTarget';
import { redact } from './redact';
import {
admitExecution,
Expand Down Expand Up @@ -180,7 +180,7 @@ function prepareRun(manifest: CapabilityManifest, args: Readonly<Record<string,
return { error: `${entry.name} carries the credential and cannot be supplied as an input` };
}
const value = args[entry.name];
if (entry.in === 'query') target.url.searchParams.set(entry.name, stringifyParam(value));
if (entry.in === 'query') setQueryParam(target.url.searchParams, entry.name, value);
else if (entry.in === 'header') headers[entry.name] = stringifyParam(value);
else if (entry.in === 'body') body = JSON.stringify(value);
}
Expand Down
21 changes: 21 additions & 0 deletions src/core/capabilities/httpTarget.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,33 @@
// A path argument fills one segment of the template and nothing else: the
// resolved pathname must be exactly the expanded template.

import type { ValueType } from './valueType';

export function joinUrl(baseUrl: string, path: string): URL {
const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
const relative = path.startsWith('/') ? path.slice(1) : path;
return new URL(relative, base);
}

/** An array of strings, numbers, or booleans: a query list Flyspace can send. */
export function isPlainList(schema: ValueType): boolean {
return schema.kind === 'array' && !!schema.items
&& (schema.items.kind === 'string' || schema.items.kind === 'number' || schema.items.kind === 'integer' || schema.items.kind === 'boolean');
}

/**
* Put one query argument on a URL. A list is sent the OpenAPI default way for
* a query (form, exploded): one `name=value` per element, in order.
*/
export function setQueryParam(params: URLSearchParams, name: string, value: unknown): void {
if (Array.isArray(value)) {
params.delete(name);
for (const element of value) params.append(name, stringifyParam(element));
Comment thread
sykosyber marked this conversation as resolved.
Resolved
return;
Comment thread
sykosyber marked this conversation as resolved.
Resolved
}
params.set(name, stringifyParam(value));
}

export function stringifyParam(value: unknown): string {
if (typeof value === 'string') return value;
if (typeof value === 'number' || typeof value === 'boolean') return String(value);
Expand Down
110 changes: 110 additions & 0 deletions src/core/capabilities/listQueryParameters.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { coerceInput } from '@/blocks/capability/CapabilityInputs';
import { executeCapability, previewCapabilityRun } from './execute';
import { setQueryParam } from './httpTarget';
import { compileOpenApi } from './openapi';
import { clearCapabilities, installProposal } from './registry';
import { capabilitySecrets } from './secrets';
import { createBrokerRateLimiter, handleCapabilityBroker } from '../services/server/capabilityBroker';
import { memoryLedger } from '../services/server/capability.ledger';
import type { PinnedRequest } from '../services/server/pinnedFetch';

/** YouTube's shape: `part` is a required list in the query. */
function spec(part: Record<string, unknown>, method = 'get') {
return {
openapi: '3.0.3',
info: { title: 'Videos', version: '1' },
servers: [{ url: 'https://videos.example.test' }],
paths: {
'/videos': {
[method]: {
operationId: 'videos.list',
parameters: [
{ name: 'part', in: 'query', required: true, ...part },
{ name: 'id', in: 'query', schema: { type: 'string' } }
],
responses: { '200': { description: 'ok', content: { 'application/json': { schema: { type: 'object', properties: { kind: { type: 'string' } } } } } } }
}
}
}
};
}

const LIST = { style: 'form', explode: true, schema: { type: 'array', items: { type: 'string' } } };

describe('compiling a list-valued query parameter', () => {
it('accepts a required list of plain values on a read', () => {
const { manifests, errors } = compileOpenApi(spec(LIST));
expect(errors).toEqual([]);
expect(manifests[0].inputs.find(input => input.name === 'part')).toMatchObject({ required: true, schema: { kind: 'array', items: { kind: 'string' } } });
});

it('accepts one with no style or explode given, the OpenAPI default for a query', () => {
expect(compileOpenApi(spec({ schema: { type: 'array', items: { type: 'integer' } } })).manifests).toHaveLength(1);
});

it('still refuses a comma-joined list, a list of objects, and any list on a write', () => {
const refused = (part: Record<string, unknown>, method?: string) => compileOpenApi(spec(part, method)).errors[0]?.message;
expect(refused({ ...LIST, explode: false })).toBe('part: compound query parameters are outside the supported subset');
expect(refused({ schema: { type: 'array', items: { type: 'object', properties: { a: { type: 'string' } } } } })).toBe('part: compound query parameters are outside the supported subset');
expect(refused(LIST, 'post')).toBe('part: compound query parameters are outside the supported subset');
});
});

describe('sending a list in the query', () => {
it('repeats the name once per element, in order', () => {
const params = new URLSearchParams('part=old');
setQueryParam(params, 'part', ['snippet', 'statistics']);
expect(params.toString()).toBe('part=snippet&part=statistics');
});

beforeEach(() => {
clearCapabilities();
capabilitySecrets.clear();
});
afterEach(() => {
vi.unstubAllGlobals();
clearCapabilities();
});

it('from the browser', async () => {
const [manifest] = compileOpenApi(spec(LIST)).manifests;
expect(installProposal(manifest).ok).toBe(true);
const preview = previewCapabilityRun(manifest.id, { part: ['snippet', 'statistics'], id: 'abc' });
expect(preview.ok && preview.preview.url).toBe('https://videos.example.test/videos?id=abc&part=snippet&part=statistics');
const fetchMock = vi.fn(async (_url: string) => new Response('{"kind":"list"}', { status: 200, headers: { 'content-type': 'application/json' } }));
vi.stubGlobal('fetch', fetchMock);
const result = await executeCapability(manifest.id, { part: ['snippet'] });
expect(result.error).toBeUndefined();
expect(new URL(fetchMock.mock.calls[0][0]).searchParams.getAll('part')).toEqual(['snippet']);
});

it('through the broker', async () => {
const [manifest] = compileOpenApi(spec(LIST), { brokerOrigins: ['https://videos.example.test'] }).manifests;
const seen: PinnedRequest[] = [];
await handleCapabilityBroker({ manifest, input: { part: ['snippet', 'statistics'] }, idempotencyKey: 'list-param-1' }, {
ledger: memoryLedger(),
limiter: createBrokerRateLimiter(),
resolve: async () => ['1.1.1.1'],
fetch: async request => {
seen.push(request);
return { status: 200, headers: {}, text: '{"kind":"list"}' };
}
});
expect(seen[0].url.searchParams.getAll('part')).toEqual(['snippet', 'statistics']);
});
});

describe('typing a list', () => {
const [manifest] = compileOpenApi(spec(LIST)).manifests;
const part = manifest.inputs.find(input => input.name === 'part')!;

it('splits comma-separated text, and treats an empty one as no value', () => {
expect(coerceInput(part, ' snippet, statistics ,')).toEqual(['snippet', 'statistics']);
expect(coerceInput(part, ' , ')).toBeUndefined();
});

it('still takes a JSON array', () => {
expect(coerceInput(part, '["snippet"]')).toEqual(['snippet']);
});
});
5 changes: 5 additions & 0 deletions src/core/capabilities/manifest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,11 @@ const SECRET_REF_PATTERN = /^[A-Za-z0-9_.:-]{1,64}$/;
export const MAX_AUTH_HINT = 300;
const NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]{0,64}$/;

/** Whether a name can be an input's name. */
export function isInputName(name: string): boolean {
return NAME_PATTERN.test(name);
}

/**
* Names an object property cannot hold as plain data: __proto__ (an
* accessor), prototype, and every name Object.prototype already defines
Expand Down
15 changes: 13 additions & 2 deletions src/core/capabilities/openapi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,14 @@
import { isKeyParameter, looksLikeKey } from './credentialName';
import { canonicalCapabilityId, credentialSlot } from './identity';
import { connectProvider, providerForAuthorizationUrl, providerForBaseUrl } from './connectProviders';
import { isPlainList } from './httpTarget';
import { fromJsonSchema } from './jsonSchema';
import {
approvalForEffect,
effectAllowedForMethod,
effectForMethod,
isInputHint,
isInputName,
isRecord,
sealManifest,
validateManifest,
Expand Down Expand Up @@ -467,14 +469,23 @@ function collectInputs(
const readOnly = method === 'GET' || method === 'HEAD';
if (!converted.ok && readOnly && location !== 'path' && parameter.required !== true && rawCompound) continue;
if (!converted.ok) return { error: `${String(parameter.name)}: ${converted.error}` };
if ((location === 'query' || location === 'header') && (converted.schema.kind === 'object' || converted.schema.kind === 'array')) {
const read = method === 'GET' || method === 'HEAD';
// A list of plain values in the query, sent the OpenAPI default way
// (form, exploded: `part=a&part=b`), is supported on a read: YouTube's
// list operations require one. Comma-joined lists (explode: false) are not.
const plainList = location === 'query' && read && isPlainList(converted.schema)
&& (parameter.style === undefined || parameter.style === 'form') && parameter.explode !== false;
if (!plainList && (location === 'query' || location === 'header') && (converted.schema.kind === 'object' || converted.schema.kind === 'array')) {
// An optional one can be left out of a read: the operation still
// works without it (Google Calendar's events.list and eventTypes).
// Not of a write, which would add write surface (AGENTS.md stop condition 3).
if (parameter.required !== true && (method === 'GET' || method === 'HEAD')) continue;
if (parameter.required !== true && read) continue;
return { error: `${String(parameter.name)}: compound ${location} parameters are outside the supported subset` };
}
const name = String(parameter.name);
// Google's optional `$.xgafv` (error format) cannot be an input name.
// Left out of a read like an unsendable optional; anything else refuses.
if (!isInputName(name) && parameter.required !== true && read && location !== 'path') continue;
const schema = withParameterDescription(converted.schema, parameter.description);
const hints = looksLikeKey(name, schema.description) ? {} : inputHints(parameter, deref(spec, parameter.schema));
inputs.push({
Expand Down
5 changes: 2 additions & 3 deletions src/core/services/server/capabilityBroker.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

import { assessEgress } from '@/core/capabilities/egress';
import { canonicalize, sha256 } from '@/core/capabilities/hash';
import { resolveHttpPath } from '@/core/capabilities/httpTarget';
import { resolveHttpPath, setQueryParam } from '@/core/capabilities/httpTarget';
import { redact } from '@/core/capabilities/redact';
import { validateManifest, type CapabilityManifest } from '@/core/capabilities/manifest';
import { MAX_SECRET_BYTES } from '@/core/capabilities/secrets';
Expand Down Expand Up @@ -316,8 +316,7 @@ function buildUrl(manifest: CapabilityManifest, input: Record<string, unknown>):
const url = target.url;
for (const entry of manifest.inputs) {
if (!Object.hasOwn(input, entry.name) || input[entry.name] === undefined || entry.in !== 'query') continue;
const value = input[entry.name];
url.searchParams.set(entry.name, typeof value === 'string' ? value : JSON.stringify(value));
setQueryParam(url.searchParams, entry.name, input[entry.name]);
}
return url;
}
Expand Down
Loading