@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/grpc/files.js

@@ -0,0 +1,62 @@
+/**
+ * The gRPC files of a project folder: `apis/<slug>/api.yaml` with `kind: grpc`, and each
+ * `*.request.yaml` of its request tree (spec §3.2).
+ */
+import { z } from 'zod';
+import { assertionsSchema } from '../assert/schema.js';
+import { authConfigSchema, keyValueEntrySchema, nonEmpty, scriptsSchema } from '../project/schema-parts.js';
+const grpcSettingsSchema = z.looseObject({
+    timeoutMs: z.number().int().nonnegative().optional(),
+    trustInvalid: z.boolean().optional(),
+    sslKeystoreRef: z.string().optional(),
+    bindAddress: z.string().optional(),
+    maxSizeBytes: z.number().int().nonnegative().optional(),
+    escapeProperties: z.boolean().optional(),
+});
+/** The four shapes a gRPC method can take. */
+export const grpcMethodKindSchema = z.enum(['unary', 'server-streaming', 'client-streaming', 'bidi-streaming']);
+/**
+ * `apis/<slug>/requests/[<folder>/…]<name>.request.yaml` for a gRPC request. The message text lives
+ * in the sibling file `message` names, validated as a path segment before it is read (ADR-0005),
+ * so a JSON message is a JSON file in git like a REST raw body.
+ */
+export const grpcRequestFileSchema = z.looseObject({
+    kind: z.literal('grpc'),
+    id: nonEmpty,
+    name: z.string(),
+    order: z.number().int(),
+    description: z.string().optional(),
+    service: z.string(),
+    method: z.string(),
+    methodKind: grpcMethodKindSchema.default('unary'),
+    metadata: z.array(keyValueEntrySchema).default([]),
+    message: nonEmpty.optional(),
+    auth: authConfigSchema.default({ type: 'inherit' }),
+    settings: grpcSettingsSchema.default({}),
+    orphaned: z.boolean().optional(),
+    assertions: assertionsSchema.default([]),
+    scripts: scriptsSchema.optional(),
+});
+/** `apis/<slug>/api.yaml` for a gRPC API. */
+export const grpcApiFileSchema = z.looseObject({
+    kind: z.literal('grpc'),
+    id: nonEmpty,
+    name: z.string(),
+    order: z.number().int(),
+    description: z.string().optional(),
+    target: z.string(),
+    tls: z.boolean().default(false),
+    metadata: z.array(keyValueEntrySchema).default([]),
+    auth: authConfigSchema.optional(),
+    definition: z
+        .looseObject({
+        // Absent in every project written before server reflection, which is an imported set.
+        kind: z.enum(['proto', 'reflection']).default('proto'),
+        source: nonEmpty,
+        cache: z.boolean().default(true),
+        roots: z.array(nonEmpty).default([]),
+        reflectionVersion: z.enum(['auto', 'v1', 'v1alpha']).optional(),
+        trustInvalid: z.boolean().optional(),
+    })
+        .optional(),
+});

package/dist/grpc/model.d.ts

@@ -13,8 +13,10 @@
  * entity survives a rename, `slug` is the file-system name derived from `name`, and nothing here
  * ever holds a secret — credentials are `secretRef`s resolved from the OS keychain at send time.
  */
+import type { Assertion } from '../assert/model.js';
+import type { RequestScripts } from '../script/model.js';
 import type { AuthConfig, CreateOptions, IdGenerator } from '../project/model.js';
-import type { KeyValueEntry } from '../rest/model.js';
+import type { KeyValueEntry } from '../http/entries.js';
 import type { GrpcMethodKind, GrpcReflectionVersion } from './shape.js';
 export { clientStreams, defaultTlsFor, GRPC_REFLECTION_VERSIONS, grpcMethodPath, serverStreams } from './shape.js';
 export type { GrpcMethodKind, GrpcReflectionVersion } from './shape.js';
