Standard library · The web

web/tls

Imported as import "web/tls" as tls, its names are then tls.…. Every signature below is the one the checker infers.

Types

Conn

A connection: the OpenSSL object, its context, and the socket under it.

• Conn(ssl: Ptr, ctx: Ptr, fd: Int)

Server

• Server(ctx: Ptr, fd: Int)

Functions

fn connect(host: Str, port: Int) -> Result(Conn, Str)

A verified connection to host:port, the name resolved on the way.

# not run
c = tls.connect("example.com", 443)?
tls.connect("expired.badssl.com", 443)   # Err: the certificate is refused

fn connect_insecure(host: Str, port: Int) -> Result(Conn, Str)

The same without checking the certificate.

# not run
c = tls.connect_insecure("self-signed.local", 8443)?   # no check of the certificate

fn read(c: Conn) -> Str

What has arrived, up to 64 KB; "" when the peer has closed or the connection failed.

# not run
chunk = tls.read(c)   # up to 64 KB of what has arrived; "" once the peer is done

fn read_all(c: Conn) -> Str

Everything until the peer closes.

# not run
reply = tls.read_all(c)   # until the peer closes

fn write(c: Conn, s: Str) -> Int

Writes all of it; the bytes written, or -1.

# not run
tls.write(c, "GET / HTTP/1.1\r\nHost: h\r\n\r\n")   # the bytes written, or -1

fn disconnect(c: Conn) -> Unit

Ends the session and closes the socket.

# not run
tls.disconnect(c)

fn listen(port: Int, cert_path: Str, key_path: Str) -> Result(Server, Str)

A listening socket with a certificate chain and its key, both PEM files.

# not run
s = tls.listen(8443, "cert.pem", "key.pem")?

fn accept(s: Server) -> Result(Conn, Str)

The next connection, its handshake done. The context is the server's, so a Conn from here is ended with disconnect and the context stays.

# not run
c = tls.accept(s)?

fn stop(s: Server) -> Unit

# not run
tls.stop(s)

fn get(host: Str, port: Int, path: Str) -> Str

GET path over a fresh connection, closed after; the raw reply, with http's status_of and response_body to take it apart, or the error text.

# not run
import "web/http" as http
raw = tls.get("example.com", 443, "/")
http.status_of(raw)   # 200

fn ask(host: Str, port: Int, method: Str, path: Str, headers: List(Str), body: Str) -> Str

# not run
raw = tls.ask("api.example.com", 443, "POST", "/v1", Cons("Content-Type: application/json", Nil), "{}")

Tests

• test_a_self_signed_server_and_its_client
• test_refusals