DOCSEARCHbyAlgolia
Submit Docs

HTTP.jl Documentation

repository·master·Indexed 20 days ago

https://github.com/juliaweb/http.jl

A comprehensive HTTP client and server implementation for Julia. It supports HTTP/2, WebSockets, Server-Sent Events (SSE), and proxy-aware transports. The library provides high-level client APIs for standard methods (GET, POST, PUT, etc.), streaming response bodies via HTTP.open, and both blocking (HTTP.listen) and non-blocking (HTTP.serve!) server implementations.

Tokens
16.2K
Snippets
55
Records
81
Agent score
71%

What's inside HTTP.jl

  1. Overview of HTTP.jl features

    master

    HTTP.jl provides a high-level HTTP stack built on top of Reseau.jl. Key features include:

    • Client Helpers: Familiar top-level functions like HTTP.get, HTTP.post, HTTP.request, and HTTP.open.
    • Client Controls: Explicit management via HTTP.Client, HTTP.Transport, HTTP.RetryBucket, HTTP.ProxyConfig, and HTTP.HTTP2Settings.
    • Timeout Controls: Granular control over connect_timeout, request_timeout, response_header_timeout, read_idle_timeout, and write_idle_timeout.
    • Server Entrypoints: Support for request/response handlers via HTTP.serve! and HTTP.listen!, as well as HTTP.streamhandler.
    • Protocol Support: Built-in HTTP/2 support and dedicated APIs for WebSockets.

  2. Manage the HTTP Server lifecycle

    master

    The HTTP.Server module provides the core primitives for running an HTTP server. You can use HTTP.listen or HTTP.listen! to start a server that listens on a specific port, or HTTP.serve / HTTP.serve! to handle requests.

    Key lifecycle functions include:

    • HTTP.listen / HTTP.listen!: Starts a server listening for incoming connections.
    • HTTP.serve / HTTP.serve!: High-level functions to serve content or handle requests.
    • HTTP.port: Retrieves the port the server is listening on.
    • HTTP.forceclose: Forces the closure of connections.
    • HTTP.peeraddr: Retrieves the address of the peer (client) connected to the server.

  3. Core types in HTTP.WebSockets

    master

    The HTTP.WebSockets module provides the following core types for managing WebSocket connections and errors:

    • HTTP.WebSockets.WebSocket: The primary interface for interacting with a WebSocket connection.
    • HTTP.WebSockets.Conn: Represents a connection instance.
    • HTTP.WebSockets.CloseFrameBody: Represents the body of a WebSocket close frame.
    • HTTP.WebSockets.WebSocketError: The error type thrown during WebSocket operations.

  4. How HTTP.jl and Reseau.jl relate

    master

    HTTP.jl is designed with a clear separation of concerns:

    • HTTP.jl owns the HTTP protocol stack (request/response logic, HTTP/2, WebSockets, etc.).
    • Reseau.jl owns the underlying transport, resolver, and TLS stack.

    This architecture allows HTTP.jl to maintain a familiar high-level surface while keeping request, response, body, transport, and stream types explicit. Client and server internals use an explicit state-machine design to improve reasoning about retries, proxying, streaming, and HTTP/2 behavior.

  5. Enable WebSocket message compression (permessage-deflate)

    master

    HTTP.jl supports the permessage-deflate extension (RFC 7692). Compression is opt-in on both ends via the compress = true keyword argument. If one side declines, the connection transparently falls back to uncompressed frames.

    Compression is most effective for large, repetitive text or JSON payloads. To prevent decompression bombs, the decompressed message size is bounded by maxframesize (defaults to 16 MiB). You can increase this value if your protocol requires larger messages.

    # server advertises permessage-deflate; clients may negotiate it
server = HTTP.WebSockets.listen!("127.0.0.1", 0; listenany = true, compress = true) do ws
    for msg in ws
        HTTP.WebSockets.send(ws, msg)
    end
end

# client offers compression
HTTP.WebSockets.open("ws://" * HTTP.WebSockets.server_addr(server); compress = true) do ws
    HTTP.WebSockets.send(ws, repeat("compress me ", 1000))  # sent compressed
    HTTP.WebSockets.receive(ws)
