https - Cryo

import std::net::https; · source

Types

`HttpsClient`

type struct HttpsClient {
    connector: TlsConnector;

    static new() -> Result<HttpsClient, IoError>;
    static insecure() -> Result<HttpsClient, IoError>;
    async get(&this, host: Str, port: u16, path: Str) -> Result<Response, IoError>;
    async post(&this, host: Str, port: u16, path: Str, content_type: Str, body: Array<u8>) -> Result<Response, IoError>;
    async send(&this, host: Str, port: u16, req: Request) -> Result<Response, IoError>;
}

One-shot HTTPS requests. net::https ties the pieces together: resolve the hostname through net::dns (on the blocking pool), dial with TcpConnect, wrap and verify with net::tls, and serialize and parse with net::http. The HTTP layer never learns it is talking to TLS.

import std::net::https;

mut client: HttpsClient = HttpsClient::new()?;
const resp: Response = await client.get(Str::new("example.com"), 443, Str::new("/"))?;

new() verifies certificates against the system store; insecure() does not, and is named accordingly. get and post build the request for you; send takes one you built yourself. The hostname goes into both the TLS SNI extension and the Host header. Each call opens a fresh connection and closes it afterwards — there is no pooling.

Requires ssl and crypto in link_libs, as any use of net::tls does.

Properties

Property	Type
`connector`	`TlsConnector`

Constructors

`static new() -> Result<HttpsClient, IoError>;`

New client with full certificate + hostname verification against the system trust store.

`static insecure() -> Result<HttpsClient, IoError>;`

New client that skips certificate verification. For self-signed or out-of-band-pinned servers only - never for the open web.

Methods

`async get(&this, host: Str, port: u16, path: Str) -> Result<Response, IoError>;`

GET https://host:port/path. Resolves host, dials, performs the TLS handshake with SNI = host, then sends the request and reads one response.

`async post(&this, host: Str, port: u16, path: Str, content_type: Str, body: Array<u8>) -> Result<Response, IoError>;`

POST https://host:port/path with a body. Sets Host and the given Content-Type; the request's Content-Length is set by set_body.

`async send(&this, host: Str, port: u16, req: Request) -> Result<Response, IoError>;`

Resolve, dial, wrap in TLS, and run one request/response.

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.

language reference

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.

language reference

type struct HttpsClient {
    connector: TlsConnector;
}

HttpsClient.connector: TlsConnector

type struct TlsConnector {
    ctx: void*;
    verify: boolean;
}

std::net::tls::context

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.

language reference

static HttpsClient::new() -> Result<HttpsClient, IoError>

New client with full certificate + hostname verification against the system trust store.

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

Result: a value that may be an error.

std::core::result

type struct HttpsClient {
    connector: TlsConnector;
}

std::net::https

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

std::io::error

static HttpsClient::insecure() -> Result<HttpsClient, IoError>

New client that skips certificate verification. For self-signed or out-of-band-pinned servers only - never for the open web.

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 HttpsClient::get(&this, host: Str, port: u16, path: Str) -> Result<Response, IoError>

GET https://host:port/path. Resolves host, dials, performs the TLS handshake with SNI = host, then sends the request and reads one response.

&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

(parameter) host: Str

type struct Str {
    bytes: u8*;
    length: u64;
}

Str: a borrowed UTF-8 string slice.

std::collections::str

(parameter) port: u16

primitive u16

16-bit unsigned integer.

primitive type

(parameter) path: Str

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

HTTP response.

std::net::http::response

async HttpsClient::post(&this, host: Str, port: u16, path: Str, content_type: Str, body: Array<u8>) -> Result<Response, IoError>

POST https://host:port/path with a body. Sets Host and the given Content-Type; the request's Content-Length is set by set_body.

(parameter) content_type: Str

(parameter) body: Array<u8>

type struct Array<T, A = GlobalAlloc> where A: Allocator {
    ptr: T*;
    length: i64;
    capacity: i64;
    alloc: A;
}

Array<T, A>: growable, heap-backed, contiguous sequence.

std::collections::array

primitive u8

