Xo is experimental. The source is now public on GitHub, or try Xo in your browser.
Menu · grpc

Docs

Tour

Book

Reference

std/grpc

On this page

Index

Types

Code

enum Code {
  Ok
  Canceled
  Unknown
  InvalidArgument
  DeadlineExceeded
  NotFound
  AlreadyExists
  PermissionDenied
  ResourceExhausted
  FailedPrecondition
  Aborted
  OutOfRange
  Unimplemented
  Internal
  Unavailable
  DataLoss
  Unauthenticated
} derive Display

The 17 canonical status codes (their numbers are the wire values of grpc-status).

Source: std/grpc.xo:8

Code.number

fn (c: Code) number() -> Int

The wire number of a code (OK is 0, UNAUTHENTICATED is 16).

Source: std/grpc.xo:29

FrameErr

enum FrameErr {
  Truncated
  BadFlag(flag: Int)
  TooLarge(len: Int)
} derive Display

Why a frame was refused.

Source: std/grpc.xo:34

Status

struct Status {
  code: Code
  message: Str = ""
  details: Bytes = b""
}

A call’s outcome that is not OK, the error of every call: the code, the status message and the raw grpc-status-details-bin payload when the peer sent one.

Source: std/grpc.xo:68

Status.display

fn (s: Status) display() -> Str

Displays as rpc error: code = NotFound desc = no such user (grpc-go’s text).

Source: std/grpc.xo:75

Call

struct Call {
  method: Str
  metadata: Map[Str, Str]
  timeout: Duration?
}

The call a handler is serving.

Source: std/grpc.xo:78

RecvState

struct RecvState {
  buf: Bytes = b""
  at: Int = 0
  done: Bool = false
  gzip: Bool = false
}

Source: std/grpc.xo:87

Recv

struct Recv {
  body: http.BodyReader
  st: Mutex[RecvState]
  max: Int
}

The messages of a call’s request stream, as a handler reads them.

Source: std/grpc.xo:96

Recv.next

fn (r: Recv) next() -> Bytes? ! Status

The next message; None when the client has finished sending. A message above the receive limit is ResourceExhausted, a cut stream or a bad frame Internal, a compressed message Unimplemented.

Source: std/grpc.xo:104

Send

struct Send {
  w: http.BodyWriter
  gzip: Bool = false
}

The messages a handler sends back.

Source: std/grpc.xo:107

Send.send

fn (s: Send) send(msg: Bytes) -> () ! Status

Sends one message (a frame is flushed at once).

Source: std/grpc.xo:114

Send.set_trailer

fn (s: Send) set_trailer(name: Str, value: Str)

A trailer sent after the last message, next to grpc-status and grpc-message.

Source: std/grpc.xo:116

Server

struct Server {
  routes: http.Router
  max_recv: Int
  methods: List[Str]
  clock: Clock
}

A gRPC server: methods registered on it are served through router() by an HTTP/2 http.Server.

Source: std/grpc.xo:119

Server.with_max_recv

fn (s: Server) with_max_recv(n: Int) -> Server

The server with another receive limit in bytes.

Source: std/grpc.xo:130

Server.unary

fn (var s: Server) unary[fx: Effects](method: Str, f: fn(Call, Bytes) -> Bytes ! Status uses fx) uses (fx, clock)

Registers a unary method (/package.Service/Method).

Source: std/grpc.xo:132

Server.stream

fn (var s: Server) stream[fx: Effects](method: Str, f: fn(Call, Recv, Send) -> () ! Status uses fx) uses (fx, clock)

Registers a method of any kind: a handler reads the request messages from Recv and writes the responses to Send; returning Ok ends the call with OK, an error with its status.

Source: std/grpc.xo:135

Server.router

fn (s: Server) router() -> http.Router

The routes to give http.server, with http.Protocol.UnencryptedHttp2 (or TLS and ALPN h2) in its protocols.

Source: std/grpc.xo:137

Client

struct Client {
  http: http.Client
  base: Str
  gzip: Bool = false
}

A gRPC client over an http.Client.

Source: std/grpc.xo:140

Client.with_gzip

fn (c: Client) with_gzip() -> Client

The client sending its messages gzip compressed (grpc-encoding: gzip); responses are read compressed or not.

Source: std/grpc.xo:150

Client.unary

fn (c: Client) unary(method: Str, req: Bytes, metadata: Map[Str, Str] = {}, timeout: Duration? = None) -> Bytes ! Status uses net.dial

