Standard Library: std.grpc
● Intermediate5 min
Every type, method and function of std.grpc: what the spec lists, then each declaration in its source, with its examples and the line that declares it.
Spec 14.14 · learn it in gRPC.
A declaration below shows what a program writes against: a type's fields, a function's parameters, what it gives, its contracts (require, ensure) and its examples. kavach test runs every example, so each one is true of the code.
What the spec lists
| Function | Gives |
|---|---|
grpc.call<Req, Res>(target, method, request) -> Res ! GrpcError | Calls method (/shop.Orders/Place) on the server at target with request, and decodes its answer into a Res |
grpc.call_stream<Req, Res>(target, method, requests) -> Res ! GrpcError | Client streaming: sends each of requests as its own message on one call, and decodes the one answer into a Res |
grpc.each<Req, Res>(target, method, request, on) ! GrpcError | Server streaming: runs on: fn(Res) for each message of the answer as it arrives |
grpc.each_stream<Req, Res>(target, method, requests, on) ! GrpcError | Two-way streaming: sends each of requests, then runs on for each message of the answer as it arrives |
grpc.serve(listener, handler) ! NetError | Serves gRPC on listener: each call is answered by handler: fn(GrpcCall) -> GrpcReply, each connection in a task of its own |
grpc.serve_talks(listener, handler, talks) ! NetError | Serves like serve, but holds a conversation on each method in talks: [String]: handler answers each of its messages as soon as it arrives |
grpc.talk_with<Req, Res>(target, method, first, on) ! GrpcError | A conversation: sends first, then runs on: fn(Res) -> [Req]? for each answer as it arrives, sending what it gives; none ends the client's side |
grpc.read<T>(call) -> T ! GrpcError | A call's message decoded into a T (the first, when the client sent several) |
grpc.read_all<T>(call) -> [T] ! GrpcError | Every message the client sent on the call, in order, each decoded into a T |
grpc.reply<T>(value) -> GrpcReply | An answer with value |
grpc.reply_stream<T>(values) -> GrpcReply | An answer that streams values, one message each |
grpc.failed(code, message) -> GrpcReply | An answer with a gRPC status other than OK (3 is INVALID_ARGUMENT, 5 NOT_FOUND, …) |
grpc.encode<T>(value) -> Bytes | value as a Protocol Buffers message |
grpc.decode<T>(data) -> T ! GrpcError | A Protocol Buffers message decoded into a T |
std.grpc.frames · frames.kav
use std.grpc.frames: 2 types and 7 functions. stdlib/grpc/frames.kav
GrpcError type
Why a gRPC call failed: Status is the server's answer.
pub type GrpcError = Network(error: NetError) |
Protocol(reason: String) |
BadMessage(reason: String) |
Status(code: Int, message: String)status_trailers function
The trailers that carry a call's gRPC status.
pub fn status_trailers(code: Int, message: String) -> [Header]check_status function
Fails with the server's status unless it is OK.
pub fn check_status(trailers: [String: String]) ! GrpcErrorSplit type
Whole messages at the start of pending, and the bytes after them.
pub type Split {
pub messages: [Bytes]
pub rest: Bytes
}split_messages function
pub fn split_messages(pending: Bytes) -> Split ! GrpcErrorframed function
A message behind gRPC's prefix: not compressed (0), then its length in four bytes, most significant first.
pub fn framed(data: Bytes) -> Bytesunframed_all function
Every message in body, without their prefixes.
pub fn unframed_all(body: Bytes) -> [Bytes] ! GrpcErrorunframed function
The first message in body, without its prefix.
pub fn unframed(body: Bytes) -> Bytes ! GrpcErrorstd.grpc · grpc.kav
use std.grpc: 2 types and 14 functions. stdlib/grpc/grpc.kav
GrpcCall type
A call as a server's handler gets it: the method's path and the messages the client sent, still encoded (read and read_all decode them). message is the first; a client that streams sends several.
pub type GrpcCall {
pub method: String
pub message: Bytes
pub messages: [Bytes]
}GrpcReply type
A server's answer: a message, a stream of messages, or a gRPC status other than OK.
pub type GrpcReply = Message(data: Bytes) | Stream(messages: [Bytes]) | Failed(code: Int, message: String)encode function
value as a Protocol Buffers message.
pub fn encode<T>(value: T) -> Bytesdecode function
A Protocol Buffers message decoded into a T.
pub fn decode<T>(data: Bytes) -> T ! GrpcErrorread function
A call's message decoded into a T.
pub fn read<T>(call: GrpcCall) -> T ! GrpcErrorread_all function
Every message the client sent on call, in order, each decoded into a T.
pub fn read_all<T>(call: GrpcCall) -> [T] ! GrpcErrorreply_stream function
An answer that streams values, one message each (spec 14.14).
pub fn reply_stream<T>(values: [T]) -> GrpcReplyfailed function
An answer with gRPC status code (not 0) and message.
pub fn failed(code: Int, message: String) -> GrpcReplycall function
Calls method (/shop.Orders/Place) on the server at target (http://host:port, or https:// for TLS) with request.
pub fn call<Req, Res>(target: String, method: String, request: Req) -> Res ! GrpcError uses Netcall_stream function
Client streaming: calls method with each of requests as its own message on one stream, and decodes the one answer.
pub fn call_stream<Req, Res>(target: String, method: String, requests: [Req]) -> Res ! GrpcError uses Neteach function
Calls streaming method on the server at target with request, running on for each message as it arrives; returns when the server finishes with status OK, and fails with Status otherwise.
pub fn each<Req, Res>(target: String, method: String, request: Req, on: fn(Res)) ! GrpcError uses Neteach_stream function
Two-way streaming: sends each of requests on one stream, ends the client's side, then runs on for each answer as it arrives, like each.
pub fn each_stream<Req, Res>(target: String, method: String, requests: [Req], on: fn(Res)) ! GrpcError uses Nettalk_with function
A two-way conversation: sends first, then runs on for each answer as it arrives; on gives the messages to send next, or none to end the client's side. Returns when the server finishes with status OK.
pub fn talk_with<Req, Res>(target: String, method: String, first: [Req], on: fn(Res) -> [Req]?) ! GrpcError uses Netserve function
Serves gRPC on listener: each connection in a task of its own, each call answered by handler.
pub fn serve(listener: Listener, handler: fn(GrpcCall) -> GrpcReply) ! NetError uses Netserve_talks function
Serves gRPC like serve, but holds a conversation on each method in talks: handler answers each of its messages as soon as it arrives, and the answer goes back at once (spec 14.14).
pub fn serve_talks(listener: Listener, handler: fn(GrpcCall) -> GrpcReply, talks: [String]) ! NetError uses Netstd.grpc.protobuf · protobuf.kav
use std.grpc.protobuf: 1 type and 3 functions. stdlib/grpc/protobuf.kav
ProtoError type
Why a message can't be read, or a value can't be sent.
pub type ProtoError = Malformed(reason: String) | Unsupported(reason: String)encode function
value (as json.of gives it) as a message with schema's fields.
pub fn encode(value: Json, schema: Json) -> Bytes ! ProtoErrordecode function
A message data as a Json object with schema's fields: a field that isn't there is null, or its type's zero value.
pub fn decode(data: Bytes, schema: Json) -> Json ! ProtoErrorvarint function
n as a varint; a negative n takes ten bytes, as int64 does.
pub fn varint(n: Int) -> Bytes
example varint(1) == Bytes([UInt8(1)])
example varint(150) == Bytes([UInt8(150), UInt8(1)])
example varint(-1).len() == 10