8-bit unsigned integer.

primitive type

async HttpsClient::send(&this, host: Str, port: u16, req: Request) -> Result<Response, IoError>

Resolve, dial, wrap in TLS, and run one request/response.

(parameter) req: Request

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

HTTP request.

std::net::http::request

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

namespace std;

std: the Cryo standard library.

module page

namespace std::net;

net: network primitives + HTTP.

module page

namespace std::net::https;

HTTPS client: one-shot requests over TLS.

module page

mut name: Type = value;

A mutable binding, reassignable after declaration - mutability is opt-in, const is the default. At module level it declares mutable global state. Before & it marks an exclusive reference or receiver instead.

language reference

mut client: HttpsClient

static HttpsClient::new() -> Result<HttpsClient, IoError>

New client with full certificate + hostname verification against the system trust store.

std::net::https

value?

Error propagation. On a Result<T, E> it yields the T of an Ok and otherwise returns the Err(e) from the enclosing function unchanged; on an Option<T> it yields the T of a Some or returns None. The enclosing function must return a matching Result / Option.

language reference

const NAME: Type = value;

At module level, a true compile-time constant, conventionally SCREAMING_SNAKE_CASE. (mut at module level declares mutable global state instead.)

language reference

const resp: Response

await future

Suspends the enclosing async body until the operand - which must implement Future - completes, and evaluates to its output. A prefix operator allowed anywhere an expression is (conditions, arms, guards), but only inside async code.

language reference

mut client: HttpsClient

declared in this snippet

async HttpsClient::get(&this, host: Str, port: u16, path: Str) -> Result<Response, IoError>

GET https://host:port/path. Resolves host, dials, performs the TLS handshake with SNI = host, then sends the request and reads one response.

std::net::https

static Str::new(text: string) -> Str

Construct from a NUL-terminated C-style string literal. The caller certifies that text is valid UTF-8 and outlives this view. The NUL terminator is not included in the view.

std::collections::str

type struct TcpConnect {
    fd: i32;
    addr: [u8;
    28];
    addrlen: u32;
    err: IoError;
    rt: Reactor*;
}

Connect to a remote address without blocking. The socket is opened and the handshake started when the future is created; each poll asks the OS whether it finished, parking on writability in between. The socket is closed if the future is dropped before it completes.

std::net::socket::tcp

static HttpsClient::insecure() -> Result<HttpsClient, IoError>

New client that skips certificate verification. For self-signed or out-of-band-pinned servers only - never for the open web.

std::net::https

async HttpsClient::post(&this, host: Str, port: u16, path: Str, content_type: Str, body: Array<u8>) -> Result<Response, IoError>

POST https://host:port/path with a body. Sets Host and the given Content-Type; the request's Content-Length is set by set_body.

std::net::https

async HttpsClient::send(&this, host: Str, port: u16, req: Request) -> Result<Response, IoError>

Resolve, dial, wrap in TLS, and run one request/response.

std::net::https

namespace std::net::tls;

net::tls: TLS over TCP via system OpenSSL.

module page

HttpsClient.connector: TlsConnector

std::net::https

Types#

HttpsClient#

Properties#

Constructors#

static new() -> Result<HttpsClient, IoError>;#

static insecure() -> Result<HttpsClient, IoError>;#

Methods#

async get(&this, host: Str, port: u16, path: Str) -> Result<Response, IoError>;#

async post(&this, host: Str, port: u16, path: Str, content_type: Str, body: Array<u8>) -> Result<Response, IoError>;#

async send(&this, host: Str, port: u16, req: Request) -> Result<Response, IoError>;#

Types

`HttpsClient`

Properties

Constructors

`static new() -> Result<HttpsClient, IoError>;`

`static insecure() -> Result<HttpsClient, IoError>;`

Methods

`async get(&this, host: Str, port: u16, path: Str) -> Result<Response, IoError>;`

`async post(&this, host: Str, port: u16, path: Str, content_type: Str, body: Array<u8>) -> Result<Response, IoError>;`

`async send(&this, host: Str, port: u16, req: Request) -> Result<Response, IoError>;`