Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docs/cheatsheet.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Cheatsheet

Every function, function-like macro and variable in burrow's public headers, 7280 of them, one line each, grouped by header. Each line is the declaration, without its lifetime annotations, and a sentence about it. Where the function or variable has a Go original, the sentence is the first one of Go's doc comment for it. Where it has none, the sentence comes from the comment above it in the header.
Every function, function-like macro and variable in burrow's public headers, 7291 of them, one line each, grouped by header. Each line is the declaration, without its lifetime annotations, and a sentence about it. Where the function or variable has a Go original, the sentence is the first one of Go's doc comment for it. Where it has none, the sentence comes from the comment above it in the header.

This page is generated by `tools/burrow-cheatsheet` from the headers and from Go's sources at go1.27.3, and CI fails if it falls behind them, so edit those and run the tool rather than editing this.

Expand Down Expand Up @@ -5027,6 +5027,17 @@ The sentences taken from Go are reproduced from the doc comments of Go's `net/ht
- `Url *http_proxy_from_environment(Alloc *a, HttpRequest *req, Error *err)` – ProxyFromEnvironment returns the URL of the proxy to use for a given request, as indicated by the environment variables HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or the lowercase versions thereof).
- `HttpProxyFunc http_proxy_from_environment_func(void)` – http_proxy_from_environment as the HttpProxyFunc a transport takes.
- `HttpProxyFunc http_proxy_url(const Url *u)` – ProxyURL returns a proxy function (for use in a Transport) that always returns the same URL.
- `HttpClientConn *http_transport_new_client_conn(HttpTransport *t, Context ctx, Str scheme, Str address, Error *err)` – NewClientConn creates a new client connection to the given address.
- `Error http_client_conn_close(HttpClientConn *cc)` – Close closes the connection.
- `Error http_client_conn_err(HttpClientConn *cc)` – Err reports any fatal connection errors.
- `HttpResponse *http_client_conn_round_trip(HttpClientConn *cc, HttpRequest *req, Error *err)` – RoundTrip implements the RoundTripper interface.
- `Int http_client_conn_available(HttpClientConn *cc)` – Available reports the number of requests that may be sent to the connection without blocking.
- `Int http_client_conn_in_flight(HttpClientConn *cc)` – InFlight reports the number of requests in flight, including reserved requests.
- `Error http_client_conn_reserve(HttpClientConn *cc)` – Reserve reserves a concurrency slot on the connection.
- `void http_client_conn_release(HttpClientConn *cc)` – Release releases an unused concurrency slot reserved by Reserve.
- `void http_client_conn_set_state_hook(HttpClientConn *cc, HttpClientConnStateHook f)` – SetStateHook arranges for f to be called when the state of the connection changes.
- `HttpRoundTripper http_client_conn_as_round_tripper(HttpClientConn *cc)` – Not in Go: cc as the HttpRoundTripper it implements, which lasts as long as cc.
- `void http_client_conn_free(HttpClientConn *cc)` – Not in Go: closes the connection and gives cc back, once its state hook is not running.
- `extern const Error http_err_use_last_response` – ErrUseLastResponse can be returned by Client.CheckRedirect hooks to control how redirects are processed.
- `extern const Error http_err_scheme_mismatch` – ErrSchemeMismatch is returned when a server returns an HTTP response to an HTTPS client.
- `HttpResponse *http_client_do(HttpClient *c, HttpRequest *req, Error *err)` – Do sends an HTTP request and returns an HTTP response, following policy (such as redirects, cookies, auth) as configured on the client.
Expand Down
115 changes: 115 additions & 0 deletions include/burrow/net/http.h
Original file line number Diff line number Diff line change
Expand Up @@ -2045,6 +2045,121 @@ HttpProxyFunc http_proxy_from_environment_func(void);
* it, for every request. */
HttpProxyFunc http_proxy_url(const Url *u);

/* --------------------------------------------------------------- ClientConn */

/* A ClientConn is a client connection to an HTTP server.
*
* Unlike a [Transport], a ClientConn represents a single connection.
* Most users should use a Transport rather than creating client connections
* directly.
*
* Not in Go: give it back with http_client_conn_free, before the transport it
* came from is freed, and never from its state hook. */
typedef struct HttpClientConn HttpClientConn;

/* The state hook http_client_conn_set_state_hook takes. */
BURROW_FUNC(HttpClientConnStateHook, void, HttpClientConn *cc);