@@ -66,6 +68,14 @@ export interface GrpcRequestDef {
      * is deleted on a re-import; the request survives badged, as a SOAP request does.
      */
     readonly orphaned?: boolean;
+    /**
+     * What `wirebench run` checks on the unary call's answer: the gRPC status code, the decoded
+     * response message as JSON, the duration. Optional so every place that builds a request without
+     * thinking about runs keeps compiling; absent reads as none.
+     */
+    readonly assertions?: readonly Assertion[];
+    /** Pre-request and post-response scripts, in files beside the request (#63). */
+    readonly scripts?: RequestScripts;
 }
 /** A named node in a gRPC API's tree. An import makes one per service. */
 export interface GrpcFolder {

package/dist/grpc/module.d.ts

@@ -0,0 +1,2 @@
+/** The gRPC protocol: APIs, their folders and their unary and streaming requests. */
+export declare const grpcProtocol: import("../protocol/module.js").ProtocolModule;

package/dist/grpc/module.js

@@ -0,0 +1,13 @@
+/** gRPC as a protocol module (spec §3). */
+import { defineProtocol } from '../protocol/module.js';
+import { grpcRun } from './run.js';
+import { grpcScripting } from './scripting.js';
+import { grpcStorage } from './storage.js';
+/** The gRPC protocol: APIs, their folders and their unary and streaming requests. */
+export const grpcProtocol = defineProtocol({
+    kind: 'grpc',
+    feature: { id: 'grpc', title: 'gRPC', default: true, stage: 'stable', requires: [] },
+    storage: grpcStorage,
+    run: grpcRun,
+    scripting: grpcScripting,
+});

package/dist/grpc/run.d.ts

@@ -0,0 +1,73 @@
+/**
+ * gRPC's run facet (spec §3.3). A run selects every method kind: a client or bidi stream sends its
+ * saved messages in order, then half-closes, and the run timeout bounds every stream (spec §5.2). A
+ * host drives a client or bidi stream's request side when it opens one interactive. A send resolves
+ * the call and refuses one
+ * it cannot make, loads the API's schema (without a schema there is no call, so no token is worth
+ * fetching; a schema that does not load is remembered for the run), runs its pre-request script,
+ * connects, then calls (spec §3.4).
+ */
+import type { AssertionSubject } from '../assert/model.js';
+import type { AuthConfig, Project } from '../project/model.js';
+import type { ProtocolRun } from '../protocol/module.js';
+import type { RunContext } from '../run/context.js';
+import type { Resolved } from '../run/send-helpers.js';
+import type { GrpcCallResult } from './call.js';
+import type { GrpcApi, GrpcFolder, GrpcRequestDef } from './model.js';
+import type { GrpcSendInput } from './send.js';
+/** One saved gRPC request selected for a run. */
+export interface GrpcSelected {
+    readonly kind: 'grpc';
+    readonly path: string;
+    readonly group: string;
+    readonly api: GrpcApi;
+    readonly chain: readonly GrpcFolder[];
+    readonly request: GrpcRequestDef;
+}
+/**
+ * What a failed call reports as its `SendFailure.input`: the call as far as it got, and its message
+ * text once resolved. It holds live credentials once connected; a host never logs it.
+ */
+export type GrpcFailedInput = GrpcResolvedInput & {
+    readonly messageText?: string;
+};
+/** A call ready for `callGrpc`, which also takes the API's proto set and the message text. */
+export type GrpcResolvedInput = Omit<GrpcSendInput, 'messages' | 'onMessage' | 'onOpen'>;
+/** The same chain for a gRPC request: request, its folders inside-out, the API. */
+export declare function grpcEffectiveAuth(selected: GrpcSelected): AuthConfig;
+/**
+ * The gRPC item for `requestId`, built as a run builds it — and found even when its contract no
+ * longer has it (`orphaned`), which a run skips and a person may still send. Undefined when no gRPC
+ * request has that id.
+ */
+export declare function grpcItemFor(project: Project, requestId: string): GrpcSelected | undefined;
+/**
+ * The app's `resolveGrpcSend` plus what its send handler adds (spec §3.4): the target through the
+ * environment's override for the API (the slot a REST base URL uses), the settings ladder, and one
+ * expansion pass over target, metadata and message, nothing connected. A reference nothing
+ * resolves is reported in `unresolved`, not thrown, and so is a call with no method chosen: the
+ * send refuses both (`refuseUnsendable`), a preview shows them.
+ *
+ * @throws WirebenchError `secret-missing`
+ */
+export declare function resolveGrpc(selected: GrpcSelected, context: RunContext): Promise<Resolved<GrpcResolvedInput> & {
+    readonly messageText: string;
+}>;
+/**
+ * The request's own TLS identity and trust decision and the chain's credentials (an OAuth2 token
+ * included), over a resolved call: what a send does after its pre-request script, so the script
+ * never sees a credential (spec §7). There is no proxy: the app sends gRPC direct as well.
+ *
+ * @throws WirebenchError `secret-missing` | `auth-grant-unsupported` | `keystore-missing`
+ */
+export declare function connectGrpc(selected: GrpcSelected, context: RunContext, input: GrpcResolvedInput): Promise<GrpcResolvedInput>;
+/**
+ * A call's answer as assertions see it: the gRPC status code (0 = OK), and its response as JSON. A
+ * unary or client-streaming call has one message: none, or one that did not decode, leaves nothing a
+ * `match` can read. A server-streaming or bidi call has every message, in order, as a JSON array,
+ * one that did not decode as `null` so the others keep their index.
+ * Exported for its unit test; not part of the run module's public surface.
+ */
+export declare function grpcSubject(result: GrpcCallResult): AssertionSubject;
+/** gRPC's run facet. */
+export declare const grpcRun: ProtocolRun<GrpcSelected>;

package/dist/grpc/run.js

@@ -0,0 +1,407 @@
+import { GrpcError, HttpError, isWirebenchError, WirebenchError } from '../errors.js';
+import { apiDefinitionDir } from '../project/paths.js';
+import { resolveAuthChain } from '../http/auth/apply-auth.js';
+import { scopesFor } from '../run/context.js';
+import { exchangeController } from '../run/exchange.js';
+import { authFor, baseUrlFor, dropRefusedToken, keystoreNeeds, tlsFor, unresolvedError, withSecrets, } from '../run/send-helpers.js';
+import { ORPHANED_STEP_REASON, findInTree, walkTree } from '../run/tree.js';
+import { applyGrpcSnapshot, grpcRequestSnapshot, grpcResponseSnapshot } from './scripting.js';
+import { grpcMessageTypes, grpcScriptTypes } from './script-types.js';
+import { secretNeedsOfAuth } from '../secrets/env-names.js';
+import { toGrpcSendInput } from './send-input.js';
+import { readGrpcDefinitionCache } from './cache.js';
+import { callGrpc } from './call.js';
+import { expandGrpcInput } from './expand.js';
+import { clientStreams, grpcMethodPath } from './model.js';
+import { loadProtoSet } from './proto/load.js';
+import { protoSetFromDescriptorSet } from './reflection/descriptors.js';
+import { grpcStatusNames } from './status.js';
+/** The same chain for a gRPC request: request, its folders inside-out, the API. */
+export function grpcEffectiveAuth(selected) {
+    const { api, chain, request } = selected;
+    return resolveAuthChain([request.auth, ...[...chain].reverse().map((folder) => folder.auth), api.auth]);
+}
+/**
+ * The gRPC item for `requestId`, built as a run builds it — and found even when its contract no
+ * longer has it (`orphaned`), which a run skips and a person may still send. Undefined when no gRPC
+ * request has that id.
+ */
+export function grpcItemFor(project, requestId) {
+    const candidates = [];
+    for (const api of project.grpcApis) {
+        walkTree(api, [], api.name, `apis/${api.slug}/requests`, (request, chain, group) => request.id === requestId
+            ? { kind: 'grpc', path: `${group}/${request.name}`, group, api, chain, request }
+            : undefined, candidates);
+    }
+    return candidates[0]?.item;
+}
+/**
+ * The app's `resolveGrpcSend` plus what its send handler adds (spec §3.4): the target through the
+ * environment's override for the API (the slot a REST base URL uses), the settings ladder, and one
+ * expansion pass over target, metadata and message, nothing connected. A reference nothing
+ * resolves is reported in `unresolved`, not thrown, and so is a call with no method chosen: the
+ * send refuses both (`refuseUnsendable`), a preview shows them.
+ *
+ * @throws WirebenchError `secret-missing`
+ */
+export async function resolveGrpc(selected, context) {
+    const { api, request } = selected;
+    const scopes = scopesFor(context);
+    const target = baseUrlFor(context, { slug: api.slug, baseUrl: api.target });
+    const unexpanded = toGrpcSendInput({
+        request: {
+            service: request.service,
+            method: request.method,
+            methodKind: request.methodKind,
+            metadata: request.metadata,
+            settings: request.settings,
+        },
+        target,
+        tls: api.tls,
+        apiMetadata: api.metadata,
+        // The user agent, socket timeout and TLS floor the app's own sends take from preferences.
+        ...(context.host.preferences !== undefined ? { preferences: context.host.preferences } : {}),
+        projectSettings: context.project.settings,
+        ...(context.signal !== undefined ? { signal: context.signal } : {}),
+    });
+    const withMessage = { ...unexpanded, messageText: request.message };
+    const withTokens = await withSecrets(withMessage, scopes, context.host.getSecret, context.secretPlaceholders);
+    const { input, unresolved } = expandGrpcInput(withMessage, withTokens, {
+        escape: request.settings.escapeProperties === true,
+    });
+    const { messageText, ...transport } = input;
+    return {
+        input: { ...transport, ...(context.timeoutMs !== undefined ? { timeoutMs: context.timeoutMs } : {}) },
+        messageText,
+        unresolved,
+    };
+}
+/**
+ * Refuses a resolved call the send cannot make, in the app's order: a reference nothing resolves,
+ * then no service or method chosen. Both come before the schema is loaded.
+ *
+ * @throws WirebenchError `grpc-unresolved-properties` | `grpc-method-unset`
+ */
+function refuseUnsendable(selected, resolved) {
+    if (resolved.unresolved.length > 0) {
+        throw unresolvedError('grpc-unresolved-properties', selected.path, resolved.unresolved);
+    }
+    if (selected.request.service === '' || selected.request.method === '') {
+        throw new WirebenchError('grpc-method-unset', 'Choose the service and method this request calls first.', {
+            details: { path: selected.path },
+        });
+    }
+}
+/**
+ * The request's own TLS identity and trust decision and the chain's credentials (an OAuth2 token
+ * included), over a resolved call: what a send does after its pre-request script, so the script
+ * never sees a credential (spec §7). There is no proxy: the app sends gRPC direct as well.
+ *
+ * @throws WirebenchError `secret-missing` | `auth-grant-unsupported` | `keystore-missing`
+ */
+export async function connectGrpc(selected, context, input) {
+    const { request } = selected;
+    const tls = await tlsFor(context, request.settings.sslKeystoreRef, request.settings.trustInvalid === true);
+    const auth = await authFor(grpcEffectiveAuth(selected), selected.path, context, tls);
+    return {
+        ...input,
+        ...(auth !== undefined ? { auth } : {}),
+        ...(tls !== undefined ? { tlsOptions: { ...input.tlsOptions, ...tls } } : {}),
+    };
+}
+/**
+ * Reads a gRPC API's schema from `apis/<slug>/definition/`, as the app's `grpcProtoSetFor` does:
+ * the `.proto` sources an import cached, or the descriptor set reflection cached. A run never
+ * reflects against a server, so an API with no cache has no schema and none of its calls can run.
+ *
+ * @throws WirebenchError `grpc-definition-missing` when there is no cache; whatever the loaders
+ * throw for one that does not load
+ */
+async function loadProtoSetFor(projectDir, api) {
+    let cache;
+    try {
+        cache = await readGrpcDefinitionCache(apiDefinitionDir(projectDir, api.slug));
+    }
+    catch (error) {
+        if (isWirebenchError(error) && error.code === 'definition-cache-missing') {
+            throw new WirebenchError('grpc-definition-missing', `The gRPC API "${api.name}" has no cached definition; import its .proto files or discover it in the app first.`, { details: { api: api.name }, cause: error });
+        }
+        throw error;
+    }
+    return cache.kind === 'proto'
+        ? loadProtoSet(cache.sources, { roots: cache.manifest.roots })
+        : protoSetFromDescriptorSet(cache.descriptors, { roots: cache.manifest.roots });
+}
+/**
+ * A call's answer as assertions see it: the gRPC status code (0 = OK), and its response as JSON. A
+ * unary or client-streaming call has one message: none, or one that did not decode, leaves nothing a
+ * `match` can read. A server-streaming or bidi call has every message, in order, as a JSON array,
+ * one that did not decode as `null` so the others keep their index.
+ * Exported for its unit test; not part of the run module's public surface.
+ */
+export function grpcSubject(result) {
+    const first = result.responseMessages[0];
+    const streamed = result.methodKind === 'server-streaming' || result.methodKind === 'bidi-streaming';
+    const decoded = streamed || (first !== undefined && first.json !== undefined);
+    const body = streamed ? result.responseMessages.map((message) => message.json ?? null) : first?.json;
+    return {
+        protocol: 'grpc',
+        status: result.exchange.status,
+        durationMs: result.exchange.durationMs,
+        bodyText: decoded ? JSON.stringify(body) : '',
+        bodyKind: decoded ? 'json' : 'other',
+        // Metadata first, then trailers: a header assertion or transfer takes the first value it finds.
+        headers: [...Object.entries(result.exchange.headers), ...Object.entries(result.exchange.trailers)],
+        statusNames: grpcStatusNames,
+    };
+}
+/** gRPC's `UNAUTHENTICATED`: the server's word for a credential it will not accept. */
+const GRPC_UNAUTHENTICATED = 16;
+/** gRPC's `DEADLINE_EXCEEDED`. */
+const GRPC_DEADLINE_EXCEEDED = 4;
+/**
+ * True when the deadline cut a stream a run made: the local deadline ended it, or the server said so
+ * once the deadline had passed. A unary call keeps `DEADLINE_EXCEEDED` as its status, for assertions.
+ */
+function deadlineCut(result, timeoutMs) {
+    const { exchange } = result;
+    return (result.methodKind !== 'unary' &&
+        exchange.status === GRPC_DEADLINE_EXCEEDED &&
+        // A server's own status 4 counts once the deadline has passed: the local one would have fired by then.
+        (exchange.statusSource === 'local' || exchange.durationMs >= timeoutMs));
+}
+/**
+ * The API's schema: the host's when it lends one, otherwise read from the definition cache once per
+ * run, a failed load remembered.
+ */
+async function protoSetFor(selected, scope, context) {
+    const lent = context.host.protoSetFor;
+    if (lent !== undefined)
+        return (await lent(selected));
+    const { api } = selected;
+    return scope.memo(`grpc:${api.id}:proto-set`, () => loadProtoSetFor(scope.context.projectDir, api));
+}
+/**
+ * What a failed call was about to put on the wire: an HTTP/2 POST to `/<service>/<method>`, its
+ * metadata. A call with no method chosen names its target alone.
+ */
+function attemptedOf(input) {
+    const path = input.service === '' || input.method === '' ? '' : grpcMethodPath(input.service, input.method);
+    return {
+        url: `${input.tls ? 'https' : 'http'}://${input.target}${path}`,
+        method: 'POST',
+        headers: Object.fromEntries(input.metadata.filter((row) => row.enabled).map((row) => [row.name, row.value])),
+    };
+}
+function streamClosed(halfClosed, settled) {
+    return new GrpcError('grpc-stream-closed', 'The request side of this call is already closed', {
+        details: { halfClosed, settled },
+    });
+}
+function grpcStreamState(controller) {
+    let side;
+    let waiting = [];
+    let ended = false;
+    /** The call has ended; when it never opened, nothing pushed now could be written. */
+    let done = false;
+    // Async only to turn a throw into a rejection: the body, and so the write, runs at once.
+    // eslint-disable-next-line @typescript-eslint/require-await
+    const write = async (handle, text) => handle.send(text);
+    const end = (handle) => {
+        handle.end();
+        controller.queue.push({ protocol: 'grpc', kind: 'closed' });
+    };
+    // `close` is a half-close too: a gRPC call is aborted by `cancel`, never by its request side.
+    const halfClose = () => {
+        if (ended)
+            return;
+        ended = true;
+        // Before the call opens, the opening ends it once the pushes made before now are written.
+        if (side !== undefined)
+            end(side);
+    };
+    return {
+        streaming: {
+            push: (message) => {
+                if (!('text' in message)) {
+                    return Promise.reject(new WirebenchError('exchange-not-streaming', 'A gRPC call takes its messages as JSON text, not binary', {
+                        details: { protocol: 'grpc', reason: 'binary' },
+                    }));
+                }
+                if (ended)
+                    return Promise.reject(streamClosed(true, false));
+                if (side !== undefined)
+                    return write(side, message.text);
+                if (done)
+                    return Promise.reject(streamClosed(false, true));
+                return new Promise((resolve, reject) => waiting.push({ text: message.text, resolve, reject }));
+            },
+            halfClose,
+            close: halfClose,
+        },
+        opened(handle) {
+            side = handle;
+            controller.queue.push({ protocol: 'grpc', kind: 'open' });
+            const queued = waiting;
+            waiting = [];
+            for (const push of queued)
+                write(handle, push.text).then(push.resolve, push.reject);
+            if (ended)
+                end(handle);
+        },
+        settled() {
+            done = true;
+            const queued = waiting;
+            waiting = [];
+            for (const push of queued)
+                push.reject(streamClosed(ended, true));
+        },
+    };
+}
+/**
+ * One gRPC request as a run or a host sends it (spec §3.4): resolve, run its pre-request script when
+ * `scripts` is given, connect, call, then its post-response script. A failure is told to the host
+ * with its stage and what was attempted: a reference nothing resolves in the prepare stage.
+ */
+async function sendGrpcItem(selected, scope, context, scripts, mode) {
+    const { controller, live, run, stream } = mode;
+    let startedAt = Date.now();
+    // Never masks the send's own error: a row that cannot be built, or a host that throws, is dropped.
+    const failed = (stage, error, attempted, messageText) => {
+        try {
+            const input = attempted === undefined ? undefined : { ...attempted, ...(messageText !== undefined ? { messageText } : {}) };
+            context.host.events?.onFailed?.(selected, {
+                stage,
+                error,
+                startedAt,
+                durationMs: Date.now() - startedAt,
+                ...(attempted !== undefined ? { attempted: attemptedOf(attempted), input } : {}),
+            });
+        }
+        catch {
+            // Deliberately ignored — see above.
+        }
+    };
+    try {
+        let input;
+        let connected;
+        let messageText;
+        let protoSet;
+        let sent;
+        try {
+            const resolved = await resolveGrpc(selected, scripts !== undefined ? { ...context, secretPlaceholders: scripts.placeholders } : context);
+            input = resolved.input;
+            messageText = resolved.messageText;
+            refuseUnsendable(selected, resolved);
+            // Before the send connects: without a schema there is no call, so no token is worth fetching.
+            protoSet = await protoSetFor(selected, scope, context);
+            if (scripts === undefined) {
+                connected = await connectGrpc(selected, context, resolved.input);
+            }
+            else {
+                const before = grpcRequestSnapshot(resolved.input, resolved.messageText);
+                sent = await scripts.session.pre(before);
+                const changed = applyGrpcSnapshot(resolved.input, resolved.messageText, before, sent);
+                const restored = await scripts.placeholders.restore({ metadata: changed.input.metadata, messageText: changed.messageText }, context.host.getSecret);
+                input = { ...changed.input, metadata: restored.metadata };
+                messageText = restored.messageText;
+                connected = await connectGrpc(selected, context, input);
+            }
+        }
+        catch (error) {
+            failed('prepare', error, input, messageText);
+            throw error;
+        }
+        const sentText = messageText;
+        // The send stage's own clock: a send-stage failure never counts resolve, the script or the token.
+        startedAt = Date.now();
+        let result;
+        try {
+            result = await callGrpc({
+                ...connected,
+                set: protoSet,
+                messageText: sentText,
+                signal: controller.signal,
+                // Only a live send decodes each message as it arrives; any other has them all in the result.
+                ...(live
+                    ? {
+                        onHeaders: (headers, httpStatus) => controller.queue.push({ protocol: 'grpc', kind: 'headers', httpStatus, headers }),
+                        onMessage: (message, index) => controller.queue.push({ protocol: 'grpc', kind: 'message', index, message }),
+                    }
+                    : {}),
+                ...(stream !== undefined ? { onOpen: (handle) => stream.opened(handle) } : {}),
+            });
+            if (run && deadlineCut(result, connected.timeoutMs)) {
+                throw new HttpError('timeout', 'The request timed out.', { details: { target: connected.target } });
+            }
+        }
+        catch (error) {
+            failed('send', error, connected, sentText);
+            throw error;
+        }
+        dropRefusedToken(context, connected.auth, result.exchange.status === GRPC_UNAUTHENTICATED);
+        return {
+            subject: grpcSubject(result),
+            raw: result.exchange,
+            exchange: { kind: 'grpc', grpc: result, input: connected, messageText: sentText },
+            origin: connected.target,
+            ...(scripts !== undefined
+                ? { script: await scripts.session.post(sent, grpcResponseSnapshot(result)) }
+                : {}),
+        };
+    }
+    finally {
+        stream?.settled();
+    }
+}
+/** gRPC's run facet. */
+export const grpcRun = {
+    groups(project) {
+        return project.grpcApis.map((api) => {
+            const candidates = [];
+            walkTree(api, [], api.name, `apis/${api.slug}/requests`, (request, chain, group) => request.orphaned === true
+                ? undefined
+                : { kind: 'grpc', path: `${group}/${request.name}`, group, api, chain, request }, candidates);
+            return { order: api.order, name: api.name, candidates };
+        });
+    },
+    whyNotRunnable(project, requestId) {
+        for (const api of project.grpcApis) {
+            const request = findInTree(api, requestId);
+            if (request !== undefined) {
+                return request.orphaned === true ? ORPHANED_STEP_REASON : undefined;
+            }
+        }
+        return undefined;
+    },
+    open(selected, scope, host, options) {
+        const controller = exchangeController('grpc', options);
+        const context = { ...scope.context, host, signal: controller.signal };
+        // Only a client or bidi stream has a request side to drive; any other call refuses a push.
+        const stream = options.interactive && clientStreams(selected.request.methodKind) ? grpcStreamState(controller) : undefined;
+        const mode = {
+            controller,
+            live: options.live === true,
+            run: options.run === true,
+            ...(stream !== undefined ? { stream } : {}),
+        };
+        return controller.handle(() => sendGrpcItem(selected, scope, context, options.scripts, mode), stream?.streaming);
+    },
+    resolve(selected, scope, host) {
+        return resolveGrpc(selected, { ...scope.context, host });
+    },
+    async scriptTypes(selected, scope) {
+        // A schema that does not load leaves the messages untyped; the send reports the missing schema.
+        const protoSet = await protoSetFor(selected, scope, scope.context).catch(() => undefined);
+        const types = grpcMessageTypes(protoSet, selected.request.service, selected.request.method);
+        return {
+            generated: grpcScriptTypes(types === undefined ? undefined : protoSet, types?.input ?? '', types?.output ?? ''),
+        };
+    },
+    secretNeeds(selected, project) {
+        return [
+            ...secretNeedsOfAuth(grpcEffectiveAuth(selected)),
+            ...keystoreNeeds(project, selected.request.settings.sslKeystoreRef),
+        ];
+    },
+};

package/dist/grpc/script-types.d.ts

@@ -0,0 +1,8 @@
+import type { ProtoSet } from './proto/load.js';
+/** `WbRequestMessage` and `WbResponseMessage` for a method's input and output types. */
+export declare function grpcScriptTypes(set: ProtoSet | undefined, inputType: string, outputType: string): string;
+/** A gRPC method's request and response message types, when the set has the method. */
+export declare function grpcMessageTypes(set: ProtoSet | undefined, service: string, method: string): {
+    readonly input: string;
+    readonly output: string;
+} | undefined;