blackbull.grpc¶
blackbull.grpc
¶
gRPC server over HTTP/2.
Enable with app.enable_grpc(registry). Handlers exchange raw message bytes; protobuf is optional. Streaming contracts are in docs/guide/grpc.md.
GrpcContext
¶
Per-call metadata, peer, deadline and response status/metadata controls for raw-byte handlers.
invocation_metadata()
¶
Return the request fields as (name, value) pairs with lowercase
names and no pseudo-headers — grpcio's
ServicerContext.invocation_metadata.
metadata(name, default=b'')
¶
Return the first request field named name (any case), or default.
peer()
¶
Return the client address as grpcio formats it (ipv4:host:port /
ipv6:[host]:port), or '' when the transport did not supply one.
send_initial_metadata(metadata)
async
¶
Send response leading metadata now (the initial HTTP/2 HEADERS),
before the first response message — grpcio's
ServicerContext.send_initial_metadata.
Optional: if never called, the response HEADERS are still emitted lazily
(just before the first message, or with the trailers for an empty
response). Calling it flushes them early with metadata attached — used
to hand the client leading metadata (auth challenges, stream ids) up
front. Raises ValueError once the HEADERS have already gone
out (grpcio's "initial metadata no longer allowed").
time_remaining()
¶
Seconds left until the call deadline (never negative), or None
when the client set no grpc-timeout — grpcio's
ServicerContext.time_remaining. Lets a handler shed work it cannot
finish in time.
trailing_metadata()
¶
The trailing metadata set so far, as a copy — so a helper composes with what the handler already set instead of clobbering it.
GrpcDecodeError
¶
Bases: ValueError
Invalid message framing: compression flag, length, or incomplete input.
GrpcError
¶
Bases: Exception
Raised by a service handler (or context.abort) to end the RPC with
a non-OK status. serve_grpc translates it into grpc-status /
grpc-message trailers.
GrpcServiceRegistry
¶
Holds the path -> GrpcMethod table for gRPC methods.
add_method(path, handler, *, streaming=None, client_streaming=None)
¶
Register handler for the fully-qualified method path
(/package.Service/Method or package.Service/Method).
Both streaming axes default to None, meaning auto-detection —
see GrpcMethod for what each axis is. Pass a bool to
override it for a handler whose nature a wrapper hides. Forcing
streaming False on an async-generator function is a
contradiction and raises ValueError.
add_service(service, methods)
¶
Register every method_name -> handler in methods under the
fully-qualified service name (e.g. "helloworld.Greeter").
Each handler's streaming-ness is auto-detected individually.
lookup(path)
¶
Return the handler for path, or None if unregistered.
Backwards-compatible accessor (returns just the callable); use
lookup_method when the streaming flag is needed.
lookup_method(path)
¶
Return the GrpcMethod for path, or None if
unregistered.
method(path, *, streaming=None, client_streaming=None)
¶
Decorator form of add_method.
methods()
¶
Return all registered method paths, in registration order.
GrpcStatus
¶
Bases: IntEnum
The canonical gRPC status codes, as the grpc-status trailer carries
them.
OK (0) is success; every other member ends the RPC. Raise one through
GrpcError — that is the typed contract
a handler is checked against, so a bare integer is a caller error rather
than an unnamed code.
decode_messages(data)
¶
Parse data into a list of (compressed, payload) messages.
A single DATA buffer may contain zero, one, or many framed messages
(gRPC permits multiple messages per stream and does not align them to
DATA-frame boundaries). Raises GrpcDecodeError on a truncated
prefix, an invalid compression flag, or a short message body.
encode_message(payload, *, compressed=False)
¶
Frame payload as a single gRPC Length-Prefixed-Message.
serve_grpc(registry, conn, receive, send)
async
¶
Serve any of the four gRPC call shapes for conn.
Report handler and protocol failures as gRPC status.