authorgravatar for truemedian@gmail.comNameless <truemedian@gmail.com> 2023-10-07 19:58:15-05:00
committergravatar for truemedian@gmail.comNameless <truemedian@gmail.com> 2023-10-21 20:52:59-05:00
logd4cf8ea0b7621f7757203ecdbaa760e99cbc455c
tree0aaab7ada9b70a0cdf942004d0a3692bee9dcc77
parentc523b5421be86cdd0591a5672eeaea30fb142fe4
signaturelock-open Commit is signed but in an unrecognized format.

std.http.Client: improve documentation

1 files changed, 33 insertions(+), 5 deletions(-)

lib/std/http/Client.zig+33-5
......@@ -489,13 +489,21 @@ pub const Response = struct {
489489 status: http.Status,
490490 reason: []const u8,
491491
492 /// If present, the number of bytes in the response body.
492493 content_length: ?u64 = null,
494
495 /// If present, the transfer encoding of the response body, otherwise none.
493496 transfer_encoding: http.TransferEncoding = .none,
497
498 /// If present, the compression of the response body, otherwise identity (no compression).
494499 transfer_compression: http.ContentEncoding = .identity,
495500
501 /// The headers received from the server.
496502 headers: http.Headers,
497503 parser: proto.HeadersParser,
498504 compression: Compression = .none,
505
506 /// Whether the response body should be skipped. Any data read from the response body will be discarded.
499507 skip: bool = false,
500508};
501509
......@@ -511,6 +519,8 @@ pub const Request = struct {
511519 method: http.Method,
512520 version: http.Version = .@"HTTP/1.1",
513521 headers: http.Headers,
522
523 /// The transfer encoding of the request body.
514524 transfer_encoding: RequestTransfer = .none,
515525
516526 redirects_left: u32,
......@@ -595,7 +605,7 @@ pub const Request = struct {
595605 raw_uri: bool = false,
596606 };
597607
598 /// Send the request to the server.
608 /// Send the HTTP request to the server.
599609 pub fn start(req: *Request, options: StartOptions) StartError!void {
600610 if (!req.method.requestHasBody() and req.transfer_encoding != .none) return error.UnsupportedTransferEncoding;
601611
......@@ -730,6 +740,8 @@ pub const Request = struct {
730740 ///
731741 /// If `handle_redirects` is true and the request has no payload, then this function will automatically follow
732742 /// redirects. If a request payload is present, then this function will error with error.RedirectRequiresResend.
743 ///
744 /// Must be called after `start` and, if any data was written to the request body, then also after `finish`.
733745 pub fn wait(req: *Request) WaitError!void {
734746 while (true) { // handle redirects
735747 while (true) { // read headers
......@@ -865,7 +877,7 @@ pub const Request = struct {
865877 return .{ .context = req };
866878 }
867879
868 /// Reads data from the response body. Must be called after `do`.
880 /// Reads data from the response body. Must be called after `wait`.
869881 pub fn read(req: *Request, buffer: []u8) ReadError!usize {
870882 const out_index = switch (req.response.compression) {
871883 .deflate => |*deflate| deflate.read(buffer) catch return error.DecompressionFailure,
......@@ -896,7 +908,7 @@ pub const Request = struct {
896908 return out_index;
897909 }
898910
899 /// Reads data from the response body. Must be called after `do`.
911 /// Reads data from the response body. Must be called after `wait`.
900912 pub fn readAll(req: *Request, buffer: []u8) !usize {
901913 var index: usize = 0;
902914 while (index < buffer.len) {
......@@ -915,7 +927,8 @@ pub const Request = struct {
915927 return .{ .context = req };
916928 }
917929
918 /// Write `bytes` to the server. The `transfer_encoding` request header determines how data will be sent.
930 /// Write `bytes` to the server. The `transfer_encoding` field determines how data will be sent.
931 /// Must be called after `start` and before `finish`.
919932 pub fn write(req: *Request, bytes: []const u8) WriteError!usize {
920933 switch (req.transfer_encoding) {
921934 .chunked => {
......@@ -936,6 +949,8 @@ pub const Request = struct {
936949 }
937950 }
938951
952 /// Write `bytes` to the server. The `transfer_encoding` field determines how data will be sent.
953 /// Must be called after `start` and before `finish`.
939954 pub fn writeAll(req: *Request, bytes: []const u8) WriteError!void {
940955 var index: usize = 0;
941956 while (index < bytes.len) {
......@@ -946,6 +961,7 @@ pub const Request = struct {
946961 pub const FinishError = WriteError || error{MessageNotCompleted};
947962
948963 /// Finish the body of a request. This notifies the server that you have no more data to send.
964 /// Must be called after `start`.
949965 pub fn finish(req: *Request) FinishError!void {
950966 switch (req.transfer_encoding) {
951967 .chunked => try req.connection.?.writer().writeAll("0\r\n\r\n"),
......@@ -1134,6 +1150,8 @@ pub fn connectTcp(client: *Client, host: []const u8, port: u16, protocol: Connec
11341150
11351151pub const ConnectUnixError = Allocator.Error || std.os.SocketError || error{ NameTooLong, Unsupported } || std.os.ConnectError;
11361152
1153/// Connect to `path` as a unix domain socket. This will reuse a connection if one is already open.
1154/// This function is threadsafe.
11371155pub fn connectUnix(client: *Client, path: []const u8) ConnectUnixError!*Connection {
11381156 if (!net.has_unix_sockets) return error.Unsupported;
11391157
......@@ -1166,6 +1184,8 @@ pub fn connectUnix(client: *Client, path: []const u8) ConnectUnixError!*Connecti
11661184 return &conn.data;
11671185}
11681186
1187/// Connect to `tunnel_host:tunnel_port` using the specified proxy with HTTP CONNECT. This will reuse a connection if one is already open.
1188/// This function is threadsafe.
11691189pub fn connectTunnel(
11701190 client: *Client,
11711191 proxy: *ProxyInformation,
......@@ -1245,6 +1265,11 @@ pub fn connectTunnel(
12451265const ConnectErrorPartial = ConnectTcpError || error{ UnsupportedUrlScheme, ConnectionRefused };
12461266pub const ConnectError = ConnectErrorPartial || RequestError;
12471267
1268/// Connect to `host:port` using the specified protocol. This will reuse a connection if one is already open.
1269///
1270/// If a proxy is configured for the client, then the proxy will be used to connect to the host.
1271///
1272/// This function is threadsafe.
12481273pub fn connect(client: *Client, host: []const u8, port: u16, protocol: Connection.Protocol) ConnectError!*Connection {
12491274 // pointer required so that `supports_connect` can be updated if a CONNECT fails
12501275 const potential_proxy: ?*ProxyInformation = switch (protocol) {
......@@ -1318,7 +1343,7 @@ pub const protocol_map = std.ComptimeStringMap(Connection.Protocol, .{
13181343 .{ "wss", .tls },
13191344});
13201345
1321/// Form and send a http request to a server.
1346/// Open a connection to the host specified by `uri` and prepare to send a HTTP request.
13221347///
13231348/// `uri` must remain alive during the entire request.
13241349/// `headers` is cloned and may be freed after this function returns.
......@@ -1420,6 +1445,9 @@ pub const FetchResult = struct {
14201445 }
14211446};
14221447
1448/// Perform a one-shot HTTP request with the provided options.
1449///
1450/// This function is threadsafe.
14231451pub fn fetch(client: *Client, allocator: Allocator, options: FetchOptions) !FetchResult {
14241452 const has_transfer_encoding = options.headers.contains("transfer-encoding");
14251453 const has_content_length = options.headers.contains("content-length");