server

type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }

Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.

type struct Name {
    field: Type;
    method(&this) -> Ret { ... }
}

A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.

type struct Http2Server {
    listener: TcpListener;
}

A single-connection-at-a-time h2c (cleartext) server.

static name(param: Type) -> Ret { ... }

A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.

static Http2Server::bind(addr: SocketAddr) -> Result<Http2Server, IoError>

Bind + listen on addr for h2c connections. The listener is put in non-blocking mode here: TcpAccept parks on readiness, and a blocking listener would stall an executor's whole worker thread inside accept.

type struct SocketAddr {
    ip: IpAddr;
    port: u16;
}

SocketAddr: (IP, port).

type enum Result<T, E> {
    Ok(T);
    Err(E);
}

Result: a value that may be an error.

type struct Http2Server {
    listener: TcpListener;
}

A single-connection-at-a-time h2c (cleartext) server.

Http2Server::local_addr(&this) -> Result<SocketAddr, IoError>

The local address the listener is bound to. After bind(.., 0) this reports the kernel-assigned ephemeral port.

&this
mut &this
this

The receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.

async function name(param: Type) -> T { ... }

Compiles the function into a stackless state machine. Calling it builds a future whose output is the declared return type; nothing runs until that future is polled. Allowed on free functions, methods, and trait methods.

async Http2Server::serve_one(mut &this, handler: (Request) -> Response) -> Result<(), IoError>

Accept one connection and serve it to completion, then return.

mut &this
mut &Type

An exclusive, mutating borrow. As a receiver, mut &this lets the method modify the fields - and callers can see that from the signature alone. As a parameter type, mut &T lets the callee mutate through the reference while the caller keeps ownership.

type struct Request {
    method: Method;
    path: String;
    version: String;
    headers: Headers;
    body: Array<u8>;
    params: HashMap<String, String>;
}

HTTP request.

type struct Response {
    status: StatusCode;
    version: String;
    headers: Headers;
    body: Array<u8>;
}

HTTP response.

primitive ()

The unit type: a value that carries no information, and the empty tuple. Distinct from void, which is the absence of a value - Result<(), E> succeeds with nothing to return. 0 bytes.

async Http2Server::run(mut &this, handler: (Request) -> Response) -> Result<(), IoError>

Accept and serve connections forever, one at a time. A failure on a single connection is swallowed so one client can't stop the server; only an accept failure ends the loop.

async Http2Server::accept_one(mut &this) -> Result<TcpStream, IoError>

Take the listener out of this, accept one connection on it, and put it back. The swap is what lets the accept own the listener for the duration without this server holding a second address for it across the suspension.

import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;

Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).

namespace std;

std: the Cryo standard library.

namespace std::net;

net: network primitives + HTTP.

namespace std::net::http2;

net::http2: HTTP/2 (RFC 7540) with HPACK header compression (RFC 7541).

namespace std::net::http2::server;

HTTP/2 server.

static Http2Server::bind(addr: SocketAddr) -> Result<Http2Server, IoError>

Bind + listen on addr for h2c connections. The listener is put in non-blocking mode here: TcpAccept parks on readiness, and a blocking listener would stall an executor's whole worker thread inside accept.

async Http2Server::serve_one(mut &this, handler: (Request) -> Response) -> Result<(), IoError>

Accept one connection and serve it to completion, then return.

async Http2Server::run(mut &this, handler: (Request) -> Response) -> Result<(), IoError>

Accept and serve connections forever, one at a time. A failure on a single connection is swallowed so one client can't stop the server; only an accept failure ends the loop.

async function serve<S>(conn: BufStream<S>, handler: (Request) -> Response) -> Result<(), IoError>
where S: AsyncTransport

Serve HTTP/2 over conn, dispatching each request to handler until the peer closes or sends GOAWAY. Takes ownership of the connection.

Http2Server::drop(mut &this) -> void

via trait Drop

type struct TcpAccept {
    listener: TcpListener;
    rt: Reactor*;
}

Accept the next incoming connection. An accepted socket does not inherit the listener's non-blocking mode, so it is set here — it is about to be used with these same futures. Owns the listener for the duration and hands it back in the TcpAccepted, so a server loop starts the next accept from that.

Http2Server::local_addr(&this) -> Result<SocketAddr, IoError>

The local address the listener is bound to. After bind(.., 0) this reports the kernel-assigned ephemeral port.

start..end

A half-open range - start up to but excluding end - and sugar for Range::new(start, end): an iterator usable in for, and an ordinary value anywhere else. It binds looser than arithmetic, so a..b + 1 is a..(b + 1).

async Http2Server::accept_one(mut &this) -> Result<TcpStream, IoError>

Take the listener out of this, accept one connection on it, and put it back. The swap is what lets the accept own the listener for the duration without this server holding a second address for it across the suspension.

function name<T>(param: Type) -> Ret { ... }

Declares a function. Parameters are written name: Type and are never inferred; the return type follows -> and defaults to void. Declaration order does not matter: every signature is collected before any body is checked, so functions may call each other freely and recurse.

async function serve<S>(conn: BufStream<S>, handler: (Request) -> Response) -> Result<(), IoError>
where S: AsyncTransport

Serve HTTP/2 over conn, dispatching each request to handler until the peer closes or sends GOAWAY. Takes ownership of the connection.

type parameter S

where S: AsyncTransport

where T: Ord + Clone, U: Hash

Constrains generic parameters to types that implement the listed traits, which is what makes those traits' methods callable on T. Bounds on one parameter join with +; parameters separate with ,. A where on a single method narrows the type's parameter for that method only.

type trait AsyncTransport {
    async read_into(mut &this, buf: Array<u8>) -> Transfer;
    async write_from(mut &this, buf: Array<u8>) -> Transfer;
}

One raw, unbuffered async byte channel: what BufStream<S> needs of a transport, and nothing more.