Skip to content
Goalchemy

lib/http

import "github.com/eugenioenko/goalchemy/lib/http"

Package http provides bounded HTTP exchanges, retaining TLS verification and returning redirect responses without following them.

Function c csharp go java python rust swift typescript
Do yes yes yes yes yes yes yes yes
DoWith yes yes yes yes yes yes yes yes
Exchange.Close yes yes yes yes yes yes yes yes
Exchange.Read yes yes yes yes yes yes yes yes
Exchange.Response yes yes yes yes yes yes yes yes
Exchange.Write yes yes yes yes yes yes yes yes
Open yes yes yes yes yes yes yes yes

Do

Section titled “Do”
func Do(ctx context.Context, method, rawURL string, headers []string, body []byte, maxResponseBytes int, timeoutMillis int64) (int, []string, []byte, error)

One bounded HTTP GET or POST exchange that keeps TLS verification and does not follow redirects.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: GET/POST only; GET has empty body. URL<=8192 bytes, request/reply body<=64MiB, header bytes<=64KiB, timeoutMillis=1..300000. Header input alternates name/value; odd length, invalid tokens, control bytes and framing/hop/proxy headers are rejected.
  • Errors: Transport, context cancellation/deadline and limit failures return zero status/nil headers/nil body and error. Non-2xx and redirects return ordinary responses.
  • Contract: lib.http.do 1.1.0

DoWith

Section titled “DoWith”
func DoWith(ctx context.Context, method, rawURL string, headers []string, body []byte, maxResponseBytes int, timeoutMillis int64, options []string) (int, []string, []byte, error)

Do with transport options for client certificates, extra root CAs, explicit insecure verification and Unix domain sockets.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: GET/POST only; GET has empty body. URL<=8192 bytes, request/reply body<=64MiB, header bytes<=64KiB, timeoutMillis=1..300000. Header input alternates name/value; odd length, invalid tokens, control bytes and framing/hop/proxy headers are rejected. Options alternate name/value with total name and value bytes <=1MiB; names are client-cert, client-key, root-cas, insecure-skip-verify and unix-socket, each at most once; client-cert and client-key come together; insecure-skip-verify is “true” or “false”; unix-socket is a path of 1..4096 bytes without NUL. Odd length, unknown or repeated names and other values are invalid requests.
  • Errors: Transport, context cancellation/deadline and limit failures return zero status/nil headers/nil body and error. Non-2xx and redirects return ordinary responses. Certificates, keys or root CAs that do not parse, or a key that does not match its certificate, return “http: invalid TLS option” where the host checks them before connecting; otherwise the handshake fails as a transport error. Browsers return “http: transport options are not supported in browsers” for any option; Java returns “http: unix sockets are not supported on this host” for unix-socket. A missing or refused socket is a transport error.
  • Contract: lib.http.do_with 1.1.0

Exchange.Close

Section titled “Exchange.Close”
func (e *Exchange) Close()

End the exchange and release its connection.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Errors: Close has no error result.
  • Contract: lib.http.exchange_close 1.0.0

Exchange.Read

Section titled “Exchange.Read”
func (e *Exchange) Read(max int) ([]byte, bool, error)

Read the next chunk of the response body.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: max=1..1048576.
  • Errors: Reads before Response return “http: invalid exchange operation”; after Close “http: exchange closed”; transport failures, cancellation and the deadline return errors.
  • Contract: lib.http.exchange_read 1.0.0

Exchange.Response

Section titled “Exchange.Response”
func (e *Exchange) Response() (int, []string, error)

End the request body and wait for the response status and headers.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: Response headers<=64KiB.
  • Errors: A known content length not written in full returns “http: invalid exchange operation”; after Close “http: exchange closed”; transport failures return zero status, nil headers and an error.
  • Contract: lib.http.exchange_response 1.0.0

Exchange.Write

Section titled “Exchange.Write”
func (e *Exchange) Write(p []byte) error

Send the next chunk of the request body.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: data<=1MiB. The total written must not exceed a known content length.
  • Errors: Writes after Response, beyond the content length or on an exchange without a body return “http: invalid exchange operation”; after Close “http: exchange closed”; transport failures, cancellation and the deadline return errors.
  • Contract: lib.http.exchange_write 1.0.0

Open

Section titled “Open”
func Open(ctx context.Context, method, rawURL string, headers []string, contentLength int64, timeoutMillis int64, options []string) (*Exchange, error)

Start a streamed HTTP exchange whose request body is written and response body read in chunks.

  • Gate: cooperative (may suspend the calling task)
  • Determinism: nondeterministic
  • Bounds: GET/POST only; contentLength is -1 (unknown, sent chunked) or the exact request body length, 0 for GET. URL<=8192 bytes, header bytes<=64KiB with the header rules of Do, timeoutMillis=1..86400000, options as for DoWith.
  • Errors: Invalid input returns a nil exchange and “http: invalid request or limit”; TLS options that do not parse return “http: invalid TLS option”; unsupported options fail as for DoWith. Connection failures surface from Write or Response.
  • Contract: lib.http.open 1.0.0