/* NewClientConn creates a new client connection to the given address.
*
* If scheme is "http", the connection is unencrypted.
* If scheme is "https", the connection uses TLS.
*
* The protocol used for the new connection is determined by the scheme,
* Transport.Protocols configuration field, and protocols supported by the
* server. See Transport.Protocols for more details.
*
* If Transport.Proxy is set and indicates that a request sent to the given
* address should use a proxy, the new connection uses that proxy.
*
* NewClientConn always creates a new connection,
* even if the Transport has an existing cached connection to the given host.
*
* The new connection is not added to the Transport's connection cache,
* and will not be used by [Transport.RoundTrip].
* It does not count against the MaxIdleConns and MaxConnsPerHost limits.
*
* The caller is responsible for closing the new connection.
*
* Not in Go: the error is in the caller's error_allocator. */
BURROW_OWNS(ret) HttpClientConn *http_transport_new_client_conn(HttpTransport *t,
Context ctx, Str scheme,
Str address,
Error *err);

/* Close closes the connection.
* Outstanding RoundTrip calls are interrupted. */
BURROW_STATIC(ret) Error http_client_conn_close(HttpClientConn *cc);

/* Err reports any fatal connection errors.
* It returns nil if the connection is usable.
* If it returns non-nil, the connection can no longer be used. */
BURROW_BORROWS(ret, cc) Error http_client_conn_err(HttpClientConn *cc);

/* RoundTrip implements the [RoundTripper] interface.
*
* The request is sent on the client connection,
* regardless of the URL being requested or any proxy settings.
*
* If the connection is at its concurrency limit,
* RoundTrip waits for the connection to become available
* before sending the request.
*
* Not in Go: the error is in the caller's error_allocator. */
BURROW_OWNS(ret) HttpResponse *
http_client_conn_round_trip(HttpClientConn *cc, HttpRequest *req, Error *err);

/* Available reports the number of requests that may be sent
* to the connection without blocking.
* It returns 0 if the connection is closed. */
Int http_client_conn_available(HttpClientConn *cc);

/* InFlight reports the number of requests in flight,
* including reserved requests.
* It returns 0 if the connection is closed. */
Int http_client_conn_in_flight(HttpClientConn *cc);

/* Reserve reserves a concurrency slot on the connection.
* If Reserve returns nil, one additional RoundTrip call may be made
* without waiting for an existing request to complete.
*
* The reserved concurrency slot is accounted as an in-flight request.
* A successful call to RoundTrip will decrement the Available count
* and increment the InFlight count.
*
* Each successful call to Reserve should be followed by exactly one call
* to RoundTrip or Release, which will consume or release the reservation.
*
* If the connection is closed or at its concurrency limit,
* Reserve returns an error. */
BURROW_BORROWS(ret, cc) Error http_client_conn_reserve(HttpClientConn *cc);

/* Release releases an unused concurrency slot reserved by Reserve.
* If there are no reserved concurrency slots, it has no effect. */
void http_client_conn_release(HttpClientConn *cc);

/* SetStateHook arranges for f to be called when the state of the connection
* changes. At most one call to f is made at a time.
* If the connection's state has changed since it was created,
* f is called immediately in a separate goroutine.
* f may be called synchronously from RoundTrip or Response.Body.Close.
*
* If SetStateHook is called multiple times, the new hook replaces the old one.
* If f is nil, no further calls will be made to f after SetStateHook returns.
*
* f is called when Available increases (more requests may be sent on the
* connection), InFlight decreases (existing requests complete), or Err begins
* returning non-nil (the connection is no longer usable). */
void http_client_conn_set_state_hook(HttpClientConn *cc, HttpClientConnStateHook f);

/* Not in Go: cc as the HttpRoundTripper it implements, which lasts as long
* as cc. */
HttpRoundTripper http_client_conn_as_round_tripper(HttpClientConn *cc);

/* Not in Go: closes the connection and gives cc back, once its state hook is
* not running. NULL is fine. */
void http_client_conn_free(HttpClientConn *cc);

/* ------------------------------------------------------------------- Client */

/* http.ErrUseLastResponse, which check_redirect gives to stop following
Expand Down
9 changes: 9 additions & 0 deletions src/net/http2.h
Original file line number Diff line number Diff line change
Expand Up @@ -1288,6 +1288,15 @@ Int burrow__http2_client_conn_streams_active(Http2ClientConn *cc);

void burrow__http2_client_conn_release(Http2ClientConn *cc);

/* NewClientConn: a connection on c for net/http's ClientConn, which takes c
* whatever happens, with one reference, the caller's. hook is the
* internalStateHook. Not in Go: done is called once whatever happens, when
* the connection is gone and calls hook no more. Its RoundTrip waits for a
* stream when the connection is at its concurrency limit. */
BURROW_OWNS(ret) Http2ClientConn *
burrow__http2_transport_new_client_conn(Http2Transport *t2, NetConn c, Str key,
Func hook, Func done, Error *err);

/* IdleConnStrsForTesting: the address of each connection that can take a new
* request, sorted, as a Slice of Str in a. */
BURROW_OWNS(ret) Slice burrow__http2_transport_idle_conn_strs(Http2Transport *t2,
Expand Down
Loading
Loading