HewStandard Library

Module std::net::tls

TLS client connections.

Provides encrypted TCP connections using TLS with system root certificates. Suitable for HTTPS clients, secure API calls, and any protocol that runs over TLS.

Examples

import std.net;
import std.net.tls;

fn main() {
    let stream = tls.connect("example.com", 443);
    let request = "GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n";
    match tls.write(stream, request.to_bytes()) {
        .Ok(_) => {}
        .Err(err) => panic(to_string(err)),
    }
    let _response = match tls.read(stream, 4096) {
        .Ok(data) => data,
        .Err(err) => panic(to_string(err)),
    };
    tls.close(stream);
}

Contents

Functions

Function connect

pub fn connect(host: string, port: i64) -> TlsStream

Open a TLS connection to a remote host.

Uses system root certificates to verify the server. Returns a TlsStream on success or a zero-value on failure.

Examples

import std.net.tls;

fn main() {
    let stream = tls.connect("example.com", 443);
}

Function last_error

pub fn last_error() -> string

Return the last TLS client error observed on this thread.

Failed connect() calls update this string. Successful connects clear it.

Function write

pub fn write(stream: TlsStream, data: bytes) -> Result<i64, net.NetError>

Write raw bytes to a TLS stream.

Returns the number of bytes written, or Err(net.NetError) on failure.

Function read

pub fn read(stream: TlsStream, size: i64) -> Result<bytes, net.NetError>

Read up to size bytes from a TLS stream.

Returns Ok(bytes) on success or orderly EOF, or Err(net.NetError) on retryable/TLS/I-O failures. Call last_error() for the precise detail.

Function close

pub fn close(stream: TlsStream)

Close a TLS connection and release resources.

Types

Struct TlsStream

An established TLS connection to a remote host.

Created by tls.connect(host, port). Must be released with close().

Traits

Trait TlsHandler

Trait for actors that handle TLS connections in active mode.

Implement this on an actor and call stream.attach(actor) to have the runtime read TLS bytes in a background thread and deliver each chunk as an on_data message. The actor never calls stream.read() — the runtime owns the read side after attach.

Example

import std.net.tls;

actor TlsEcho {
    let stream: tls.TlsStream;
    receive fn on_data(data: bytes) {
        match stream.write(data) {
            .Ok(_) => {}
            .Err(err) => panic(to_string(err)),
        }
    }
    receive fn on_close() {
        println("tls connection closed");
    }
}

Methods

fn on_data(data: bytes)

Called when a chunk of decrypted bytes arrives from the peer.

fn on_close()

Called when the connection closes or errors.

Trait TlsStreamMethods

Methods available on a TlsStream.

Methods

fn write(self: Self, data: bytes) -> Result<i64, net.NetError>

Write raw bytes to the TLS stream.

Returns the number of bytes written, or Err(net.NetError) on failure.

fn read(self: Self, size: i64) -> Result<bytes, net.NetError>

Read up to size bytes from the TLS stream.

Returns Ok(bytes) on success or orderly EOF, or Err(net.NetError) on retryable/TLS/I-O failures. Use last_error() for the precise class.

Do not call after attach() — the runtime owns the read side.

fn attach(self: Self, handler: TlsHandler)

Attach this TLS stream to an actor (Erlang-style active mode).

The runtime reads TLS bytes in a background thread and delivers each chunk as an on_data actor message. When the connection closes or errors, a single on_close message is sent. After attach, calling read() produces undefined behaviour — the runtime owns the read side. Outbound write() remains valid.

handler is the actor that will receive on_data and on_close. The compiler synthesises both protocol message IDs from the concrete actor type behind the handle.