gRPC
Restura speaks the Connect protocol on the web target and native gRPC over HTTP/2 (with automatic Connect-protocol fallback) on desktop — no local toolchain either way. On the web, Auto and Connect send JSON over Connect; for binary protobuf on the web pick the gRPC-Web wire protocol. On desktop, native gRPC and gRPC-Web are binary.
Discovering the service
Section titled “Discovering the service”- Server reflection — the fastest path. Hit Discover (next to the service/method picker) and Restura lists available services and methods. Reflection sends the request’s enabled Metadata and Auth (variables resolved), so servers that require credentials for reflection — API gateways, Envoy, Cloud Run with IAM — can be discovered. Automatic discovery, when a tab opens or its URL changes, sends the request’s own auth only. Discover also sends auth inherited from its folder or collection. Credentials stored as secret handles are resolved by the desktop app only; on the web, switch them to an inline value.
- Upload
.protofiles — pick one file, several files, or a whole folder (the folder button) and Restura compiles them on the fly. Imports resolve against the other uploaded files (by import path, relative to the importing file, or by file name). Thegoogle/protobuf/*well-known types (timestamp.proto,empty.proto,struct.proto, …) andgoogle/api/annotations.proto/http.proto/field_behavior.protoare built in. An import that can’t be resolved fails the upload with an error naming the missing file. - Upload a FileDescriptorSet — for monorepos that already ship a compiled set (
.binpb,.protoset,.desc,.pb— e.g.buf build -o api.binpborprotoc --include_imports -o api.binpb). Well-known types the set leaves out are filled in. - One picker — services from an uploaded
.protoor FileDescriptorSet appear in the same service/method picker as reflected ones (uploads first). Picking a method fills the message editor with a request template; after an upload, its first method is selected for you.
Saved requests keep their schema
Section titled “Saved requests keep their schema”When you save a gRPC request to a collection, Restura stores a snapshot of the schema you loaded — the reflected descriptors, the uploaded .proto, or the compiled descriptors of a multi-file / FileDescriptorSet upload — together with the request’s timeout. Reopening the request, running it in the collection runner, and exporting it to OpenCollection all reuse that snapshot (exports deduplicate identical snapshots; see Restura extensions). A saved request without a snapshot falls back to server reflection when it runs on desktop; if the server doesn’t offer reflection, the run fails asking you to open the request and reflect or upload a .proto.
Unknown request fields
Section titled “Unknown request fields”When the request has a schema (an upload, or reflection descriptors on desktop), the message editor flags JSON keys the method’s input message doesn’t define — nested, repeated and map-value messages included — as you type, with a Rename to ”…” quick fix for near misses (nmae → name) and a Remove action. What happens on send follows Settings → Requests → gRPC → Unknown request fields:
- Warn (default) — the editor shows the warning and the request is sent without the unknown keys.
- Block — the send is refused with
INVALID_ARGUMENTlisting the keys and suggestions. - Off — no lint; unknown keys are dropped silently.
The same policy applies to collection runs and to every message of a stream. Previously unknown keys were always dropped silently, so a typo sent the field’s default value.
Wire protocol
Section titled “Wire protocol”The request’s Settings → Wire Protocol selector is saved with the request (and in OpenCollection exports):
- Auto (default) — desktop dials native gRPC and falls back to Connect only when the server refuses native gRPC (HTTP 4xx other than 408/429, or 501/505 — e.g. a 415 or an edge refusing the gRPC content type). A transient 502/503/504 or a 429 is reported as-is and the call is never re-sent over another protocol. A server that needed the fallback is remembered (desktop session), but native gRPC is still tried if the Connect path is later refused, so the memo heals itself. Web sends Connect JSON through the Worker (unary, no schema needed). The CLI’s Auto is Connect only; a native-gRPC-only server fails with an explicit message saying so.
- gRPC desktop — native gRPC over HTTP/2 only, no fallback.
- gRPC-Web — binary
application/grpc-web+proto, for servers behind an Envoygrpc_webfilter, grpcwebproxy, or any Connect/gRPC-Web server. Unary and server streaming work on web (relayed by the Worker’s/api/grpc-web, messages streamed as they arrive) and desktop. Needs the schema — reflect or upload a.protofirst. - gRPC-Web text web — the base64
application/grpc-web-textvariant. - Connect — Connect protocol only.
gRPC-Web has no request streaming, so client and bidirectional streaming need native gRPC on desktop.
Path prefixes are kept on every wire protocol and target: https://gateway.example.com/grpc/ calls /grpc/pkg.Service/Method. URLs may use http:// / https:// everywhere and grpc:// / grpcs:// on desktop.
Status codes for non-gRPC replies — when something other than a gRPC server answers (an HTML 404 from a gateway, a native-gRPC-only server’s 415), the status comes from the HTTP code per the gRPC/Connect mapping (404 → UNIMPLEMENTED, 401 → UNAUTHENTICATED, 403 → PERMISSION_DENIED, 429/502/503/504 → UNAVAILABLE, others → UNKNOWN), and the error names the HTTP status instead of echoing the page. The Connect relay sends your deadline as Connect-Timeout-Ms.
Schema drift
Section titled “Schema drift”Each snapshot records a content hash and the time it was captured. When you reflect again and the server’s schema no longer matches the saved snapshot, the builder shows Schema changed since saved with a count of breaking and non-breaking changes. Details lists each change with its rule — removed services, methods, messages, fields, enums or enum values; changed request/response types; client- or server-streaming changes; field type, cardinality or oneof changes; and renamed fields, JSON names or enum values (breaking because requests are written as JSON). Additions are non-breaking. Update snapshot saves the new schema; Keep saved leaves the saved one in place. Until you update, the collection runner keeps using the saved snapshot. An uploaded schema (a .proto, a multi-file upload or a FileDescriptorSet) is never replaced by reflection.
Streaming
Section titled “Streaming”- Unary — request-response.
- Server streaming — single request, streamed responses. Live updates land in the response panel.
- Client streaming — multiple requests, single response. desktop only — not available on the web target.
- Bidirectional streaming — desktop only — not available on the web target. On the web the Client and Bidi method-type options are disabled with a Desktop only tooltip.
- Sending stream messages — while a client or bidirectional call is live on desktop, a message box next to Invoke sends messages and ends the client side. Cmd/Ctrl+Enter in the box sends the message; elsewhere, Cmd/Ctrl+Enter while a call is in flight cancels it.
- Stream tab — appears once a call has streamed messages and holds the message log.
- Web Stream tab — for any non-unary method the request builder adds a Web Stream tab with a separate message composer for streaming calls (send messages, end the client side, watch the log); Cmd/Ctrl+Enter there sends the message.
- Collection runs — the collection runner runs streaming requests to completion. Server streams run on web and desktop. Client and bidirectional streams run on desktop only: the runner sends the request message (a top-level JSON array sends one message per element), then closes the client side. On the web they’re skipped.
- Retries — the Settings tab retry policy also applies to server streams: a stream that ends with a non-OK status (other than a cancel) runs again. Client and bidirectional streams aren’t retried.
- Stream log — the Stream tab’s messages can be searched, filtered by direction, frozen, cleared, and exported as JSON or NDJSON.
- Long streams — a stream keeps its most recent 1,000 inbound messages (up to 10 MB of JSON). Older ones are dropped from the Stream tab, the response body and
pm.response.messages, and a N earlier messages dropped notice shows how many. - Response — the Body tab offers Pretty / Raw / Tree views, a JSONPath query, find, copy, and download (a streamed response’s frames appear as one JSON array, indexed by frame). Headers shows the server’s leading metadata and Trailers the
grpc-status/grpc-messageand any trailing metadata. - Rich error details — when an error carries
google.rpc.Statusdetails (from thegrpc-status-details-bintrailer or Connect’s error JSON), an Error details tab decodes them:BadRequest,ErrorInfo,RetryInfo,QuotaFailure,PreconditionFailure,DebugInfo,RequestInfo,ResourceInfo,HelpandLocalizedMessageas JSON, types from your loaded schema likewise, and anything else as its type plus raw base64 (Connect’sdebugrendering is shown too). Test scripts read the same list aspm.response.statusDetails. Works on web, self-hosted and desktop, unary and streaming, over every wire protocol (gRPC-Web included). - Field violations in the editor — when those details include a
google.rpc.BadRequest, each rejected field is underlined in the request message with the server’s description (nested and repeated paths such asbook.authors[1].email_addressare mapped to the JSON keys you wrote, using the request’s schema when one is loaded). The Error details tab lists the violations; click one to jump to the field. A field that is missing from the message is marked on its parent object. {{variables}}in the URL, service and method — autocompleted and highlighted (unresolved names are flagged). Resolved from globals, the environment, the collection and its folders at call time; the builder validates the resolved value when you send, not the template.- Names — service and method names follow protobuf identifier rules on every target: any-case package segments (
Company.Orders.OrderService), package-less services, and non-PascalCase methods (get_item). google.protobuf.Any— fields of typeAnyare encoded and decoded as JSON ({"@type": "type.googleapis.com/pkg.Type", …}) for any type in the loaded schema, on every wire protocol.
Deadlines and long-lived streams
Section titled “Deadlines and long-lived streams”Each call has a deadline, set in the Timeout (ms) field next to the request tabs. The default is 30 seconds. Streaming methods also have a No deadline checkbox, so watch or subscribe streams can stay open until you cancel them. Unary calls and collection runs always have a deadline. Cancelling a call stops it right away on every platform; on desktop the call in the main process is cancelled too and ends with CANCELLED.
On desktop, a stream with no messages in either direction for 15 minutes is closed. Its activity resets that timer, so a stream that keeps sending messages stays open. Every way a stream can end sends a final status, so the request leaves the streaming state. That includes a deadline, an idle close, and a cancel. Each message can be up to 10 MB; a bigger one ends the call with RESOURCE_EXHAUSTED.
Request settings
Section titled “Request settings”The request’s Settings tab holds, besides the wire protocol:
- Retry policy — max attempts (1 = no retry) and delay between attempts; a unary call or server stream that ends with a non-OK status runs again.
- Compression — Send gzip-compressed requests wraps outbound frames in gzip. desktop only — the web build warns and ignores it.
Retry policy and compression apply to sends from the request builder only. They aren’t saved with the request or exported, and the collection runner doesn’t use them.
Two more settings live elsewhere:
- Timeout — the Timeout (ms) field next to the request tabs (see above): 30 s by default, at least 1 s. Desktop accepts up to 600 s; through the web proxy the limit is 300 s, and a longer deadline is refused before sending.
- TLS desktop only — server certificate verification, custom CAs and client certificates (mTLS) come from the app’s Settings → Certificates, the same store HTTP uses, with per-host (and optionally per-port) entries taking precedence over the global certificate. Browsers can’t present client certificates or change the trust store.
Authentication
Section titled “Authentication”Pick the method in the request’s Auth tab (No Auth reads Inherit (…) when a folder or collection supplies one). Bearer, Basic, API Key (header placement) and OAuth 2.0 are sent as lowercase metadata; {{variables}} in their fields resolve at send time, like the URL and metadata. Keychain-stored secrets are resolved in the main process on desktop. The app’s gRPC rule for Basic requires both a username and a password. In the CLI, external secret references on gRPC items resolve like HTTP and fail the item explicitly when no resolver is available.
- Not supported for gRPC yet: AWS SigV4, OAuth 1.0, WSSE, Digest and NTLM. These need the exact wire bytes or a challenge round-trip that the gRPC transports don’t do. The auth tab shows a warning, and Send is blocked with an error rather than sending the call without credentials. As a workaround, set Auth to No Auth (on the request and on any folder or collection it inherits from) and put a pre-computed credential in a metadata entry. Inherited folder/collection auth is checked the same way as the request’s own, for unary and streaming calls.
- Custom metadata — gRPC uses metadata in place of HTTP headers; edit it in the same table as HTTP headers, with bulk edit (one
key: valueper line,//to disable a row) and an optional description per row. Values resolve{{variables}}. There is no per-entry size limit (multi-KB bearer JWTs are fine); total metadata, including auth, is capped at 16 KiB. Protocol headers the relay owns (content-type,connect-*,grpc-timeout, …) can’t be overridden from metadata. - Binary metadata — keys ending in
-bintravel base64-encoded on every wire protocol. A value that is already valid base64 (standard or URL-safe, padded or not) is sent as typed; any other value is treated as UTF-8 text and encoded for you. Short words made only of base64 characters (test,user1) are valid base64 too, so for text values in a-binkey enter the base64 yourself.
Scripts
Section titled “Scripts”Pre-request and test scripts run for every gRPC call type with the same rs.* / pm.* API as HTTP (Scripts), on web and desktop; the CLI runs unary calls only.
-
Streams — the pre-request script runs before the stream opens and the test script once it ends.
rs.response.messagesholds every message received (all(),count(),idx(i),each(fn));rs.response.codeis the final gRPC status andrs.response.json()returns the messages as an array. Each stream also gets one History entry. -
Edit outgoing metadata — in a pre-request script,
rs.request.metadataholds the enabled metadata rows (lowercased keys,{{variables}}resolved). Add, change ordeletekeys and the call is sent with the result. Auth metadata is added after the script and isn’t visible to it. -
Assert on metadata and trailers — in a test script,
rs.response.metadata(alias ofrs.response.headers) andrs.response.trailersexpose the leading and trailing metadata; the raw maps areresponse.headersandresponse.trailers.
// pre-requestrs.request.metadata['x-request-id'] = require('uuid').v4();
// testrs.test('trailer present', () => { rs.expect(rs.response.trailers.get('x-checksum')).to.exist;});
// test, server streamrs.test('three updates', () => rs.expect(rs.response.messages.count()).to.equal(3));Code export
Section titled “Code export”The Code button next to the method picker exports the call as a grpcurl or buf curl command (unary or streaming). It uses the enabled Metadata entries as typed — {{variables}} stay unresolved and Auth-tab credentials are not included.
Tracing
Section titled “Tracing”Restura auto-injects a W3C traceparent header on every gRPC request by default — useful when your services participate in distributed tracing. Override it by setting your own traceparent metadata entry — there is no setting to turn the auto-injection off.
Reflection over the web
Section titled “Reflection over the web”The web app reflects through a dedicated route, /api/grpc/reflection, which calls the server’s ServerReflectionInfo with Connect streaming framing (reflection v1, falling back to v1alpha). It works against any Connect-protocol server that exposes reflection. Because reflection is a bidirectional-streaming RPC, the hop from the proxy to your server must be HTTP/2: the self-hosted server negotiates HTTP/2 over TLS automatically, but a plaintext (h2c) server or a gRPC-only server (no Connect protocol) needs the desktop app, which speaks native gRPC.
Related
Section titled “Related”- Authentication — Bearer, Basic, API Key, OAuth 2.0 and mTLS.
- Workflows — OWS orchestration currently supports bound HTTP calls only; gRPC workflow calls are rejected until a bounded dispatcher exists.
- Architecture — how gRPC, HTTP, and MCP share one core.