std/net/http

Standard Library documentation

HTTP/web client foundation.

Back to Stdlib View Source

Module

Name
std/net/http
Area
Standard Library
Source
modules/std/net/http.zzm

NAME

std/net/http - HTTP/web client foundation.

SYNOPSIS

  from std/net/http import CookieJar, UserAgent;

  let jar := new CookieJar();
  let ua  := new UserAgent(
    cookie_jar: jar,
    agent: "my-app/1.0"
  );

  let req := ua
    .build_request("GET", "https://example.com/items")
    .query({ page: "1" })
    .auth_bearer("TOKEN");

  let res := ua.send(req);
  let data := res.expect_success().json();

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is partially supported by zuzu-js in the browser: asynchronous HTTP, cookie jar, header normalization, URL, timeout, and retry coverage passes, but synchronous request coverage is unsupported.

DESCRIPTION

This module provides an HTTP client API with classes for cookie handling, request building, retries/timeouts, and JSON-first responses.

EXPORTS

Classes

  • CookieJar(config?)

    Creates a cookie jar. Returns: CookieJar.

    • jar.add(String url, String set_cookie)

      Parameters: url is the source URL and set_cookie is a Set-Cookie header value. Returns: CookieJar. Stores cookies from the header.

    • jar.cookie_header(String url)

      Parameters: url is a request URL. Returns: String or null. Builds the Cookie header value for url.

    • jar.clear()

      Parameters: none. Returns: CookieJar. Removes all stored cookies.

  • UserAgent(config?)

    Creates an HTTP user agent. Returns: UserAgent.

    Supported config keys include default_headers, cookie_jar, max_redirect, timeout, and TLS policy keys: tls_identity, tls_ca, tls_verify, tls_server_name, tls_min_version, and tls_ciphers.

    tls_identity accepts a std/secure TlsIdentity or null. tls_ca accepts a std/secure Certificate, PEM certificate text, an array of those, or null. tls_verify defaults to true. tls_min_version accepts "tls1.2" or "tls1.3". tls_ciphers is a backend-native cipher string.

    Backends throw a clear unsupported error for non-default TLS settings they cannot honour. JS/Browser does not support script-selected TLS client configuration; any non-default TLS policy throws when sending.

    Builder and dispatch methods:

    • build_request(method, url)

      Parameters: method is an HTTP method and url is the request URL. Returns: Request. Builds a mutable request.

    • send(request)

      Parameters: request is a Request. Returns: Response. Sends the request synchronously.

    • send_async(request)

      Parameters: request is a Request. Returns: Task. Sends the request asynchronously.

    Request methods:

    • Generic

      request(method, url, data?, headers?)

      Parameters: method is an HTTP method, url is the request URL, data is optional request data, and headers are optional headers. Returns: Response. Builds and sends one request.

    • Async generic

      request_async(method, url, data?, headers?)

      Parameters: same as request. Returns: Task. Asynchronous request helper resolving to Response.

    • Convenience

      get, head, delete, options, post, put, patch.

      get_async, head_async, delete_async, options_async, post_async, put_async, and patch_async return awaitable Task values which resolve to Response.

      For post, put, and patch, pass data then optional headers. For the others, the second argument can be headers.

  • Request

    Mutable request builder. Returns: Request when constructed by the user agent.

    • request.method(value?), request.url(value?)

      Parameters: optional value updates the method or URL. Returns: String when reading, or Request when setting.

    • request.header(name, value?)

      Parameters: name is a header name and value is optional. Returns: String or Request. Gets or sets one request header.

    • request.headers(value?)

      Parameters: optional value is header data. Returns: header data or Request. Gets or replaces request headers.

    • request.query(values)

      Parameters: values is query parameter data. Returns: Request. Adds query parameters to the request URL.

    • request.body(value?), request.content(value?)

      Parameters: optional value is request body data. Returns: body value or Request. Gets or sets the request body.

    • request.json(value)

      Parameters: value is JSON-encodable data. Returns: Request. Sets a JSON request body and content type.

    • request.auth_bearer(String token)

      Parameters: token is a bearer token. Returns: Request. Sets the Authorization header.

    • request.timeout(Number seconds), request.retries(Number count)

      Parameters: numeric values configure request behaviour. Returns: Request. Sets timeout or retry policy.

    • request.download_to(path), request.upload_from(path)

      Parameters: path is a std/io Path or compatible path value. Returns: Request. Configures response download or request upload.

    • request.tls_identity(identity_or_null)

      Parameters: identity_or_null is a TLS identity or null. Returns: Request. Overrides the user-agent TLS identity for the request.

    • request.multipart(parts)

      Parameters: parts describes multipart form parts. Returns: Request. Sets a multipart request body.

    • request.send(user_agent)

      Parameters: user_agent is a UserAgent. Returns: Response. Sends the request synchronously.

    • request.send_async(user_agent)

      Parameters: user_agent is a UserAgent. Returns: Task. Sends the request asynchronously.

    tls_identity(identity_or_null) overrides the user-agent TLS identity for that request only. Passing null disables any user-agent identity for that request.

  • Response

    Represents an HTTP response.

    • response.status(), response.reason(), response.url()

      Parameters: none. Returns: Number for status, otherwise String. Returns response metadata.

    • response.content()

      Parameters: none. Returns: BinaryString or value. Returns the response body.

    • response.headers()

      Parameters: none. Returns: header data. Returns response headers.

    • response.header(String name)

      Parameters: name is a header name. Returns: String or null. Returns the first matching response header.

    • response.success()

      Parameters: none. Returns: Boolean. Returns true for a successful HTTP status.

    • response.json()

      Parameters: none. Returns: value. Decodes the response body as JSON.

    • response.expect_success()

      Parameters: none. Returns: Response. Returns the response or throws for an unsuccessful status.

    • response.to_Dict()

      Parameters: none. Returns: Dict. Converts the response to a dictionary.

JS/BROWSER SYNCHRONOUS REQUEST SUPPORT

In the JS/Browser implementation, synchronous request methods do not perform real network requests. These methods return a Response with status 599 and reason Synchronous HTTP is unsupported on JS/Browser. Use the asynchronous methods in JS/Browser.

COPYRIGHT AND LICENCE

std/net/http is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.