HTTP Client API Reference

Full-featured HTTP client library with request building, response handling, connection pooling, and TLS support

Import

U std/http_client

Overview

The HTTP Client module provides a complete HTTP/HTTPS client implementation with support for:

• All standard HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
• URL parsing and validation
• Header management (set, add, remove, get)
• Request/response body handling
• JSON, form, and text content types
• Authentication helpers (Bearer token, Basic auth)
• Connection pooling and keep-alive
• Automatic redirect following
• Timeout configuration
• TLS/HTTPS with SNI and certificate verification

Constants

HTTP Methods

Buffer Sizes

Default Configuration

Connection Pool

Error Codes

Structs

Url

URL component parser and builder.

Methods:

HttpRequest

HTTP request builder with chainable methods.

Constructors:

Header Management:

Body Methods:

Configuration:

Other Methods:

HttpResponse

Parsed HTTP response with status, headers, and body.

Constructors:

Status Checking:

Content Access:

Error Handling:

ConnectionPool

Connection pool for keep-alive connection reuse.

Methods:

HttpClient

Configurable HTTP client with connection pooling and redirect support.

Constructor:

Configuration:

Request Execution:

Convenience Methods:

Cleanup:

JSON Helper Functions

Top-Level Convenience Functions

Usage Examples

Simple GET Request

U std/http_client

F main() -> i64 {
    resp := http_get("https://api.example.com/users")

    I resp.is_success() == 1 {
        body := resp.body_text()
        __println(body)
        __println("Status: ", resp.status)
    } E {
        __println("Error: ", resp.error_text())
    }

    resp.drop()
    0
}

POST JSON Request

U std/http_client

F main() -> i64 {
    json := json_kv2("name", "Alice", "email", "alice@example.com")
    resp := http_post("https://api.example.com/users", json)

    I resp.is_success() == 1 {
        __println("Created: ", resp.body_text())
    }

    resp.drop()
    0
}

Custom Request with Headers

U std/http_client

F main() -> i64 {
    req := HttpRequest::get("https://api.example.com/protected")
        .with_bearer_token("eyJhbGc...")
        .set_header("X-Custom-Header", "value")
        .with_timeout(10000)  # 10 seconds

    client := HttpClient::new()
    resp := client.send(&req)

    I resp.is_success() == 1 {
        __println("Response: ", resp.body_text())
    }

    req.drop()
    resp.drop()
    client.drop()
    0
}

Reusable Client with Connection Pooling

U std/http_client

F main() -> i64 {
    client := HttpClient::new()
        .timeout(5000)
        .follow_redirects(1)
        .keep_alive(1)
        .default_header("User-Agent", "MyApp/1.0")

    # First request (creates connection)
    resp1 := client.get("http://example.com/api/users")
    __println("Status: ", resp1.status)
    resp1.drop()

    # Second request (reuses connection)
    resp2 := client.get("http://example.com/api/posts")
    __println("Status: ", resp2.status)
    resp2.drop()

    client.drop()
    0
}

PUT Request with JSON

U std/http_client

F main() -> i64 {
    json := json_kv2("name", "Bob", "status", "active")

    req := HttpRequest::put("https://api.example.com/users/123")
        .with_json(json)
        .with_bearer_token("token123")

    client := HttpClient::new()
    resp := client.send(&req)

    I resp.is_success() == 1 {
        __println("Updated successfully")
    } E {
        __println("Error: ", resp.status, " - ", resp.error_text())
    }

    req.drop()
    resp.drop()
    client.drop()
    0
}

Handling Response Headers

U std/http_client

F main() -> i64 {
    resp := http_get("https://api.example.com/data")

    # Get specific headers
    content_type := resp.content_type()
    M content_type {
        Some(ct) => __println("Content-Type: ", ct),
        None => __println("No Content-Type header")
    }

    content_len := resp.content_length()
    I content_len >= 0 {
        __println("Content-Length: ", content_len)
    }

    # Check if header exists
    I resp.has_header("X-Custom-Header") == 1 {
        custom := resp.get_header("X-Custom-Header")
        M custom {
            Some(val) => __println("Custom: ", val),
            None => 0
        }
    }

    resp.drop()
    0
}

Basic Authentication

U std/http_client

F main() -> i64 {
    # Encode "user:password" in base64
    encoded := "dXNlcjpwYXNzd29yZA=="

    req := HttpRequest::get("https://api.example.com/secure")
        .with_basic_auth(encoded)

    client := HttpClient::new()
    resp := client.send(&req)

    I resp.status == 200 {
        __println("Authenticated: ", resp.body_text())
    } E I resp.status == 401 {
        __println("Authentication failed")
    }

    req.drop()
    resp.drop()
    client.drop()
    0
}

Redirect Handling

U std/http_client

F main() -> i64 {
    client := HttpClient::new()
        .follow_redirects(1)
        .max_redirects(5)

    resp := client.get("http://example.com/redirect")

    I resp.is_success() == 1 {
        __println("Final response: ", resp.body_text())
    } E I resp.error_code == CLIENT_ERR_TOO_MANY_REDIRECTS {
        __println("Too many redirects")
    }

    resp.drop()
    client.drop()
    0
}

Error Handling

U std/http_client

F main() -> i64 {
    resp := http_get("https://invalid-domain-xyz.com")

    I resp.is_ok() == 0 {
        M resp.error_code {
            CLIENT_ERR_DNS => __println("DNS resolution failed"),
            CLIENT_ERR_CONNECT => __println("Connection failed"),
            CLIENT_ERR_TIMEOUT => __println("Request timed out"),
            CLIENT_ERR_TLS_INIT => __println("TLS initialization failed"),
            CLIENT_ERR_TLS_HANDSHAKE => __println("TLS handshake failed"),
            _ => __println("Unknown error: ", resp.error_text())
        }
    } E {
        __println("Status: ", resp.status)
    }

    resp.drop()
    0
}

Form Data POST

U std/http_client

F main() -> i64 {
    form := "username=alice&password=secret123&remember=true"

    req := HttpRequest::post("https://example.com/login")
        .with_form(form)

    client := HttpClient::new()
    resp := client.send(&req)

    I resp.is_redirect() == 1 {
        location := resp.location()
        M location {
            Some(url) => __println("Redirect to: ", url),
            None => __println("No location header")
        }
    }

    req.drop()
    resp.drop()
    client.drop()
    0
}

Notes

• HTTPS requires TLS support compiled into the runtime
• Connection pooling is only available for plain HTTP connections (not HTTPS)
• Default headers are applied to all requests sent through the client
• Redirects automatically convert POST/PUT/PATCH to GET for 301/302/303 status codes
• The client automatically adds default headers: User-Agent, Accept, Connection
• All strings returned by the API should be freed by the caller when appropriate
• Use drop() methods to free allocated memory for requests, responses, and clients