Esc

client_upgrade

procedureextensionexperimentalsince 0.36.1Source
  • macOS: client_upgrade works on macOS
  • Linux: client_upgrade works on Linux
  • Windows: client_upgrade works on Windows
  • Wasm: client_upgrade works on Wasm

Performs an HTTP/1.1 upgrade without redirects or replay, on the current Io fiber. On success the caller owns link and allocated pending bytes, and must close the reply too. A rejected switch returns its response and a .STATUS error; no connection is handed out.

Signature

client_upgrade :: (
    client: *Client,
    url_text: string,
    headers: [] Header_Field
) -> (Client_Response, Link, [] u8, Client_Error)
Example
Io :: #import "Extensions/Io";

handoff :: (link: Link, pending: [] u8, data: *void) {
    Io.write(link.writer, "ready"); // the server's side of the switched connection
}

route :: () -> Response {
    return upgrade_response("example", handoff);
}

main :: () {
    Io.io_run(() {
        app: App;
        defer free_app(*app);

        get(*app, "/", route);
        api := test_client(*app);

        headers := Header_Field.[.{ name = "Connection", value = "Upgrade" }, .{ name = "Upgrade", value = "example" }];
        reply, link, pending, error := client_upgrade(api, "http://localhost/", headers);
        assert(error.kind == .NONE && reply.status == 101);

        defer close(*reply);
        defer close(link);
        defer free(pending.data);

        // Bytes the server sent right behind its head come in `pending`; the rest is read from the link.
        builder: String_Builder;
        append(*builder, cast(string) pending);

        buffer: [16] u8;
        total := pending.count;

        while total < 5 {
            count, read_error := Io.read(link.reader, buffer);
            assert(read_error == .NONE && count > 0);

            append(*builder, string.{ count, buffer.data });
            total += count;
        }

        text := builder_to_string(*builder);
        defer free(text);

        assert(text == "ready");
    });
}

See also