Outbound HTTP client

The public httpclient package provides an explicit standard-library client for generated or handwritten beans. It does not perform discovery or hidden network access.

httpclient.New requires an absolute HTTP(S) base URL without credentials, query, or fragment. Relative requests remain below that base path; absolute references, authority changes, dot-segment traversal, and fragments are rejected. Redirects receive the same origin and base-path enforcement, so a remote redirect cannot silently turn a configured integration into an arbitrary outbound request.

A nil http.Client selects a 30-second timeout. Caller-supplied clients are copied, not mutated, and retain their transport, cookie jar, timeout, and redirect callback behind Spice’s scope check. Request contexts remain caller-owned.

client, err := httpclient.New(httpclient.Options{
    BaseURL:   "https://inventory.example/v1",
    UserAgent: "commerce/1.2.0",
})
if err != nil {
    return err
}

response, err := httpclient.DoJSON[InventoryResponse](
    ctx,
    client,
    http.MethodPost,
    "reservations",
    CreateReservation{SKU: sku, Quantity: quantity},
)

Typed JSON helpers:

• set JSON request/response media types;
• bound response and error bodies to 4 MiB by default, with a 64 MiB maximum for typed decoding (larger payloads use the raw streaming API);
• accept JSON and application/*+json;
• return zero values for empty and 204 successes;
• optionally reject unknown response fields;
• close response bodies and report close/read failures;
• return status and defensive response headers.

Non-2xx responses return *httpclient.ResponseError. A valid RFC 9457 document is available through RemoteProblem, but Error() includes only status and never renders the remote detail or raw body. Raw NewRequest/Do remains available when streaming or custom codecs are required; callers own the returned response body, while Spice still enforces the configured base URL.