tiny.http.Client

1pub const Client = struct {2    allocator: Allocator,3    ca_bundle: tls.Bundle = .empty,4    ca_bundle_lock: tls.BundleLock = .init,5    certs_loaded: bool = false,6    timeout_ms: u32 = default_timeout_ms,7    keep_alive: bool = false,8    tcp_no_delay: bool = false,9    persistent: ?PersistentConnection = null,10    persistent_host: [client_operation.default_host_bytes]u8 =11        undefined,12    persistent_host_len: u16 = 0,13    persistent_port: u16 = 0,1415    /// Builds a client that holds `allocator` to back its certificate authority16    /// bundle and retain an open connection for subsequent requests. Building a17    /// client touches the network in no way. The certificate authority bundle18    /// is loaded from the local operating system store on the first TLS request19    /// that requires it rather than during initialization. Calling `deinit`20    /// closes any retained connection and frees the bundle.21    pub fn init(allocator: Allocator) Client {22        return .{ .allocator = allocator };23    }2425    pub fn deinit(self: *Client) void {26        self.dropPersistent(true);27        if (self.certs_loaded) self.ca_bundle.deinit(self.allocator);28    }2930    fn ensureCerts(self: *Client) !void {31        if (!self.certs_loaded) {32            tls.loadSystemBundle(&self.ca_bundle, self.allocator) catch return error.TlsFailed;33            self.certs_loaded = true;34        }35    }3637    pub fn post(38        self: *Client,39        operation_scratch: OperationScratch,40        response_scratch: ResponseScratch,41        url: []const u8,42        headers: []const Header,43        body: []const u8,44    ) ClientError!ClientResponse {45        return self.request(operation_scratch, response_scratch, "POST", url, headers, body);46    }4748    pub fn postStream(49        self: *Client,50        operation_scratch: OperationScratch,51        stream_scratch: StreamScratch,52        url: []const u8,53        headers: []const Header,54        body: []const u8,55        handler: StreamHandler,56    ) anyerror!u16 {57        return self.requestStream(58            operation_scratch,59            stream_scratch,60            "POST",61            url,62            headers,63            body,64            handler,65        );66    }6768    pub fn get(69        self: *Client,70        operation_scratch: OperationScratch,71        response_scratch: ResponseScratch,72        url: []const u8,73        headers: []const Header,74    ) ClientError!ClientResponse {75        return self.request(operation_scratch, response_scratch, "GET", url, headers, "");76    }7778    pub fn getStream(79        self: *Client,80        operation_scratch: OperationScratch,81        stream_scratch: StreamScratch,82        url: []const u8,83        headers: []const Header,84        handler: StreamHandler,85    ) anyerror!u16 {86        return self.requestStream(87            operation_scratch,88            stream_scratch,89            "GET",90            url,91            headers,92            "",93            handler,94        );95    }9697    /// Sends one request and returns the response read from the server.98    /// Returned headers and body slices point directly into `response_scratch`.99    /// This backing storage must remain alive and unchanged while the response100    /// is in use, with subsequent parses into that storage serving as one point101    /// of invalidation.102    ///103    /// Parsing the URL into target fields and checking the read and write104    /// buffers for a plain request occur before opening any socket, so failures105    /// during these preparation checks leave the network untouched.106    ///107    /// A request over TLS loads the local operating system certificate108    /// authority bundle on the first call requiring it. When keep-alive is109    /// enabled, the request reuses an existing connection already open to that110    /// host and port.111    pub fn request(112        self: *Client,113        operation_scratch: OperationScratch,114        response_scratch: ResponseScratch,115        method: []const u8,116        url: []const u8,117        headers: []const Header,118        body: []const u8,119    ) ClientError!ClientResponse {120        try rejectTunnelMethod(method);121        const prepared = try ClientOperation.prepare(operation_scratch, url);122        if (!prepared.is_tls) try ClientOperation.validatePlain(operation_scratch);123        const alloc = self.allocator;124        if (prepared.is_tls) try self.ensureCerts();125126        if (self.keep_alive) {127            return self.reusableRequest(128                response_scratch,129                prepared,130                method,131                headers,132                body,133            );134        }135        self.dropPersistent(true);136        const stream = connectToHost(137            prepared.host,138            prepared.port,139            self.timeout_ms,140            self.tcp_no_delay,141        ) catch return error.ConnectionFailed;142        if (prepared.is_tls) {143            return self.doTlsRequest(144                alloc,145                response_scratch,146                stream,147                prepared.host,148                prepared.target,149                method,150                headers,151                body,152            );153        } else {154            return doPlainRequest(155                operation_scratch,156                response_scratch,157                stream,158                prepared.host,159                prepared.target,160                method,161                headers,162                body,163            );164        }165    }166167    pub fn openWebSocket(168        self: *Client,169        operation_scratch: OperationScratch,170        websocket_scratch: WebSocketScratch,171        url: []const u8,172    ) anyerror!ClientWebSocket {173        const prepared = try ClientOperation.prepare(174            operation_scratch,175            url,176        );177        if (!prepared.is_tls) {178            try ClientOperation.validatePlain(179                operation_scratch,180            );181        }182        if (prepared.is_tls) try self.ensureCerts();183        const socket = connectToHost(184            prepared.host,185            prepared.port,186            self.timeout_ms,187            self.tcp_no_delay,188        ) catch return error.ConnectionFailed;189        const connection: PersistentConnection =190            if (prepared.is_tls)191                .{ .tls = try self.createTlsPersistent(192                    socket,193                    prepared.host,194                ) }195            else196                .{ .plain = try PlainConn.create(197                    self.allocator,198                    socket,199                ) };200        var owned = true;201        errdefer if (owned) {202            destroyConnection(203                self.allocator,204                connection,205                false,206            );207        };208        try clientWebSocketHandshake(209            connection,210            prepared,211        );212        const result = try ClientWebSocket.init(213            self.allocator,214            connection,215            websocket_scratch,216        );217        owned = false;218        return result;219    }220221    pub fn requestStream(222        self: *Client,223        operation_scratch: OperationScratch,224        stream_scratch: StreamScratch,225        method: []const u8,226        url: []const u8,227        headers: []const Header,228        body: []const u8,229        handler: StreamHandler,230    ) anyerror!u16 {231        try rejectTunnelMethod(method);232        const prepared = try ClientOperation.prepare(operation_scratch, url);233        if (!prepared.is_tls) try ClientOperation.validatePlain(operation_scratch);234        const alloc = self.allocator;235        if (prepared.is_tls) try self.ensureCerts();236237        const stream = connectToHost(238            prepared.host,239            prepared.port,240            self.timeout_ms,241            self.tcp_no_delay,242        ) catch return error.ConnectionFailed;243244        if (prepared.is_tls) {245            return self.doTlsRequestStream(246                alloc,247                stream_scratch,248                stream,249                prepared.host,250                prepared.target,251                method,252                headers,253                body,254                handler,255            );256        } else {257            return doPlainRequestStream(258                operation_scratch,259                stream_scratch,260                stream,261                prepared.host,262                prepared.target,263                method,264                headers,265                body,266                handler,267            );268        }269    }270271    fn reusableRequest(272        self: *Client,273        response_scratch: ResponseScratch,274        prepared: PreparedOperation,275        method: []const u8,276        headers: []const Header,277        body: []const u8,278    ) ClientError!ClientResponse {279        try self.ensurePersistent(prepared);280        const response = self.performReusableRequest(281            response_scratch,282            prepared.host,283            prepared.target,284            method,285            headers,286            body,287        ) catch |err| {288            self.dropPersistent(false);289            return err;290        };291        if (!response.connection_reusable) {292            self.dropPersistent(true);293        }294        return response;295    }296297    fn ensurePersistent(298        self: *Client,299        prepared: PreparedOperation,300    ) ClientError!void {301        if (self.persistentMatches(prepared)) return;302        self.dropPersistent(true);303        if (prepared.host.len > self.persistent_host.len) {304            return error.ClientHostCapacityExceeded;305        }306        const socket = connectToHost(307            prepared.host,308            prepared.port,309            self.timeout_ms,310            self.tcp_no_delay,311        ) catch return error.ConnectionFailed;312        const connection: PersistentConnection =313            if (prepared.is_tls)314                .{ .tls = try self.createTlsPersistent(315                    socket,316                    prepared.host,317                ) }318            else319                .{ .plain = try PlainConn.create(320                    self.allocator,321                    socket,322                ) };323        self.persistent = connection;324        @memcpy(325            self.persistent_host[0..prepared.host.len],326            prepared.host,327        );328        self.persistent_host_len =329            @intCast(prepared.host.len);330        self.persistent_port = prepared.port;331    }332333    fn createTlsPersistent(334        self: *Client,335        socket: sys.Socket,336        host: []const u8,337    ) ClientError!*TlsConn {338        const conn = self.allocator.create(TlsConn) catch {339            sys.close(socket);340            return error.OutOfMemory;341        };342        errdefer self.allocator.destroy(conn);343        conn.initAt(socket);344        errdefer conn.deinit(false);345        try self.initializeTls(conn, host);346        return conn;347    }348349    fn initializeTls(350        self: *Client,351        conn: *TlsConn,352        host: []const u8,353    ) ClientError!void {354        var entropy: [tls.Client.Options.entropy_len]u8 =355            undefined;356        tls.fillEntropy(&entropy) catch357            return error.TlsFailed;358        const now = tls.realtimeNow();359        conn.tls_client = tls.Client.init(360            &conn.socket_reader.reader,361            &conn.socket_writer.writer,362            .{363                .host = .{ .explicit = host },364                .ca = tls.bundleAuthority(365                    self.allocator,366                    &self.ca_bundle_lock,367                    &self.ca_bundle,368                ),369                .read_buffer = &conn.tls_read_buf,370                .write_buffer = &conn.tls_write_buf,371                .entropy = &entropy,372                .realtime_now = now,373                .allow_truncation_attacks = true,374            },375        ) catch return error.TlsFailed;376    }377378    fn performReusableRequest(379        self: *Client,380        response_scratch: ResponseScratch,381        host: []const u8,382        target: []const u8,383        method: []const u8,384        headers: []const Header,385        body: []const u8,386    ) ClientError!ClientResponse {387        const persistent = self.persistent orelse388            return error.ConnectionFailed;389        return switch (persistent) {390            .plain => |conn| blk: {391                ClientOperation.writeReusableRequest(392                    &conn.socket_writer.writer,393                    method,394                    host,395                    target,396                    headers,397                    body,398                ) catch return error.WriteFailed;399                conn.socket_writer.writer.flush() catch400                    return error.WriteFailed;401                break :blk try client_response.read(402                    response_scratch,403                    &conn.socket_reader.reader,404                    method,405                );406            },407            .tls => |conn| blk: {408                ClientOperation.writeReusableRequest(409                    &conn.tls_client.?.writer,410                    method,411                    host,412                    target,413                    headers,414                    body,415                ) catch return error.WriteFailed;416                conn.tls_client.?.writer.flush() catch417                    return error.WriteFailed;418                conn.socket_writer.writer.flush() catch419                    return error.WriteFailed;420                break :blk try client_response.read(421                    response_scratch,422                    &conn.tls_client.?.reader,423                    method,424                );425            },426        };427    }428429    fn persistentMatches(430        self: *const Client,431        prepared: PreparedOperation,432    ) bool {433        const persistent = self.persistent orelse434            return false;435        const is_tls = switch (persistent) {436            .plain => false,437            .tls => true,438        };439        return is_tls == prepared.is_tls and440            self.persistent_port == prepared.port and441            std.mem.eql(442                u8,443                self.persistent_host[0..self.persistent_host_len],444                prepared.host,445            );446    }447448    fn dropPersistent(449        self: *Client,450        notify: bool,451    ) void {452        if (self.persistent) |persistent| {453            switch (persistent) {454                .plain => |conn| conn.destroy(455                    self.allocator,456                ),457                .tls => |conn| {458                    conn.deinit(notify);459                    self.allocator.destroy(conn);460                },461            }462            self.persistent = null;463        }464        self.persistent_host_len = 0;465        self.persistent_port = 0;466    }467468    fn rejectTunnelMethod(method: []const u8) error{TunnelUnsupported}!void {469        if (isTunnelMethod(method)) return error.TunnelUnsupported;470    }471472    fn isTunnelMethod(method: []const u8) bool {473        return std.mem.eql(u8, method, "CONNECT");474    }475476    fn doTlsRequest(477        self: *Client,478        alloc: Allocator,479        response_scratch: ResponseScratch,480        socket: sys.Socket,481        host: []const u8,482        path: []const u8,483        method: []const u8,484        headers: []const Header,485        body: []const u8,486    ) ClientError!ClientResponse {487        std.debug.assert(!isTunnelMethod(method));488        const conn = alloc.create(TlsConn) catch return error.OutOfMemory;489        var send_close_notify = false;490        defer {491            conn.deinit(send_close_notify);492            alloc.destroy(conn);493        }494495        conn.initAt(socket);496497        try self.initializeTls(conn, host);498499        ClientOperation.writeRequest(500            &conn.tls_client.?.writer,501            method,502            host,503            path,504            headers,505            body,506        ) catch return error.WriteFailed;507        conn.tls_client.?.writer.flush() catch return error.WriteFailed;508        conn.socket_writer.writer.flush() catch return error.WriteFailed;509510        const parsed = try client_response.read(511            response_scratch,512            &conn.tls_client.?.reader,513            method,514        );515        send_close_notify = true;516        return parsed;517    }518519    fn doTlsRequestStream(520        self: *Client,521        alloc: Allocator,522        stream_scratch: StreamScratch,523        socket: sys.Socket,524        host: []const u8,525        path: []const u8,526        method: []const u8,527        headers: []const Header,528        body: []const u8,529        handler: StreamHandler,530    ) anyerror!u16 {531        std.debug.assert(!isTunnelMethod(method));532        const conn = alloc.create(TlsConn) catch return error.OutOfMemory;533        var send_close_notify = false;534        defer {535            conn.deinit(send_close_notify);536            alloc.destroy(conn);537        }538539        conn.initAt(socket);540        try self.initializeTls(conn, host);541542        ClientOperation.writeRequest(543            &conn.tls_client.?.writer,544            method,545            host,546            path,547            headers,548            body,549        ) catch return error.WriteFailed;550        conn.tls_client.?.writer.flush() catch return error.WriteFailed;551        conn.socket_writer.writer.flush() catch return error.WriteFailed;552553        const status = try client_stream.ClientStream.readForMethod(554            stream_scratch,555            &conn.tls_client.?.reader,556            method,557            handler,558        );559        send_close_notify = true;560        return status;561    }562563    fn doPlainRequest(564        operation_scratch: OperationScratch,565        response_scratch: ResponseScratch,566        socket: sys.Socket,567        host: []const u8,568        path: []const u8,569        method: []const u8,570        headers: []const Header,571        body: []const u8,572    ) ClientError!ClientResponse {573        std.debug.assert(!isTunnelMethod(method));574        defer sys.close(socket);575576        var socket_writer = SocketWriter.init(socket, operation_scratch.plain_write);577        ClientOperation.writeRequest(578            &socket_writer.writer,579            method,580            host,581            path,582            headers,583            body,584        ) catch return error.WriteFailed;585        socket_writer.writer.flush() catch return error.WriteFailed;586587        var socket_reader = SocketReader.init(socket, operation_scratch.plain_read);588        return client_response.read(response_scratch, &socket_reader.reader, method);589    }590591    fn doPlainRequestStream(592        operation_scratch: OperationScratch,593        stream_scratch: StreamScratch,594        socket: sys.Socket,595        host: []const u8,596        path: []const u8,597        method: []const u8,598        headers: []const Header,599        body: []const u8,600        handler: StreamHandler,601    ) anyerror!u16 {602        std.debug.assert(!isTunnelMethod(method));603        defer sys.close(socket);604605        var socket_writer = SocketWriter.init(socket, operation_scratch.plain_write);606        ClientOperation.writeRequest(607            &socket_writer.writer,608            method,609            host,610            path,611            headers,612            body,613        ) catch return error.WriteFailed;614        socket_writer.writer.flush() catch return error.WriteFailed;615616        var socket_reader = SocketReader.init(socket, operation_scratch.plain_read);617        return client_stream.ClientStream.readForMethod(618            stream_scratch,619            &socket_reader.reader,620            method,621            handler,622        );623    }624};

1pub const Client = client.Client;