1.. _module-pw_rpc-protocol: 2 3=============== 4Packet protocol 5=============== 6.. pigweed-module-subpage:: 7 :name: pw_rpc 8 9Pigweed RPC servers and clients communicate using ``pw_rpc`` packets. These 10packets are used to send requests and responses, control streams, cancel ongoing 11RPCs, and report errors. 12 13Packet format 14============= 15Pigweed RPC packets consist of a type and a set of fields. The packets are 16encoded as protocol buffers. The full packet format is described in 17``pw_rpc/pw_rpc/internal/packet.proto``. 18 19.. literalinclude:: internal/packet.proto 20 :language: protobuf 21 :lines: 14- 22 23The packet type and RPC type determine which fields are present in a Pigweed RPC 24packet. Each packet type is only sent by either the client or the server. 25These tables describe the meaning of and fields included with each packet type. 26 27Client-to-server packets 28------------------------ 29+---------------------------+-------------------------------------+ 30| packet type | description | 31+===========================+=====================================+ 32| REQUEST | Invoke an RPC | 33| | | 34| | .. code-block:: text | 35| | | 36| | - channel_id | 37| | - service_id | 38| | - method_id | 39| | - payload | 40| | (unary & server streaming only) | 41| | - call_id (optional) | 42| | | 43+---------------------------+-------------------------------------+ 44| CLIENT_STREAM | Message in a client stream | 45| | | 46| | .. code-block:: text | 47| | | 48| | - channel_id | 49| | - service_id | 50| | - method_id | 51| | - payload | 52| | - call_id (if set in REQUEST) | 53| | | 54+---------------------------+-------------------------------------+ 55| CLIENT_REQUEST_COMPLETION | Client requested stream completion | 56| | | 57| | .. code-block:: text | 58| | | 59| | - channel_id | 60| | - service_id | 61| | - method_id | 62| | - call_id (if set in REQUEST) | 63| | | 64+---------------------------+-------------------------------------+ 65| CLIENT_ERROR | Abort an ongoing RPC | 66| | | 67| | .. code-block:: text | 68| | | 69| | - channel_id | 70| | - service_id | 71| | - method_id | 72| | - status | 73| | - call_id (if set in REQUEST) | 74| | | 75+---------------------------+-------------------------------------+ 76 77**Client errors** 78 79The client sends ``CLIENT_ERROR`` packets to a server when it receives a packet 80it did not request. If possible, the server should abort it. 81 82The status code indicates the type of error. The status code is logged, but all 83status codes result in the same action by the server: aborting the RPC. 84 85* ``CANCELLED`` -- The client requested that the RPC be cancelled. 86* ``ABORTED`` -- The RPC was aborted due its channel being closed. 87* ``NOT_FOUND`` -- Received a packet for a service method the client does not 88 recognize. 89* ``FAILED_PRECONDITION`` -- Received a packet for a service method that the 90 client did not invoke. 91* ``DATA_LOSS`` -- Received a corrupt packet for a pending service method. 92* ``INVALID_ARGUMENT`` -- The server sent a packet type to an RPC that does not 93 support it (a ``SERVER_STREAM`` was sent to an RPC with no server stream). 94* ``UNAVAILABLE`` -- Received a packet for an unknown channel. 95 96Server-to-client packets 97------------------------ 98+-------------------+-------------------------------------+ 99| packet type | description | 100+===================+=====================================+ 101| RESPONSE | The RPC is complete | 102| | | 103| | .. code-block:: text | 104| | | 105| | - channel_id | 106| | - service_id | 107| | - method_id | 108| | - status | 109| | - payload | 110| | (unary & client streaming only) | 111| | - call_id (if set in REQUEST) | 112| | | 113+-------------------+-------------------------------------+ 114| SERVER_STREAM | Message in a server stream | 115| | | 116| | .. code-block:: text | 117| | | 118| | - channel_id | 119| | - service_id | 120| | - method_id | 121| | - payload | 122| | - call_id (if set in REQUEST) | 123| | | 124+-------------------+-------------------------------------+ 125| SERVER_ERROR | Received unexpected packet | 126| | | 127| | .. code-block:: text | 128| | | 129| | - channel_id | 130| | - service_id (if relevant) | 131| | - method_id (if relevant) | 132| | - status | 133| | - call_id (if set in REQUEST) | 134| | | 135+-------------------+-------------------------------------+ 136 137All server packets contain the same ``call_id`` that was set in the initial 138request made by the client, if any. 139 140**Server errors** 141 142The server sends ``SERVER_ERROR`` packets when it receives a packet it cannot 143process. The client should abort any RPC for which it receives an error. The 144status field indicates the type of error. 145 146* ``NOT_FOUND`` -- The requested service or method does not exist. 147* ``FAILED_PRECONDITION`` -- A client stream or cancel packet was sent for an 148 RPC that is not pending. 149* ``INVALID_ARGUMENT`` -- The client sent a packet type to an RPC that does not 150 support it (a ``CLIENT_STREAM`` was sent to an RPC with no client stream). 151* ``RESOURCE_EXHAUSTED`` -- The request came on a new channel, but a channel 152 could not be allocated for it. 153* ``ABORTED`` -- The RPC was aborted due its channel being closed. 154* ``INTERNAL`` -- The server was unable to respond to an RPC due to an 155 unrecoverable internal error. 156* ``UNAVAILABLE`` -- Received a packet for an unknown channel. 157 158Invoking a service method 159========================= 160Calling an RPC requires a specific sequence of packets. This section describes 161the protocol for calling service methods of each type: unary, server streaming, 162client streaming, and bidirectional streaming. 163 164The basic flow for all RPC invocations is as follows: 165 166* Client sends a ``REQUEST`` packet. Includes a payload for unary & server 167 streaming RPCs. 168* For client and bidirectional streaming RPCs, the client may send any number of 169 ``CLIENT_STREAM`` packets with payloads. 170* For server and bidirectional streaming RPCs, the server may send any number of 171 ``SERVER_STREAM`` packets. 172* The server sends a ``RESPONSE`` packet. Includes a payload for unary & client 173 streaming RPCs. The RPC is complete. 174 175The client may cancel an ongoing RPC at any time by sending a ``CLIENT_ERROR`` 176packet with status ``CANCELLED``. The server may finish an ongoing RPC at any 177time by sending the ``RESPONSE`` packet. 178 179Unary RPC 180--------- 181In a unary RPC, the client sends a single request and the server sends a single 182response. 183 184.. mermaid:: 185 :alt: Unary RPC 186 :align: center 187 188 sequenceDiagram 189 participant C as Client 190 participant S as Server 191 C->>+S: request 192 Note left of C: PacketType.REQUEST<br>channel ID<br>service ID<br>method ID<br>payload 193 194 S->>-C: response 195 Note right of S: PacketType.RESPONSE<br>channel ID<br>service ID<br>method ID<br>payload<br>status 196 197The client may attempt to cancel a unary RPC by sending a ``CLIENT_ERROR`` 198packet with status ``CANCELLED``. The server sends no response to a cancelled 199RPC. If the server processes the unary RPC synchronously (the handling thread 200sends the response), it may not be possible to cancel the RPC. 201 202.. mermaid:: 203 :alt: Cancelled Unary RPC 204 :align: center 205 206 sequenceDiagram 207 participant C as Client 208 participant S as Server 209 C->>+S: request 210 Note left of C: PacketType.REQUEST<br>channel ID<br>service ID<br>method ID<br>payload 211 212 C->>S: cancel 213 Note left of C: PacketType.CLIENT_ERROR<br>channel ID<br>service ID<br>method ID<br>status=CANCELLED 214 215 216Server streaming RPC 217-------------------- 218In a server streaming RPC, the client sends a single request and the server 219sends any number of ``SERVER_STREAM`` packets followed by a ``RESPONSE`` packet. 220 221.. mermaid:: 222 :alt: Server Streaming RPC 223 :align: center 224 225 sequenceDiagram 226 participant C as Client 227 participant S as Server 228 C->>+S: request 229 Note left of C: PacketType.REQUEST<br>channel ID<br>service ID<br>method ID<br>payload 230 231 S-->>C: messages (zero or more) 232 Note right of S: PacketType.SERVER_STREAM<br>channel ID<br>service ID<br>method ID<br>payload 233 234 S->>-C: done 235 Note right of S: PacketType.RESPONSE<br>channel ID<br>service ID<br>method ID<br>status 236 237 238The client may terminate a server streaming RPC by sending a ``CLIENT_STREAM`` 239packet with status ``CANCELLED``. The server sends no response. 240 241.. mermaid:: 242 :alt: Cancelled Server Streaming RPC 243 :align: center 244 245 sequenceDiagram 246 participant C as Client 247 participant S as Server 248 C->>S: request 249 Note left of C: PacketType.REQUEST<br>channel ID<br>service ID<br>method ID<br>payload 250 251 S-->>C: messages (zero or more) 252 Note right of S: PacketType.SERVER_STREAM<br>channel ID<br>service ID<br>method ID<br>payload 253 254 C->>S: cancel 255 Note left of C: PacketType.CLIENT_ERROR<br>channel ID<br>service ID<br>method ID<br>status=CANCELLED 256 257Client streaming RPC 258-------------------- 259In a client streaming RPC, the client starts the RPC by sending a ``REQUEST`` 260packet with no payload. It then sends any number of messages in 261``CLIENT_STREAM`` packets, followed by a ``CLIENT_REQUEST_COMPLETION``. The server sends 262a single ``RESPONSE`` to finish the RPC. 263 264.. mermaid:: 265 :alt: Client Streaming RPC 266 :align: center 267 268 sequenceDiagram 269 participant C as Client 270 participant S as Server 271 C->>S: start 272 Note left of C: PacketType.REQUEST<br>channel ID<br>service ID<br>method ID<br>payload 273 274 C-->>S: messages (zero or more) 275 Note left of C: PacketType.CLIENT_STREAM<br>channel ID<br>service ID<br>method ID<br>payload 276 277 C->>S: done 278 Note left of C: PacketType.CLIENT_REQUEST_COMPLETION<br>channel ID<br>service ID<br>method ID 279 280 S->>C: response 281 Note right of S: PacketType.RESPONSE<br>channel ID<br>service ID<br>method ID<br>payload<br>status 282 283The server may finish the RPC at any time by sending its ``RESPONSE`` packet, 284even if it has not yet received the ``CLIENT_REQUEST_COMPLETION`` packet. The client may 285terminate the RPC at any time by sending a ``CLIENT_ERROR`` packet with status 286``CANCELLED``. 287 288.. mermaid:: 289 :alt: Cancelled Client Streaming RPC 290 :align: center 291 292 sequenceDiagram 293 participant C as Client 294 participant S as Server 295 C->>S: start 296 Note left of C: PacketType.REQUEST<br>channel ID<br>service ID<br>method ID 297 298 C-->>S: messages (zero or more) 299 Note left of C: PacketType.CLIENT_STREAM<br>channel ID<br>service ID<br>method ID<br>payload 300 301 C->>S: cancel 302 Note right of S: PacketType.CLIENT_ERROR<br>channel ID<br>service ID<br>method ID<br>status=CANCELLED 303 304Bidirectional streaming RPC 305--------------------------- 306In a bidirectional streaming RPC, the client sends any number of requests and 307the server sends any number of responses. The client invokes the RPC by sending 308a ``REQUEST`` with no payload. It sends a ``CLIENT_REQUEST_COMPLETION`` packet when it 309has finished sending requests. The server sends a ``RESPONSE`` packet to finish 310the RPC. 311 312.. mermaid:: 313 :alt: Bidirectional Streaming RPC 314 :align: center 315 316 sequenceDiagram 317 participant C as Client 318 participant S as Server 319 C->>S: start 320 Note left of C: PacketType.REQUEST<br>channel ID<br>service ID<br>method ID<br>payload 321 322 C-->>S: messages (zero or more) 323 Note left of C: PacketType.CLIENT_STREAM<br>channel ID<br>service ID<br>method ID<br>payload 324 325 C-->S: (messages in any order) 326 327 S-->>C: messages (zero or more) 328 Note right of S: PacketType.SERVER_STREAM<br>channel ID<br>service ID<br>method ID<br>payload 329 330 C->>S: done 331 Note left of C: PacketType.CLIENT_REQUEST_COMPLETION<br>channel ID<br>service ID<br>method ID 332 333 S->>C: done 334 Note right of S: PacketType.RESPONSE<br>channel ID<br>service ID<br>method ID<br>status 335 336 337The server may finish the RPC at any time by sending the ``RESPONSE`` packet, 338even if it has not received the ``CLIENT_REQUEST_COMPLETION`` packet. The client may 339terminate the RPC at any time by sending a ``CLIENT_ERROR`` packet with status 340``CANCELLED``. 341 342.. mermaid:: 343 :alt: Client Streaming RPC 344 :align: center 345 346 sequenceDiagram 347 participant C as Client 348 participant S as Server 349 C->>S: start 350 Note left of C: PacketType.REQUEST<br>channel ID<br>service ID<br>method ID<br>payload 351 352 C-->>S: messages (zero or more) 353 Note left of C: PacketType.CLIENT_STREAM<br>channel ID<br>service ID<br>method ID<br>payload 354 355 C->>S: done 356 Note left of C: PacketType.CLIENT_REQUEST_COMPLETION<br>channel ID<br>service ID<br>method ID 357 358 S->>C: response 359 Note right of S: PacketType.RESPONSE<br>channel ID<br>service ID<br>method ID<br>payload<br>status 360