gRPC messages, schemas and mocks
The free app shows a gRPC call's status, deadline and metadata. With Wirescry Pro, its details also show the messages it sent and received, and the APIs tab holds your gRPC schemas: calls a schema describes show field names, and are checked against it.
Reading calls doesn't change them or your schemas. Rules can reply to gRPC calls, breakpoints can edit their messages, and Compose can send a gRPC call you write as JSON. Apart from passing calls on, Wirescry contacts a server only when you ask it for its schema, or send it a call from Compose.
The gRPC section
Select a gRPC call, and its details have a gRPC section. gRPC and gRPC-Web calls are marked by their type, and so are Connect's streams. A Connect unary call has no type of its own, so the section also shows for a reply of protobuf (application/proto), and for a POST answered with JSON whose path names a method of a service with a package, such as /shop.v1.Orders/Get. Other JSON requests don't get it. The section has:
- Method: the service and method, such as
shop.v1.Orders/Get. - Protocol: gRPC, gRPC-Web, gRPC-Web (text), Connect or Connect (stream), with ", JSON" for calls whose messages are JSON.
- Schema: the schema that describes the method, or a note when none does, with a button to ask the server for its schema.
- Types: the method's request and response types, from its schema.
- Status: for gRPC-Web and Connect calls that send their status in the body, the status found there.
- Request and Response: each message, numbered, with its size and whether it was compressed.
While a call is still going, such as a stream, each side shows its newest messages as they arrive (see below).
Compressed messages (gzip, deflate, Brotli and Zstandard) are decompressed first. A message is read with its schema when a schema has the method, and by field number when none does. Show fields by number shows the fields by number even when there's a schema. Messages sent as JSON, such as Connect's application/json or application/grpc+json, show as the JSON that was sent.
Without a schema
Protobuf messages don't carry their field names, so without a schema each field shows as its number and its value: a number, text when the bytes read as text, the fields of a message inside it when they read as one, or hex bytes. Hover over the number for the field's wire type. The bytes don't say whether a number is signed, zigzag-encoded or a float, so the other ways to read it show beside it, such as (signed -1, float NaN) for a 32-bit field.
With a schema
With a schema, each message shows as protobuf's JSON form, with field names and enum names: {"status": "SERVING"}. Fields at their default value are left out, as protobuf's JSON does. A message over 256 KB is shown by field number instead.
A message the schema doesn't fit says why, and is shown by field number. So is one holding a google.protobuf.Any of a type the schema doesn't have.
While a call is going
A call that's still going shows each side's messages as they arrive: "1 message so far", then more. Only the newest 200 are shown, with a note saying how many earlier ones aren't. gRPC-Web's trailers and Connect's end of stream show as the call's status when they arrive. Once the call ends, the section reads all of it as for any finished call, so its first messages show again.
Two kinds of call show their messages only once they end: a body compressed as a whole (with a Content-Encoding header), and a unary Connect call, which has one message. Messages show live once the server has sent its response headers; a server that sends nothing until the end, as some do for a client stream, shows its call's messages when it ends.
Adding a schema
Wirescry reads compiled descriptor sets, not .proto files. Make one with either:
protoc --descriptor_set_out=api.binpb --include_imports api.proto
buf build -o api.binpb--include_imports puts the files your .proto imports in the set too; without it, Wirescry says a file is missing. buf build includes them.
The file must end in .binpb, .pb, .desc, .bin or .protoset. Rename a descriptor set with another extension before adding it.
In the APIs tab, under gRPC schemas, click Add a schema… and choose the file. The list shows each schema with its services and methods. Adding the same file again, after compiling it again, say, replaces the schema added from it.
Wirescry reads its own copy of the schema, made when you added it, so changing or moving the file changes nothing until you add it again. Remove takes a schema out of Wirescry; the file is kept.
When two schemas have the same method, the one added first is used. A schema from a server comes first for that server's calls.
Limits
| Limit | |
|---|---|
| Schemas | 20 |
| One schema file | 4 MB |
| All schemas | 16 MB together |
| Message types, enums and services | 50,000 per schema |
Of a call, Wirescry reads up to 200 messages a side, messages up to 4 MB, and 16 MB decompressed in all. Very large or deeply nested messages are read in part, and the section says so.
Getting the schema from the server
Many gRPC servers can describe their own services, through gRPC server reflection. For such a server, you don't need a schema file.
Select a gRPC call that has no schema, and in its gRPC section click Get the schema from the server…. The button is there for gRPC calls with protobuf messages, not for gRPC-Web, Connect or JSON calls. Wirescry names the server it would ask, such as api.example.com:443. Click Ask the server, and Wirescry sends the server new calls asking for its services and the .proto files that define them. Nothing is sent before you click it. Cancel stops asking.
When it's done, the section says how many calls it sent and how many services the schema has, and reads the call again with it. Anything the server couldn't describe is listed.
- Only that server's calls: a schema from a server applies to calls with the same host in their URL, including its port when the URL names one, and comes before a schema from a file for them. Calls to other servers aren't read with it.
- In the APIs tab: it shows as "api.example.com:443 (from the server)", and hovering over it says which server it was asked of. Remove it as any other schema.
- Asking again: a call read with a server's schema has Ask the server again…, which replaces it. Do this after the server's API changes.
Many servers switch reflection off in production. Only ask servers you have permission to query.
What is sent
The new calls go straight to the server, not through Wirescry's proxy, and carry only the call's host name (:authority). Nothing else from the call is sent: no credentials, cookies, metadata or messages. A server that requires credentials for reflection refuses, and Wirescry shows its reason.
Over HTTPS, the server's certificate is checked as for any HTTPS connection, against the same certificates the proxy trusts.
When Wirescry won't ask
Wirescry asks only when it can reach the server the way the call did. It says why when it won't:
- The call was loaded from a HAR file, sent from the Compose tab, or came from an Android device, another machine or a container.
- A rule or breakpoint handled it, or a rule blocked it.
- Its request is still being sent.
- It went over plain HTTP to another computer. Wirescry asks over HTTPS, or over plain HTTP to servers on this computer only.
- It went to Wirescry itself.
Asking fails, with the reason, when the server has no reflection service, refuses, isn't a gRPC server, or doesn't answer.
Limits
| Limit | |
|---|---|
| Time | 30 seconds in all |
| One answer | 4 MB |
| All answers | 16 MB |
| Services asked about | 50 |
.proto files | 500 |
| The schema it makes | 4 MB, as for a schema file |
One server is asked at a time. A schema from a server counts toward the limits for schemas, as one added from a file does.
Badges
Each call whose service is in one of your schemas is checked against it, and gets a badge in the traffic list. Hover over it for more.
| Badge | What it means |
|---|---|
| Schema | Its messages fit the method's types. |
| Schema, partly | Nothing checked was wrong, but part of the call couldn't be checked, such as a body that wasn't kept, or JSON messages. |
| Schema: 2 issues | Something doesn't fit the schema. |
| Not in schema | A schema has the service, but not this method. |
Calls to services no schema has get no badge. Select a call with a badge, and the gRPC section says what matched and what didn't.
What's checked
These are issues:
- A message that doesn't fit its type.
- A
google.protobuf.Anyof a type the schema doesn't have. - A message with fields its type doesn't have. The section names their numbers.
- Several messages on a side the method doesn't stream, such as a unary call's request.
- No message on a side the method doesn't stream, when the call ended OK.
- A body that ends in the middle of a message, when the connection didn't fail.
A call whose connection failed, or that its client canceled, isn't faulted for what it didn't send. Nor is a call that ended with an error status for a message it didn't send. Messages sent as JSON, such as Connect's application/json, aren't checked yet.
Results are kept for the most recent 10,000 gRPC calls. When you add or remove a schema, the traffic in the list is checked again, newest first.
Replying to gRPC calls
A rule can answer gRPC calls itself, so you can try a client against replies a server rarely gives: an error, an empty list, a slow answer, or a stream that fails halfway.
- In the Rules tab, choose New rule.
- Under gRPC method, enter the service, such as
shop.v1.Orders, and a method, such asGet. Both are offered from your schemas. Leave the method empty, or enter*, for any method of the service. - Choose the action Reply as gRPC, set the reply, and click Add rule.
The quickest way is Mock… on a gRPC call in the traffic list. It starts a rule with the call's method, host and query, and its status, status message and reply, read whole with its schema. Without an active license, it starts a plain mock instead.
The gRPC method
A gRPC method matches only gRPC calls to it: gRPC, gRPC-Web and Connect POSTs. A REST call whose path happens to look the same doesn't match. A Connect unary call is told apart by its Connect-Protocol-Version header, so a call without it doesn't match, and Connect GET calls never do. A call with a prefix before the service in its path, such as /api/shop.v1.Orders/Get, matches too. A rule with a gRPC method uses no path, and its method is Any or POST. Other conditions, such as the host or a header, still apply.
A gRPC method also works with other actions, such as pausing the calls.
The reply
| Field | What it sets |
|---|---|
| Status | OK, or an error code by name, such as NOT_FOUND (5). |
| Status message | For an error: what went wrong, sent as grpc-message (in Connect, the error's message). |
| Reply (JSON) | Each message in protobuf's JSON form, such as {"id": "o-42", "totalCents": "1250"}. Fill in from schema writes one with every field at its default. Add a message adds another. |
| Response metadata | Headers sent before any message, one name: value per line. |
| Trailing metadata | Metadata sent with the status. |
| Delay (ms) | How long to wait first, up to 10 minutes. |
A reply has at most 100 messages and 256 KB of message JSON in all, and a status message of up to 1,000 bytes. Metadata has up to 100 entries in all. Each line is a lowercase name of letters, digits and -_., then a value of plain ASCII. A name ending -bin takes a base64 value. Names starting grpc-, connect- or trailer-, and ones HTTP sets itself, such as content-type or te, are refused.
How many messages a reply has depends on the method:
- A unary method, or a client stream: one message when OK, and none on an error. Switching to an error clears the messages.
- A server stream, or a bidirectional one: any number, sent one after another, then the status, which may be an error.
Client and bidirectional streams get the reply once the client finishes sending: rules wait for the whole request.
The reply goes out in the format the call used: gRPC, gRPC-Web (and its text form) or Connect, with protobuf or JSON messages. Over native gRPC, an error with no messages and no response metadata goes out the way gRPC servers send errors, in one block with the status, which clients with a retry policy may retry. With response metadata, the headers go first, and such clients won't retry. gRPC-Web and Connect carry the status in the body, as they always do.
Schemas and checks
Messages are encoded with the schema for each call's method and server, as the gRPC section picks it. When you save a rule in the editor, the reply is checked against the schemas its calls could use. Imported rules aren't checked until their calls arrive.
- It fits none of them: the save is refused with the reason, because every call would fail.
- It fits some but not others: it's saved with a note naming the ones it doesn't fit.
- No schema has the method yet: it's saved with a note. Until one does, its calls get
INTERNAL: Wirescry has no schema with shop.v1.Orders/Get.
An error with no messages needs no schema. That's the only reply a rule for any method of a service can give.
Calls from web pages
A web page's gRPC-Web or Connect call to another site needs that site's permission (CORS). For a call from a page, the reply says the page may read it. Before the call, the browser asks with a preflight (an OPTIONS request). Wirescry answers that too, as long as the rule doesn't depend on headers or the body, which a preflight doesn't carry. The answer isn't cached, so a rule you change or switch off doesn't keep answering for the server.
Which clients
A mock never contacts the server, so it works for clients that reach Wirescry over HTTPS, and over plain HTTP/2 (h2c) through the proxy. Native gRPC needs HTTP/2; gRPC-Web and Connect also work over HTTP/1.1. Mocks haven't been tested with Android apps yet.
gRPC calls at breakpoints
A breakpoint pauses a gRPC call only where that can't stall it, by its method's kind in your schemas:
| Method | Paused at |
|---|---|
| Unary | The request and the response, as the rule says. |
| Server stream | The request only. Its messages stream through. |
| Client stream | The response only. |
| Bidirectional stream | Never. |
gRPC calls none of your schemas describe aren't paused, except Connect's unary calls: they can't stall, so they pause like other requests, with their body as text.
A paused gRPC call that one of your schemas describes shows each message as JSON, read with its schema, instead of the body. Edit a message, and it's encoded again with the schema and sent uncompressed. Fields the schema doesn't know are left out of it. Messages you don't change, or change only in their spacing, keep their content, fields the schema doesn't know included. A gRPC-Web trailer frame, or a Connect end message, passes on unchanged. Messages can't be edited when there are more than 100, or the body is over 256 KB on the wire, once decompressed, or as JSON.
At the request, Reply as gRPC answers the call without contacting the server, in its own format. Its form has a status, a status message, the messages and both kinds of metadata, as a rule's reply does, but no delay or Fill in from schema. At the response, the status and trailers come from the server and can't be changed here; the messages can.
While a call is paused, its deadline shows: The client gives up in 4 s, or that it already has. When the request is sent on, its deadline (grpc-timeout or connect-timeout-ms) is shortened by the time it was held, so the server stops when the client does.
Composing a gRPC call
In the Compose tab, From a gRPC schema fills the composer with a call to a method from your gRPC schemas:
- Choose the Method. Unary and server-streaming methods are listed: Compose sends one request message, so client and bidirectional streams aren't. A schema you got from a server fills in that server.
- Type the Server, such as
api.example.comorlocalhost:8443. With no server, the URL uses a{{server}}variable, for an environment to fill in. - Choose the Format: gRPC, Connect, protobuf or Connect, JSON. A server stream can only be sent as gRPC.
- Click Fill in.
The composer then holds a POST to https://server/package.Service/Method with the format's headers: Content-Type: application/grpc and grpc-timeout: 30S for gRPC; Content-Type and Connect-Protocol-Version: 1 and Connect-Timeout-Ms: 30000 for Connect. The body is the request message as JSON, with every field at its default. Edit it, and the headers, as you like.
On Send, Wirescry fills in variables, then encodes the JSON with the method's schema for that server (the server's own, if you got one from it) and sends the bytes:
- gRPC (
application/grpc) goes over HTTP/2, with the message in gRPC's 5-byte frame andte: trailers. The reply, its trailers and its status show under the editor and in Traffic, decoded with the schema. Cancel stops a call or a stream. - Connect, protobuf (
application/protowithConnect-Protocol-Version) sends the encoded message alone. - Connect, JSON and other types are sent as written.
The composer keeps the JSON, so a saved request keeps it too. For gRPC and Connect, protobuf, Send refuses, with the reason:
- A message that isn't JSON, nests too deeply, or doesn't fit the method's request type, such as a field the type doesn't have. An empty body too.
- A URL whose path doesn't end in a method, such as
/shop.v1.Orders/Get, or that still has a{{variable}}no environment set. - A method none of your schemas for that server has, a client or bidirectional stream, and a server stream sent as Connect, protobuf.
- gRPC to an
http://URL. Wirescry reaches a server over HTTP/2 only with TLS, so gRPC calls needhttps://. Calls to a server without TLS (h2c) can't be sent from Compose. - More than 256 KB of JSON.
Copy as refuses a call that Send encodes: the code would send its JSON, not protobuf.
Edit and resend
Edit and resend on a captured gRPC or Connect call opens Compose with its request message as JSON, read with the method's schema for that server. Send encodes it again. The headers saying how the body was compressed (grpc-encoding, connect-content-encoding and Content-Encoding) are left out, since Send sends the message uncompressed. A Connect call that sent an empty message opens with {}.
When the message can't be copied, Compose opens without it, and a note says why:
- None of your gRPC schemas has the method.
- The method streams its requests, or the call sent more than one message. Compose sends one.
- Wirescry didn't keep the request body, couldn't read it, or it's more than 256 KB as JSON.
- It's a binary gRPC-Web call, a gRPC call with JSON messages, or a Connect stream, which Compose can't send.
If the message had fields the schema doesn't, it's filled in without them, and a note says so. A gRPC call to an http:// URL is filled in, with a note that Compose sends gRPC only to https://. Connect unary calls in JSON, and gRPC-Web text, are text, so Edit and resend copies them as they are, as for any other request.
Where schemas are stored
In the plugins/pro folder of Wirescry's data folder:
| File or folder | What it holds |
|---|---|
grpc-schemas.json | The list of schemas: each one's source path, or the server it was asked of, and what the tab shows about it. |
grpc-schemas/ | Wirescry's copy of each schema file. |
The files are unencrypted. Remove deletes a schema's copy. Wirescry never sends a schema anywhere.
When Pro is locked
Without an active license, the gRPC section says Pro needs a license, and the APIs tab shows how to start a trial or enter a key. Calls aren't checked, Pro's badges come off the traffic list, and rules and breakpoints don't apply. Compose doesn't send gRPC or Connect, protobuf calls: Send says Pro needs a license. Edit and resend leaves a gRPC call's message out, as for any body that isn't text. Your schemas and rules are kept, and when Pro is active again, the calls still in the list are checked again.