# gizlang:grpc

gRPC (https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md) over HTTP/2. A message is bytes (the caller encodes it with gizlang:protobuf, or any codec). `service` makes the Http handler of the methods of a server; `dial` and `Channel.call` call a server. A call sends all its request messages and reads all its replies: unary, client-streaming and server-streaming calls fit, and the server may send its replies as it makes them. Messages are not compressed.

```gizlang
import * as Grpc from "gizlang:grpc";
```

## Types

### `Status`

```gizlang
type Status = { code: i64; message: string; }
```

How a call ended: a code (OK, or one above) and the server's message.

- `code`: `i64`
- `message`: `string`

### `Replies`

```gizlang
type Replies
```

The replies of a call in progress, sent as the method makes them.

Opaque: create and use it through this module's functions.

### `Handler`

```gizlang
type Handler = (request: Http.Request, messages: Vec<bytes>, replies: mut Replies) => Status
```

A method: it gets the request (its headers are the call's metadata) and the request messages, sends replies, and returns the status.

### `Method`

```gizlang
type Method = { path: string; run: Handler; }
```

The method at `path`, "/package.Service/Method".

- `path`: `string`
- `run`: `(request: gizlang_http.Request, messages: Vec<bytes>, replies: mut gizlang_grpc.Replies) => gizlang_grpc.Status`

### `Channel`

```gizlang
type Channel
```

A connection to a gRPC server.

Opaque: create and use it through this module's functions.

## Functions

### `frame`

```gizlang
function frame(message: bytes): bytes
```

A message with its 5-byte prefix: not compressed, and its length.

Effects: fail.

### `unframe`

```gizlang
function unframe(data: bytes): Vec<bytes> throws string
```

The messages of a body made of framed messages; an error for a cut or compressed one.

Effects: fail.

### `service`

```gizlang
function service(methods: Vec<Method>): (request: Http.Request) => Http.ReplyPlan
```

The handler of a gRPC server for Http.serve (over h2c or TLS with ALPN h2): a request for a path that is not a method gets
UNIMPLEMENTED, and one that is not a gRPC call gets 415. A method that returns does so with the status in the trailers.

### `use`

```gizlang
function use(stream: Stream, authority: string, secure: bool): Channel throws string
```

Calls over a stream that speaks HTTP/2 from its first byte (a TLS stream that chose h2, with `secure`).

Effects: fail, io.

### `dial`

```gizlang
function dial(sys: System, host: string, port: i64): Channel throws string
```

A channel to `host:port` over a plain TCP connection (h2c).

Effects: fail, io.

## Methods

### `Replies.send`

```gizlang
function Replies.send(self: mut Replies, message: bytes): bool throws Http.HttpError
```

Sends one reply message.

Effects: fail, read, write, console, io.

### `Channel.call`

```gizlang
function Channel.call(self: mut Channel, path: string, messages: Vec<bytes>, metadata: Vec<Http.Header>): Vec<bytes> throws Status
```

One call: the request messages go out, the replies and the server's status come back. `metadata` are extra request headers.
Err has the status when the call ended in an error.

Effects: fail, io.

### `Channel.close`

```gizlang
function Channel.close(self: mut Channel): void
```

Closes the channel.

Effects: fail, io.

## Constants

### `OK`

```gizlang
const OK = 0
```

The status codes of a call.

### `CANCELLED`

```gizlang
const CANCELLED = 1
```

The caller cancelled the call.

### `UNKNOWN`

```gizlang
const UNKNOWN = 2
```

An error that no other code describes.

### `INVALID_ARGUMENT`

```gizlang
const INVALID_ARGUMENT = 3
```

The client gave an argument that is not valid.

### `DEADLINE_EXCEEDED`

```gizlang
const DEADLINE_EXCEEDED = 4
```

The deadline ended before the call completed.

### `NOT_FOUND`

```gizlang
const NOT_FOUND = 5
```

The requested entity does not exist.

### `ALREADY_EXISTS`

```gizlang
const ALREADY_EXISTS = 6
```

The entity that the client tried to create exists.

### `PERMISSION_DENIED`

```gizlang
const PERMISSION_DENIED = 7
```

The caller may not do the operation.

### `RESOURCE_EXHAUSTED`

```gizlang
const RESOURCE_EXHAUSTED = 8
```

A resource or quota is used up.

### `FAILED_PRECONDITION`

```gizlang
const FAILED_PRECONDITION = 9
```

The system is not in the state that the operation needs.

### `ABORTED`

```gizlang
const ABORTED = 10
```

The operation stopped, often on a concurrency conflict.

### `OUT_OF_RANGE`

```gizlang
const OUT_OF_RANGE = 11
```

The operation went past the valid range.

### `UNIMPLEMENTED`

```gizlang
const UNIMPLEMENTED = 12
```

The server does not implement or support the operation.

### `INTERNAL`

```gizlang
const INTERNAL = 13
```

An internal error of the server.

### `UNAVAILABLE`

```gizlang
const UNAVAILABLE = 14
```

The service is not available now; a retry can succeed.

### `DATA_LOSS`

```gizlang
const DATA_LOSS = 15
```

Data was lost or corrupted and cannot be recovered.

### `UNAUTHENTICATED`

```gizlang
const UNAUTHENTICATED = 16
```

The call has no valid credentials.