std/http

HTTP

The std/http module provides synchronous HTTP request execution (GET, POST, PUT, DELETE) and concurrent multi-target dispatch. All network activity is governed under strict host authority to prevent unauthorized outbound connections from AI-generated scripts.

Response Object Model

Every completed network request produces an HttpResponse instance exposing status codes, headers, and response body payloads.

class HttpResponse {
    val status: Int                    // HTTP status code (200, 201, 404, 500, ...)
    val ok: Bool                       // True if status code falls within 200..299
    val url: String                    // Final resolved destination URL after redirects
    val headers: Map<String, String>   // Response headers collection
    val body: String                   // Response payload as string

    fun statusCode(): Int              // Method to retrieve status code
    fun isOk(): Bool                   // Success check
    fun isSuccess(): Bool              // Alias for isOk()
    fun text(): String                 // Reads full response body string
}

Core Request Operations

Network operations require an explicit timeout parameter (in milliseconds). If the destination server times out or cannot be reached, an exception is thrown for deterministic error recovery.

@import("std/http")

val endpoint = "https://api.erp-system.internal/v1/invoices"
val timeoutMs = 3000

try {
    // 1. Send GET request
    val getRes = Http.get(endpoint + "/INV-2026", timeoutMs)
    if (getRes.isSuccess()) {
        println("Invoice data: " + getRes.text())
    }

    // 2. Send POST request to create record
    val newPayload = "{\"customer\": \"ACME\", \"amount\": 5000}"
    val postRes = Http.post(endpoint, newPayload, timeoutMs)
    println("POST status code: " + postRes.statusCode())

    // 3. Send PUT request to update record
    val updatePayload = "{\"status\": \"SETTLED\"}"
    val putRes = Http.put(endpoint + "/INV-2026", updatePayload, timeoutMs)
    println("Update status: " + putRes.status)

    // 4. Send DELETE request to retract
    val delRes = Http.delete(endpoint + "/INV-TEMP", timeoutMs)
    println("Deletion status: " + delRes.isOk())
} catch (e) {
    println("Network request failed: " + e.message)
}

Concurrent Request Execution

Use Http.getAll() to execute multiple GET requests concurrently at the host layer. Responses are returned in an array of HttpResponse objects matching the order of input URLs.

@import("std/http")

val endpoints = <String>[
    "https://api.erp-system.internal/v1/rates/usd",
    "https://api.erp-system.internal/v1/rates/eur",
    "https://api.erp-system.internal/v1/rates/jpy"
]

val responses = Http.getAll(endpoints, 5000)
println("Total responses: " + responses.size())

for (res in responses) {
    if (res.ok) {
        println("Rate at " + res.url + " size: " + res.body.size())
    }
}

Security Governance & Resource Boundaries

Under the Autolang execution model, AI code is untrusted. The host application maintains absolute authority and enforces rigorous limits before any network connection is established:

1. Domain Allowlist

The host configures regular expression rules for authorized endpoints. If unconfigured, the VM defaults to blocking all outbound network traffic.

2. URL Length Limits

URLs exceeding 512 characters are immediately rejected to prevent buffer overflow attacks and anomalous payloads.

3. Response Size Quotas

Response payloads are capped at 5MB to shield the VM heap from out-of-memory denial-of-service conditions.

4. Security Exceptions

When an unapproved endpoint is requested, the VM halts execution and throws an explicit SecurityError.

Method Reference

Static Http Methods

Http.get(url: String, timeoutMs: Int): HttpResponse: Synchronous GET request.
Http.post(url: String, body: String, timeoutMs: Int): HttpResponse: Synchronous POST request with payload.
Http.put(url: String, body: String, timeoutMs: Int): HttpResponse: Synchronous PUT request to update resource.
Http.delete(url: String, timeoutMs: Int): HttpResponse: Synchronous DELETE request.
Http.getAll(urls: Array<String>, timeoutMs: Int): Array<HttpResponse>: Concurrently dispatches multiple GET requests and returns mapped results.

HttpResponse Properties & Methods

status: Int / statusCode(): Int: HTTP response status code.
ok: Bool / isOk(): Bool / isSuccess(): Bool: Returns true if status code falls within 200..299.
url: String: Final resolved URL after redirections.
headers: Map<String, String>: Normalized response headers map.
body: String / text(): String: Full response body payload string.