end

  6. Core HTTP types: Request, Response, and Headers

    master

    The HTTP module provides the fundamental building blocks for HTTP communication. The primary types are:

    • HTTP.Request: Represents an outgoing or incoming HTTP request.
    • HTTP.Response: Represents an incoming or outgoing HTTP response.
    • HTTP.Headers: A collection of key-value pairs representing HTTP headers.
    • HTTP.RequestContext: Manages the state and lifecycle of an active HTTP connection/request.

  7. Enable HTTP/2 support

    master

    The standard server entrypoints (serve!, listen!, and streamhandler) support HTTP/2.

    • For browser/production clients: Configure TLS to allow ALPN to select h2.
    • For cleartext-prior-knowledge clients: The server accepts the HTTP/2 connection preface on the normal listener.

  8. Reuse an HTTP Client for shared configuration

    master

    Use HTTP.Client to bundle transport settings, cookie jars, retry policies, and proxy configurations that should persist across multiple requests. This is more efficient than top-level calls when you need a specific set of behaviors (like HTTP/2 preference or a shared cookie state) to travel together.

    Verb helpers accept the client as the first positional argument: HTTP.get(client, url) is equivalent to HTTP.get(url; client = client).

    using HTTP

retry_bucket = HTTP.RetryBucket(capacity = 100)
transport = HTTP.Transport(max_idle_per_host = 2, max_idle_total = 4)
client = HTTP.Client(
    transport = transport,
    cookiejar = HTTP.CookieJar(),
    retry_bucket = retry_bucket,
)

# Use client positionally or via keyword
client_response = HTTP.request("GET", "http://example.com/reused"; client = client)
# OR
client_response = HTTP.get(client, "http://example.com/reused")

close(client)

  9. Monitor HTTP request lifecycle with Trace Events

    master

    You can observe the lifecycle of an HTTP request by hooking into HTTP.RequestEvents. The following event types are available for tracing:

    • HTTP.RequestEvent: Triggered during the request phase.
    • HTTP.ResponseHeadEvent: Triggered when the response headers are received.
    • HTTP.RetryEvent: Triggered when a request is being retried.
    • HTTP.RedirectEvent: Triggered when a redirect is encountered.
    • HTTP.DoneEvent: Triggered when the request/response cycle is complete.

  10. Implement Routing and Middleware

    master

    Routing and middleware logic is primarily located in the HTTP.Handlers module. For compatibility, these are also accessible via HTTP.Router and HTTP.register!.

    To build complex request handling logic, you can use:

    • HTTP.Handlers.Router: To define paths and map them to handlers.
    • HTTP.Handlers.Middleware: To wrap handlers with cross-cutting concerns (e.g., logging, authentication).
    • HTTP.Handlers.register!: To add new routes or handlers to a router.
    • HTTP.Handlers.getroute, HTTP.Handlers.getparams, and HTTP.Handlers.getparam: To extract routing information from an incoming request.
    • HTTP.Handlers.getcookies: To retrieve cookies from the request headers.

  11. Implement Middleware via function composition

    master

    Middleware in HTTP.jl is implemented by composing functions around handlers. For example, you can wrap a router or individual handlers with a timeout middleware using HTTP.Handlers.handlertimeout.

    using HTTP

timeout = HTTP.Handlers.handlertimeout(5.0; status = 503)
router = HTTP.Router(
    req -> HTTP.Response(404),
    req -> HTTP.Response(405),
    timeout,
)

  12. Migrate from HTTP.jl 1.x to 2.x

    master

    HTTP.jl 2.0 is a breaking release. Key changes include:

    • Minimum Julia Version: Julia 1.10 is required.
    • Core Building Blocks: Request, Response, Headers, RequestContext, bodies, Client, Transport, Server, and Stream are the primary public types.
    • Transport Layer: Transport, resolver, and TLS work is now delegated to Reseau.
    • Headers: HTTP.Headers is now a standalone mutable struct instead of a vector of pairs.
    • Request Context: RequestContext is a typed state object rather than a plain Dict.
    • Default Behavior: Top-level request helpers (like HTTP.get) now buffer Response.body::Vector{UInt8} by default.
    • WebSockets: Entrypoints are now located under HTTP.WebSockets.

    Recommended Upgrade Order

    1. Upgrade Julia and dependency compatibility.
    2. Update high-level client calls and response field access.
    3. Update explicit Request / Response constructors.
    4. Replace direct connection-pool, layer, parser, HPACK, or HTTP/2 internals with documented Client, Transport, Stream, server, or WebSocket APIs.
    5. Re-test timeout, retry, proxy, cookie, streaming, WebSocket, SSE, and HTTP/2 paths.