Wire Protocol

1. Communication.

• Communication is performed using packets.
• The contents of a named pipe message are a single packet.
• A packet may contain any number of TransportMessage protos or raw binary payloads in sequence with no delimiting.

2. Data representation.

• Like gRPC itself, this wire protocol uses protobufs for protocol messages.
• The TransportMessage proto is defined here and includes several types of messages in a oneof:
  • RequestInit, Headers, PayloadInfo, RequestControl, Trailers

3. Initialization.

• Once the pipe connection is initiated, the client sends a RequestInit message with the fully qualified name of the method to call, and optionally a deadline.
• The client then sends a Headers message with any gRPC request headers.
• For unary and server-streaming methods, the client also sends the payload for gRPC request message (see 4).
• Pipe connections currently cannot be reused for multiple calls, a new pipe connection must be made for each. (This may be changed in the future.)

4. Payloads.

• A PayloadInfo message includes the number of bytes in the payload as well as an in_same_packet flag.
• If in_same_packet is true, the bytes of the payload immediately follow the PayloadInfo message.
  • e.g. Packet 1 { PayloadInfo 1, Payload 1, PayloadInfo 2, Payload 2 }
• If in_same_packet is false, the bytes of the payload are in a separate packet on their own.
  • e.g. Packet 1 { PayloadInfo 1, PayloadInfo 2} Packet 2 { Payload 1 } Packet 3 { Payload 2 }

Performance notes. Where possible, multiple messages (aside from large payloads) should be combined into a single packet. Choosing to use a payload in a separate packet should be done for large payloads, e.g. >15 kiB.

For Mac/Linux we currently use dotnet's named pipe abstraction which uses a fifo. The protocol is the same except that rather than using message-based transport to delimit packets, instead each packet is prefixed with 4 bytes (using system endianness) that is an int32 indicating the number of subsequent bytes in the packet.