From c63af5d3eced9ffa0aad6426e7aba8512ab61d74 Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Sun, 12 Feb 2023 13:05:11 +0100 Subject: [PATCH] Improve documentation and transport semantics --- net/http/client.ha | 13 ++++++++++--- net/http/request.ha | 7 ++++++- net/http/transport.ha | 44 +++++++++++++++++++++++-------------------- 3 files changed, 40 insertions(+), 24 deletions(-) diff --git a/net/http/client.ha b/net/http/client.ha index 069ee57..bf2a4bd 100644 --- a/net/http/client.ha +++ b/net/http/client.ha @@ -10,9 +10,16 @@ export type client = struct { default_transport: transport, }; -// Creates a new HTTP [[client]] with the provided User-Agent string, which is -// borrowed from the caller. Pass the return value to [[client_finish]] to free -// resourfces associated with the HTTP client after use. +// Creates a new HTTP [[client]] with the provided User-Agent string. +// +// The HTTP client implements a number of sane defaults, which may be tuned. The +// set of default headers is configured with [[client_default_header]], and the +// default transport behavior with [[client_default_transport]]. +// +// TODO: Implement and document the connection pool +// +// The caller must pass the client object to [[client_finish]] to free resources +// associated with this client after use. export fn newclient(ua: str) client = { let client = client { ... }; header_add(&client, "User-Agent", ua); diff --git a/net/http/request.ha b/net/http/request.ha index a975299..ec982bb 100644 --- a/net/http/request.ha +++ b/net/http/request.ha @@ -2,6 +2,11 @@ use io; use net::uri; // Stores state related to an HTTP request. +// +// For a request to be processable by an HTTP [[client]], i.e. via [[do]], the +// method and target must be filled in appropriately. The target must include at +// least a host, port, and scheme. The default values for other fields are +// suitable if appropriate for the request you wish to perform. export type request = struct { // HTTP request method, e.g. GET method: str, @@ -18,7 +23,7 @@ export type request = struct { // Transport configuration, or null to use the [[client]] default. transport: nullable *transport, - // I/O reader for the request body. + // I/O reader for the request body, or void if there is no body. body: (io::handle | void), }; diff --git a/net/http/transport.ha b/net/http/transport.ha index e71bc09..c62fcff 100644 --- a/net/http/transport.ha +++ b/net/http/transport.ha @@ -6,46 +6,50 @@ use strconv; use strings; use types; -// Configures the transport mode. +// Configures the Transport-Encoding behavior. // -// For clients, if set to "none", no transport decoding is performed on the -// response body, and the user must read the Transport-Encoding header and -// decode it themselves. If set to "auto", [[response]].body will be decoded -// according to the response's Transport-Encoding header. Most users will want -// this to be set to "auto". +// If set to "none", no transport decoding or encoding is performed on the +// message body, irrespective of the value of the Transport-Encoding header. The +// user must perform any required encoding or decoding themselves in this mode. +// If set to "auto", the implementation will examine the Transport-Encoding +// header and encode the message body appropriately. // -// For servers, if set to "auto", net::http will examine the Transport-Encoding -// header and apply the appropriate transport encoding. If set to "none", the -// response body will be sent directly to the client with no further processing. +// Most users will want this to be set to "auto". +// +// TODO: Document server behavior export type transport_mode = enum { AUTO = 0, NONE, }; -// Configures the content mode. +// Configures the Content-Encoding behavior. // -// For clients, if set to "none", no content decoding is performed on the -// response body, and the user must read the Content-Encoding header and decode -// it themselves. If set to "auto", [[response]].body will be decoded according -// to the response's Content-Encoding header. Most users will want this to be -// set to "auto". +// If set to "none", no transport decoding or encoding is performed on the +// message body, irrespective of the value of the Content-Encoding header. The +// user must perform any required encoding or decoding themselves in this mode. +// If set to "auto", the implementation will examine the Content-Encoding header +// and encode the message body appropriately. // -// For servers, if set to "auto", net::http will examine the Content-Encoding -// header and apply the appropriate content encoding. If set to "none", the -// response body will be sent directly to the client with no further processing. +// Most users will want this to be set to "auto". +// +// TODO: Document server behavior export type content_mode = enum { AUTO = 0, NONE, }; // Describes an HTTP [[client]]'s transport configuration for a given request. +// +// The default value of this type sets all parameters to "auto". export type transport = struct { // Desired Transport-Encoding configuration, see [[transport_mode]] for // details. - transport: transport_mode, + request_transport: transport_mode, + response_transport: transport_mode, // Desired Content-Encoding configuration, see [[content_mode]] for // details. - content: content_mode, + request_content: content_mode, + response_content: content_mode, }; fn new_reader(