One unary call: the request message, the response message, or the call’s status. timeout is sent as grpc-timeout and bounds the call (DeadlineExceeded).

Source: std/grpc.xo:153

Client.call

fn (c: Client) call[R, fx: Effects](method: Str, metadata: Map[Str, Str], timeout: Duration?, f: fn(ClientCall) -> R ! Status uses fx) -> R ! Status uses (fx, net.dial)

Runs f on a streaming call: f sends with send, ends the request with close_send and reads with recv. The call’s status is the result of recv after the last message (an error when it is not OK).

Source: std/grpc.xo:174

ClientCall

struct ClientCall {
  w: http.PipeWriter
  head: Chan[(http.ClientStream?, Status?)]
  st: Mutex[CallState]
  max: Int
  gzip: Bool = false
}

The client side of a streaming call, valid inside Client.call.

Source: std/grpc.xo:156

ClientCall.send

fn (c: ClientCall) send(msg: Bytes) -> () ! Status

Sends one message.

Source: std/grpc.xo:176

ClientCall.close_send

fn (c: ClientCall) close_send()

Ends the request stream.

Source: std/grpc.xo:178

ClientCall.recv

fn (c: ClientCall) recv() -> Bytes? ! Status uses net.dial

The next response message; None at the end of an OK call, the status as an error otherwise.

Source: std/grpc.xo:180

CallState

struct CallState {
  stream: http.ClientStream? = None
  failed: Status? = None
  recv: RecvState = RecvState{}
  final: Status? = None
}

Source: std/grpc.xo:165

Functions

code_from

fn code_from(n: Int) -> Code?

The code of a grpc-status number; None above 16.

Source: std/grpc.xo:31

frame

fn frame(payload: Bytes, compressed: Bool = false) -> Bytes

One message frame: a flag byte (1 for a compressed payload), a 4 byte big endian length, the payload.

Source: std/grpc.xo:41

unframe

fn unframe(data: Bytes, at: Int, max_len: Int = 4194304) -> (Bool, Bytes, Int) ! FrameErr

Reads the frame at at: (compressed, payload, next offset). A length above max_len is TooLarge (grpc-go’s default receive limit is 4 MiB).

Source: std/grpc.xo:44

encode_timeout

fn encode_timeout(ns: Int) -> Str

The grpc-timeout header value for a duration in nanoseconds: at most 8 digits and the largest unit that keeps it (n, u, m, S, M, H), as grpc-go’s encodeTimeout.

Source: std/grpc.xo:48

decode_timeout

fn decode_timeout(s: Str) -> Int?

The nanoseconds of a grpc-timeout value; None for a value that is not 1 to 8 digits and one unit letter.

Source: std/grpc.xo:50

encode_message

fn encode_message(s: Str) -> Str

grpc-message encoding: bytes outside 0x20 to 0x7e and % are written as %XX (upper case hex).

Source: std/grpc.xo:53

encode_message_bytes

fn encode_message_bytes(b: Bytes) -> Str

encode_message of arbitrary bytes (a status message from another language need not be UTF-8).

Source: std/grpc.xo:55

decode_message

fn decode_message(s: Str) -> Str

The inverse; a malformed escape is kept as written (grpc-go), and bytes that are not UTF-8 become U+FFFD.

Source: std/grpc.xo:57

decode_message_bytes

fn decode_message_bytes(s: Str) -> Bytes

The inverse as raw bytes, exactly what grpc-go’s client reports.

Source: std/grpc.xo:59

bin_encode

fn bin_encode(data: Bytes) -> Str

A binary metadata value as grpc-go sends it: unpadded standard base64, for a name that ends in -bin.

Source: std/grpc.xo:62

bin_decode

fn bin_decode(value: Str) -> Bytes?

The bytes of a -bin metadata value, padded or not (grpc-go accepts both); None when it is not base64.

Source: std/grpc.xo:64

server

fn server(clock: Clock) -> Server

A server with grpc-go’s 4 MiB receive limit. clock times the deadlines clients send: a handler still running at its grpc-timeout is cancelled and the call ends with DeadlineExceeded.

Source: std/grpc.xo:128

client

fn client(c: http.Client, base: Str) -> Client

A client of base (http://host:port, plain HTTP/2 with prior knowledge, or https://host:port).

Source: std/grpc.xo:148

↑ index