conn - Cryo

import std::net::http::conn; · source

Types

Reading messages off a connection

implement struct BufStream<S> {
    async read_request(mut &this) -> Result<Request, IoError>
    where S: AsyncTransport;

    async read_response(mut &this) -> Result<Response, IoError>
    where S: AsyncTransport;
}

net::http::conn extends BufStream with the two message readers: request line or status line, headers until the blank line, then a body of exactly Content-Length bytes. Both cap what they will accept — header lines at MAX_HEADER_LINE, bodies at MAX_BODY — and fail with InvalidData past that.

They are methods on the connection rather than free functions for a reason that recurs across the async layers: a parser written as a static taking mut &BufStream<S> cannot be called from an async caller holding the connection as a local, because handing the address of a local to a future that outlives the current poll is refused (E0455). Only the receiver is re-supplied on every poll, so the reader has to be a method.

The server and client are written against these, and so can anything else that speaks HTTP/1.1 over a buffered transport — plaintext or TLS alike.

implement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }

Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.

language reference

implement struct Name { ... }

Names the struct an inherent block extends. The methods inside are interchangeable with ones declared in the struct body.

language reference

type struct BufStream<S> {
    inner: S;
    rbuf: Array<u8>;
    rpos: u64;
    scratch: Array<u8>;
    wbuf: Array<u8>;
}

std::io::buf

type parameter S

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.

language reference

async BufStream::read_request(mut &this) -> Result<Request, IoError>
where S: AsyncTransport

Read one complete request: request line, headers, and the body sized by Content-Length. A peer that closes mid-message is UnexpectedEof; one that sends a malformed line is InvalidData.

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.

language reference

&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.

language reference

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

Result: a value that may be an error.

std::core::result

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

HTTP request.

std::net::http::request

type struct IoError {
    kind: IoErrorKind;
    os_code: i32;
}

std::io::error

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.

language reference

type parameter S

declared in this snippet

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.

std::io::traits

async BufStream::read_response(mut &this) -> Result<Response, IoError>
where S: AsyncTransport

Read one complete response, framed the same way.

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

HTTP response.

std::net::http::response

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).

language reference