120 lines
2.7 KiB
ReStructuredText
120 lines
2.7 KiB
ReStructuredText
Metadata
|
|
========
|
|
|
|
Structure of the gRPC call looks like this:
|
|
|
|
.. code-block:: text
|
|
|
|
> :path /package/Method/
|
|
> ...
|
|
> ... request metadata
|
|
|
|
> data (request)
|
|
|
|
< :status 200
|
|
< ...
|
|
< ... initial metadata
|
|
|
|
< data (reply)
|
|
|
|
< grpc-status 0
|
|
< ...
|
|
< ... trailing metadata
|
|
|
|
The same as regular HTTP request but with trailers. So client can send request
|
|
metadata and server can return initial and trailing metadata.
|
|
|
|
Metadata sent as regular HTTP headers. It may contain printable ascii text
|
|
with spaces:
|
|
|
|
.. code-block:: text
|
|
|
|
auth-token: 0d16ad85-6ce4-4773-a1be-9f62b2e886a3
|
|
|
|
Or it may contain binary data:
|
|
|
|
.. code-block:: text
|
|
|
|
auth-token-bin: DRathWzkR3Ohvp9isuiGow
|
|
|
|
Binary metadata keys should contain ``-bin`` suffix and values should be encoded
|
|
using base64 encoding without padding.
|
|
|
|
Keys with ``grpc-`` prefix are reserved for gRPC protocol. You can read more
|
|
additional details here: `gRPC Wire Format`_.
|
|
|
|
``grpclib`` encodes and decodes binary metadata automatically. In Python you
|
|
will receive text metadata as ``str`` type:
|
|
|
|
.. code-block:: python3
|
|
|
|
{"auth-token": "0d16ad85-6ce4-4773-a1be-9f62b2e886a3"}
|
|
|
|
Binary metadata you will receive as ``bytes`` type:
|
|
|
|
.. code-block:: python3
|
|
|
|
{"auth-token-bin": b"\r\x16\xad\x85l\xe4Gs\xa1\xbe\x9fb\xb2\xe8\x86\xa3"}
|
|
|
|
Client-Side
|
|
~~~~~~~~~~~
|
|
|
|
Sending metadata:
|
|
|
|
.. code-block:: python3
|
|
|
|
reply = await stub.Method(Request(), metadata={'auth-token': auth_token})
|
|
|
|
Sending and receiving metadata:
|
|
|
|
.. code-block:: python3
|
|
|
|
async with stub.Method.open(metadata={'auth-token': auth_token}) as stream:
|
|
await stream.recv_initial_metadata()
|
|
print(stream.initial_metadata)
|
|
|
|
await stream.send_message(Request())
|
|
reply = await stream.recv_message()
|
|
|
|
await stream.recv_trailing_metadata()
|
|
print(stream.trailing_metadata)
|
|
|
|
See reference docs for more details: :doc:`client`.
|
|
|
|
Server-Side
|
|
~~~~~~~~~~~
|
|
|
|
Receiving and sending metadata:
|
|
|
|
.. code-block:: python3
|
|
|
|
class Service(ServiceBase):
|
|
|
|
async def Method(self, stream):
|
|
print(stream.metadata) # request metadata
|
|
|
|
await stream.send_initial_metadata(metadata={
|
|
'begin-time': current_time(),
|
|
})
|
|
|
|
request = await stream.recv_message()
|
|
...
|
|
await stream.send_message(Reply())
|
|
|
|
await stream.send_trailing_metadata(metadata={
|
|
'end-time': current_time(),
|
|
})
|
|
|
|
See reference docs for more details: :doc:`server`.
|
|
|
|
Reference
|
|
~~~~~~~~~
|
|
|
|
.. automodule:: grpclib.metadata
|
|
:members: Deadline
|
|
|
|
.. automodule:: grpclib.protocol
|
|
:members: Peer
|
|
|
|
.. _gRPC Wire Format: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
|