module.ae

// std.http - HTTP Client & Server (alias for std.net)
//
// NB the pure-Aether TLS backends are deliberately NOT imported here.
// std.cryptography.tls13_server reads the certificate and key with std.fs, so
// importing it from this module gave every std.http user an fs/os capability
// requirement they had not asked for -- `--emit=lib --with=net` started
// rejecting `import std.http` because the graph now reached std.os. Serving
// TLS genuinely does need file access, so the opt-in belongs at the
// application that wants it:
//
//     import std.http
//     import std.cryptography.tls13_server   // pure TLS server, needs --with=fs
//
// The C side reaches the implementation through weak symbols
// (aether_pure_tls_server_* in aether_http_server.c), so the import is purely
// what pulls the definitions into the link; nothing here calls them.
//
// This is a convenience module that re-exports HTTP functions from std.net.
// You can use either:
//   import std.http  (this module)
//   import std.net   (consolidated networking module)
//
// The implementations are in std/net/aether_http.c and std/net/aether_http_server.c
// which are compiled into libaether.a

exports(
    http_get_raw, http_get_with_timeout_raw, http_get_with_timeout_ns_raw,
    http_post_raw, http_put_raw, http_delete_raw,
    http_response_free, http_response_status_code,
    http_response_body_str, http_response_headers_str,
    http_response_status, http_response_body, http_response_headers,
    http_response_error, http_response_ok,
    get, get_with_timeout, post, put, delete,
    http_client_pool_configure_raw, http_client_pool_clear_raw,
    http_client_pool_idle_count_raw, http_client_rx_buffer_allocs_raw,
    client_pool_configure, client_pool_disable, client_pool_clear,
    client_pool_idle_count, client_rx_buffer_allocs,
    http_server_create, http_server_bind_raw, http_server_port, http_server_start_raw,
    server_set_host,
    http_server_start_background_raw,
    http_server_stop, http_server_free,
    http_server_set_tls_raw, server_set_tls,
    http_server_set_keepalive_raw, server_set_keepalive,
    http_server_set_h2_raw, server_set_h2,
    http_server_set_h2_concurrent_dispatch_raw, server_set_h2_concurrent_dispatch,
    http_server_drain_connection,
    http_server_shutdown_graceful_raw, server_shutdown_graceful,
    server_on_start, server_on_stop,
    http_server_set_health_probes_raw, server_set_health_probes,
    http_server_set_access_log_raw, server_set_access_log,
    http_server_set_metrics_raw, server_set_metrics,
    server_sse,
    http_response_sse_upgrade_raw,
    sse_send, sse_send_id, sse_send_full, sse_comment, sse_close,
    response_upgrade_sse,
    response_begin_chunked, chunked_write, chunked_end,
    server_websocket,
    ws_connect, ws_client_free,
    http_ws_message_length,
    ws_send_text, ws_send_binary, ws_recv,
    ws_recv_timeout, ws_poll, ws_fd,
    ws_message, ws_message_bytes, ws_close,
    server_bind, server_start, server_start_background,
    http_server_add_route, http_server_get, http_server_post,
    http_server_put, http_server_delete,
    http_server_use_middleware,
    http_get_header, http_get_query_param, http_get_path_param,
    http_request_free,
    http_response_create, http_response_set_status, http_response_get_status,
    http_response_set_header, http_response_add_header,
    http_response_clear_headers,
    http_response_set_body, response_set_body_bytes,
    response_accept_tunnel,
    http_response_json, http_server_response_free,
    http_server_set_actor_handler,
    http_request_body_read_raw, http_get_request_body_read,
    http_get_request_body_read_length, http_release_request_body_read,
    request_body_read, request_body_complete,
    http_mime_type,
    serve_file, serve_static,
    request_method, request_path, request_body,
    request_body_length, request_body_bytes, request_query,
    request_remote_addr, request_remote_port,
    request_local_addr, request_local_port,
    request_scheme, request_is_tls, request_http_version,
    request_header_count, request_header_name, request_header_value,
    ae_io_cancel, await_io
)

// HTTP Client — raw ptr-returning externs.
// These are the escape hatch for code that needs direct access to the
// underlying HttpResponse struct (e.g. to inspect headers and body
// together, or to implement custom retry logic). Most callers should
// use the Go-style wrappers below.
// Idle connection pool. The client keeps a connection open after a response
// whose length was definite and reuses it for the next request to the same
// origin, which is what HTTP/1.1 is designed for: a proxy or a polling client
// otherwise pays a TCP (and TLS) handshake per request.
//
// Reuse is on by default. Connections are keyed by origin, the proxy actually
// dialled, TLS, and the verification the caller asked for, so a pinned-CA or
// verification-off connection is never handed to a request that did not ask
// for it.
extern http_client_pool_configure_raw(max_idle: int, max_per_host: int, idle_ns: long) -> string
extern http_client_pool_clear_raw()
extern http_client_pool_idle_count_raw() -> int
extern http_client_rx_buffer_allocs_raw() -> long

extern http_get_raw(url: string) -> ptr
// http.get with a per-call timeout. 0ns blocks forever
// (matches http.get's default). Sub-second values are rounded UP to
// whole seconds because the underlying SO_RCVTIMEO field is integer
// seconds. Use this any time the target URL isn't local — a hung
// DNS lookup or unresponsive server otherwise stalls the calling
// actor's entire message handler.
extern http_get_with_timeout_raw(url: string, timeout_ms: int) -> ptr
extern http_get_with_timeout_ns_raw(url: string, timeout: Duration) -> ptr
extern http_post_raw(url: string, body: string, content_type: string) -> ptr
extern http_put_raw(url: string, body: string, content_type: string) -> ptr
extern http_delete_raw(url: string) -> ptr
extern http_response_free(response: ptr)
extern http_response_status_code(response: ptr) -> int
extern http_response_body_str(response: ptr) -> string
extern http_response_headers_str(response: ptr) -> string

// HTTP Client - response accessors (used by both raw callers and the
// Go-style wrappers below).
extern http_response_status(response: ptr) -> int
extern http_response_body(response: ptr) -> string @heap
extern http_response_headers(response: ptr) -> string
extern http_response_error(response: ptr) -> string
extern http_response_ok(response: ptr) -> int

// string_concat used internally to duplicate borrowed strings before the
// backing response is freed. The concat of any string with "" produces a
// new heap-allocated copy that outlives the source.
extern string_concat(a: string, b: string) -> string @heap

// HTTP Client — Go-style result-type wrappers. These are the idiomatic
// Aether-facing API: they auto-free the underlying response and return
// `(body, err)` or `(status, err)` tuples.
//
// On success, the error string is empty ("") and the value is valid.
// On failure, the value is a zero-value ("" or 0) and the error string
// describes what went wrong. Errors include both transport-level
// failures (DNS, connect, send) and non-2xx HTTP status codes.

// Resize the idle connection pool: how many idle connections to keep in
// total, how many of those may be to one origin, and how long an unused one
// is kept before it is closed. The defaults are the call below.
//
//     http.client_pool_configure(64, 8, 15s)
//
// Keep the idle time under the upstream's own keep-alive timeout, or the
// server closes connections while they sit here and every reuse costs a
// retry.
client_pool_configure(max_idle: int, max_per_host: int, idle: Duration) -> string {
    return http_client_pool_configure_raw(max_idle, max_per_host, idle)
}

// Turn connection reuse off and close what is held. Every request then opens
// its own connection, which is what the client did before reuse existed.
client_pool_disable() {
    _ = http_client_pool_configure_raw(0, -1, -1)
}

// Close every idle connection. Useful before measuring, and after a change
// that makes held connections invalid (a new CA, a rotated proxy).
client_pool_clear() {
    http_client_pool_clear_raw()
}

// How many idle connections are held right now.
client_pool_idle_count() -> int {
    return http_client_pool_idle_count_raw()
}

// How many response buffers the client has had to allocate from nothing,
// over the life of the process. A pooled connection keeps the buffer its
// last response was read into and lends it to the next, so a run of
// requests over one kept connection allocates once, not once per request
// -- which is what this lets a program, or a test, check rather than
// assume. Responses whose buffer grew past 64 KiB are not kept, so the idle
// pool cannot pin an outsized body.
client_rx_buffer_allocs() -> long {
    return http_client_rx_buffer_allocs_raw()
}

// GET a URL and return the response body. Most common case.
get(url: string) -> {
    response = http_get_raw(url)
    if response == null {
        return "", "out of memory"
    }
    err = http_response_error(response)
    if err != "" {
        err_copy = string_concat(err, "")
        http_response_free(response)
        return "", err_copy
    }
    status = http_response_status(response)
    if status < 200 {
        http_response_free(response)
        return "", "unexpected status"
    }
    if status >= 300 {
        http_response_free(response)
        return "", "http error"
    }
    body = http_response_body(response)
    body_copy = string_concat(body, "")
    http_response_free(response)
    return body_copy, ""
}

// GET a URL with a per-call timeout. Same return shape
// as `get`. Use this for any third-party URL — without it, a hung
// site stalls the calling actor's whole message handler. 0ns
// preserves `get`'s "block forever" default; values <1000 are rounded
// up to 1 second under the hood (the underlying socket-timeout field
// is integer seconds today).
get_with_timeout(url: string, timeout: Duration) -> {
    response = http_get_with_timeout_ns_raw(url, timeout)
    if response == null {
        return "", "out of memory"
    }
    err = http_response_error(response)
    if err != "" {
        err_copy = string_concat(err, "")
        http_response_free(response)
        return "", err_copy
    }
    status = http_response_status(response)
    if status < 200 {
        http_response_free(response)
        return "", "unexpected status"
    }
    if status >= 300 {
        http_response_free(response)
        return "", "http error"
    }
    body = http_response_body(response)
    body_copy = string_concat(body, "")
    http_response_free(response)
    return body_copy, ""
}

// POST a body and return the response body.
post(url: string, body: string, content_type: string) -> {
    response = http_post_raw(url, body, content_type)
    if response == null {
        return "", "out of memory"
    }
    err = http_response_error(response)
    if err != "" {
        err_copy = string_concat(err, "")
        http_response_free(response)
        return "", err_copy
    }
    status = http_response_status(response)
    if status < 200 {
        http_response_free(response)
        return "", "unexpected status"
    }
    if status >= 300 {
        http_response_free(response)
        return "", "http error"
    }
    result = http_response_body(response)
    result_copy = string_concat(result, "")
    http_response_free(response)
    return result_copy, ""
}

// PUT a body and return the response body.
put(url: string, body: string, content_type: string) -> {
    response = http_put_raw(url, body, content_type)
    if response == null {
        return "", "out of memory"
    }
    err = http_response_error(response)
    if err != "" {
        err_copy = string_concat(err, "")
        http_response_free(response)
        return "", err_copy
    }
    status = http_response_status(response)
    if status < 200 {
        http_response_free(response)
        return "", "unexpected status"
    }
    if status >= 300 {
        http_response_free(response)
        return "", "http error"
    }
    result = http_response_body(response)
    result_copy = string_concat(result, "")
    http_response_free(response)
    return result_copy, ""
}

// DELETE a URL and return the response body.
delete(url: string) -> {
    response = http_delete_raw(url)
    if response == null {
        return "", "out of memory"
    }
    err = http_response_error(response)
    if err != "" {
        err_copy = string_concat(err, "")
        http_response_free(response)
        return "", err_copy
    }
    status = http_response_status(response)
    if status < 200 {
        http_response_free(response)
        return "", "unexpected status"
    }
    if status >= 300 {
        http_response_free(response)
        return "", "http error"
    }
    result = http_response_body(response)
    result_copy = string_concat(result, "")
    http_response_free(response)
    return result_copy, ""
}

// HTTP Server - lifecycle
extern http_server_create(port: int) -> ptr
extern http_server_bind_raw(server: ptr, host: string, port: int) -> int
// Resolved listening port. After binding with port 0 (OS-assigned),
// returns the kernel-chosen port so dynamic-port users can discover it;
// otherwise echoes the requested port. 0 if unbound.
extern http_server_port(server: ptr) -> int
// Set the bind address before server_start. Default is "0.0.0.0"
// (all interfaces). Pass "127.0.0.1" to bind loopback only — useful
// for tests because macOS / Windows firewalls don't prompt on
// loopback binds. A host name binds the IPv4 address it resolves to,
// and one that does not resolve fails the bind (#2639).
extern http_server_set_host(server: ptr, host: string)
extern http_server_start_raw(server: ptr) -> int
extern http_server_start_background_raw(server: ptr) -> int
extern http_server_stop(server: ptr)
extern http_server_free(server: ptr)
// TLS termination (#260 Tier 0). Loads the cert+key (PEM-encoded);
// after this call every accepted connection completes a TLS handshake
// before the HTTP parse runs. Returns "" on success, error string
// otherwise. See server_set_tls below for the Aether-side wrapper.
extern http_server_set_tls_raw(server: ptr, cert_path: string, key_path: string) -> string

// Enable TLS termination on an HTTP server. Both paths must point at
// PEM-encoded files; the cert and key are validated to match before
// the server is marked TLS-enabled. Returns "" on success, an error
// string on failure (file unreadable, parse error, mismatched key,
// build without OpenSSL).
//
// Idempotent — calling twice with the same files is a no-op success;
// calling with different files re-loads.
//
// Example:
//     server = http.server_create(443)
//     err = http.server_set_tls(server, "/etc/ssl/cert.pem", "/etc/ssl/key.pem")
//     if err != "" { println("TLS setup failed: ${err}"); exit(1) }
//     http.server_start(server)
server_set_tls(server: ptr, cert_path: string, key_path: string) -> {
    return http_server_set_tls_raw(server, cert_path, key_path)
}

// HTTP/2 (#260 Tier 2). When enabled:
//   - the TLS context advertises "h2" via ALPN with "http/1.1" as
//     the fallback, so HTTP/2-capable clients (curl --http2,
//     browsers, fan-out gateways) negotiate the framed protocol
//     while older clients stay on HTTP/1.1 transparently;
//   - plain (non-TLS) connections honour h2c upgrade requests
//     per RFC 7540 §3.2 (Upgrade: h2c + HTTP2-Settings header);
//   - per-stream dispatch reuses the existing route table, so all
//     middleware / metrics / access logs / health probes / response
//     transformers (gzip, error_pages) apply uniformly across
//     HTTP/1.1 and HTTP/2 traffic.
//
// max_concurrent_streams advertises SETTINGS_MAX_CONCURRENT_STREAMS
// to the peer. Pass 0 for libnghttp2's default (100). Negative
// values return an error.
//
// Returns "" on success or an error string when the build doesn't
// link libnghttp2 (the rest of the server keeps working in
// HTTP/1.1-only mode).
//
// Example (h2 over TLS):
//     server = http.server_create(443)
//     err1 = http.server_set_tls(server, "cert.pem", "key.pem")
//     err2 = http.server_set_h2(server, 0)          // 0 = nghttp2 default
//     if err1 != "" { println("TLS: ${err1}"); exit(1) }
//     if err2 != "" { println("h2:  ${err2}"); exit(1) }
//     http.server_start(server)
extern http_server_set_h2_raw(server: ptr, max_concurrent_streams: int) -> string

server_set_h2(server: ptr, max_concurrent_streams: int) -> {
    return http_server_set_h2_raw(server, max_concurrent_streams)
}

// Per-stream concurrent dispatch for HTTP/2. When `worker_count`
// is greater than 0, each h2 connection spawns this many worker
// threads so multiple streams can run their handlers in parallel.
// Default 0 = sequential dispatch on the connection thread (legacy
// behaviour). Returns "" on success, error string otherwise.
//
//   workers   typical use
//   -------   --------------------------------------------------
//   0         keep handlers on the connection thread (default)
//   4         small fan-out — most servers
//   8–16      heavy fan-out — handler runs DB queries / large I/O
//   >16       diminishing returns; bound by the connection accept
//             queue and the number of physical cores
extern http_server_set_h2_concurrent_dispatch_raw(server: ptr, worker_count: int) -> string

server_set_h2_concurrent_dispatch(server: ptr, worker_count: int) -> {
    return http_server_set_h2_concurrent_dispatch_raw(server, worker_count)
}

// HTTP/1.1 keep-alive (#260 Tier 0). When enabled, the server reads
// multiple requests off one socket instead of closing after each.
//   max_requests = 0  -> unlimited per connection
//   idle_timeout = 0ns -> use the default 30s SO_RCVTIMEO
// Returns "" on success.
extern http_server_set_keepalive_raw(server: ptr, enabled: int, max_requests: int, idle_ns: long) -> string

server_set_keepalive(server: ptr, enabled: int, max_requests: int, idle_timeout: Duration) -> {
    return http_server_set_keepalive_raw(server, enabled, max_requests, idle_timeout.ns)
}

// Graceful shutdown (#260 Tier 3). Stops accepting new connections,
// then waits up to `timeout` for in-flight ones to finish naturally.
// Returns "" on clean drain, "timeout" if connections were still
// active when the deadline passed. Typically wired into a SIGTERM
// handler in the entry point.
extern http_server_shutdown_graceful_raw(server: ptr, timeout_ns: long) -> string

server_shutdown_graceful(server: ptr, timeout: Duration) -> {
    return http_server_shutdown_graceful_raw(server, timeout.ns)
}

// Lifecycle hooks (#260 Tier 3). on_start fires once after the listen
// socket is bound, before the accept loop runs (great place to log
// "ready" or flip a readiness probe). on_stop fires after the accept
// loop exits but before sockets close. Both pass the `user_data`
// pointer to the hook function. Hooks are C function pointers — declare
// them with @c_callback on the Aether side.
extern http_server_set_on_start(server: ptr, hook: ptr, user_data: ptr)
extern http_server_set_on_stop(server: ptr, hook: ptr, user_data: ptr)

server_on_start(server: ptr, hook: ptr, user_data: ptr) {
    http_server_set_on_start(server, hook, user_data)
}

server_on_stop(server: ptr, hook: ptr, user_data: ptr) {
    http_server_set_on_stop(server, hook, user_data)
}

// Health-probe endpoints (#260 Tier 3). Registers two routes:
//   live_path  — always 200 "ok" (process is up)
//   ready_path — calls ready_check (1 -> 200 "ready", 0 -> 503 "not ready")
// Either path may be "" to skip registration. ready_check may be null —
// in that case ready_path returns 200 too.
extern http_server_set_health_probes_raw(server: ptr,
    live_path: string,
    ready_path: string,
    ready_check: ptr,
    user_data: ptr) -> string

server_set_health_probes(server: ptr, live_path: string, ready_path: string,
    ready_check: ptr, user_data: ptr) -> {
    return http_server_set_health_probes_raw(server, live_path, ready_path,
        ready_check, user_data)
}

// Built-in access logger (#260 Tier 3 / F1). format: "combined" or
// "json". output_path: file path (opened with "ab" — appends),
// "-" for stderr, or "" to disable. Returns "" on success.
extern http_server_set_access_log_raw(server: ptr, format: string, output_path: string) -> string

server_set_access_log(server: ptr, format: string, output_path: string) -> {
    return http_server_set_access_log_raw(server, format, output_path)
}

// Built-in per-route metrics (#260 Tier 3 / F2). Tracks request
// counts, error rates, latency histograms; exposes the standard
// Prometheus text format on the configured endpoint (default
// "/metrics"). Returns "" on success.
extern http_server_set_metrics_raw(server: ptr, metrics_endpoint: string) -> string

server_set_metrics(server: ptr, metrics_endpoint: string) -> {
    return http_server_set_metrics_raw(server, metrics_endpoint)
}

// Server-Sent Events (#260 Tier 2). Register an SSE route — the
// handler owns the connection lifetime and pushes events directly
// to the client. The server sends `Content-Type: text/event-stream`
// + `Connection: close` automatically before invoking the handler.
//
// Handler signature (declared as @c_callback on the Aether side):
//     handler(req: ptr, sse: ptr, ud: ptr)
//
// Inside the handler, call sse_send / sse_send_id to push events,
// or sse_close to terminate explicitly. The connection closes
// when the handler returns.
extern http_server_sse(server: ptr, path: string, handler: @retain ptr, user_data: ptr)
extern http_sse_send_event(sse: ptr, event_name: string, data: string) -> int
extern http_sse_send_event_id(sse: ptr, event_name: string, data: string, id: string) -> int
extern http_sse_send_event_full(sse: ptr, event_name: string, data: string, id: string, retry_ms: int) -> int
extern http_response_sse_upgrade_raw(res: ptr) -> ptr
extern http_sse_close(sse: ptr)
extern http_sse_send_comment(sse: ptr, text: string) -> int

server_sse(server: ptr, path: string, handler: @keep ptr, user_data: ptr) {
    http_server_sse(server, path, handler, user_data)
}

sse_send(sse: ptr, event_name: string, data: string) -> int {
    return http_sse_send_event(sse, event_name, data)
}

sse_send_id(sse: ptr, event_name: string, data: string, id: string) -> int {
    return http_sse_send_event_id(sse, event_name, data, id)
}

// Full SSE event, including `retry:` -- the spec's own reconnection-backoff
// field (WHATWG HTML, server-sent events). Without it a client can only use
// its default backoff and the server has no way to say otherwise, so an SSE
// surface emitting id/event/data but not retry is incomplete rather than
// merely minimal. 5 of the 20 Datastar cross-SDK conformance goldens require
// it, which is how the gap surfaced.
//
// `retry_ms` <= 0 omits the field; sse_send and sse_send_id pass 0, so their
// behaviour is unchanged. Field order on the wire is id, event, retry, data --
// retry must precede the blank line that dispatches the event.
sse_send_full(sse: ptr, event_name: string, data: string, id: string, retry_ms: int) -> int {
    return http_sse_send_event_full(sse, event_name, data, id, retry_ms)
}

// Turn an in-flight ordinary response into an SSE stream.
//
// `server_sse` registers a whole ROUTE as SSE, which forces the decision
// before the request is parsed -- so a handler that must be able to answer 400
// on a malformed body and only THEN stream cannot use it. This is that seam.
//
// Unlike `response_accept_tunnel` this does NOT hand back a raw socket, so it
// works over TLS: writes go through the connection's own send path.
//
// Contract when the handler has already touched `res`: headers set earlier are
// DISCARDED (the SSE head is fixed, and a stale Content-Length would corrupt
// the stream), and if a body was already set the upgrade is REFUSED -- that
// body is data the caller believes it sent.
//
// Returns (sse, "") on success, (null, error) when the response is not on a
// live connection, has already been taken over, or has a body.
response_upgrade_sse(res: ptr) -> {
    if res == null { return null, "no response" }
    sse = http_response_sse_upgrade_raw(res)
    if sse == null {
        return null, "sse upgrade failed (no live connection, already taken over, or body already set)"
    }
    return sse, ""
}

sse_close(sse: ptr) {
    http_sse_close(sse)
}

// An SSE comment (`: text`), which clients ignore: a keep-alive that a proxy
// dropping idle connections sees as traffic (#3109). 0 when sent, -1 on a
// closed stream, a failed write or a text with a line break.
sse_comment(sse: ptr, text: string) -> int {
    return http_sse_send_comment(sse, text)
}

// A chunked response (#3109): stream a body whose length is not known in
// advance. response_begin_chunked sends the status and the headers the
// handler has set (a Content-Length dropped; Transfer-Encoding: chunked and
// Connection: close added) and takes the connection over, as
// response_upgrade_sse does, over TLS too. Then each chunked_write(stream,
// data) sends one chunk, and chunked_end(stream) ends the body. Returns
// (stream, "") or (null, error) when the response is not on a live
// connection, was already taken over, or has a body, or when the head
// could not be sent (the connection then closes). The stream is valid
// until the handler returns.
//
//     http.response_set_header(res, "Content-Type", "text/plain")
//     stream, err = http.response_begin_chunked(res)
//     if err == "" {
//         _ = http.chunked_write(stream, string.bytes("part one\n"))
//         _ = http.chunked_end(stream)
//     }
extern http_response_begin_chunked_raw(res: ptr) -> ptr
extern http_chunked_write(stream: ptr, data: ptr, length: int) -> int
extern http_chunked_end(stream: ptr) -> int

response_begin_chunked(res: ptr) -> {
    if res == null { return null, "no response" }
    stream = http_response_begin_chunked_raw(res)
    if stream == null {
        return null, "chunked response refused (no live connection, already taken over, a body already set, or the head not sent)"
    }
    return stream, ""
}

// One chunk holding the bytes of `data`; an empty slice sends nothing.
// 0 when sent, -1 on a closed stream or a failed write (the client left).
chunked_write(stream: ptr, data: byte[]) -> int {
    if data.len < 0 { panic("http.chunked_write: the `data` slice has no bound (.len -1); give it one, as `(p as byte[])[0..n]`") }
    return http_chunked_write(stream, data, data.len)
}

// The end of the body. 0 when sent, -1 as chunked_write.
chunked_end(stream: ptr) -> int {
    return http_chunked_end(stream)
}

// WebSocket (#260 Tier 2 / E2 — RFC 6455). The handler owns the
// connection lifetime — the server completes the upgrade handshake
// then hands control to the user.
//
// Handler signature (declared @c_callback on the Aether side):
//     handler(req: ptr, ws: ptr, ud: ptr)
//
// Inside the handler:
//   ws_recv(ws) -> (kind, data) where kind = 1 (text) / 2 (binary) /
//                 -1 (closed)
//   ws_send_text(ws, text) -> int (0 OK, -1 transport error)
//   ws_send_binary(ws, data) -> int        // data: byte[]
//   ws_close(ws, code, reason) — 1000 = normal, 1001 = going away, ...
//
// Control frames (ping/pong) are auto-handled inside ws_recv.
extern http_server_websocket(server: ptr, path: string, handler: @retain ptr, user_data: ptr)
extern http_ws_send_text(ws: ptr, text: string) -> int
extern http_ws_send_binary(ws: ptr, data: ptr, length: int) -> int
extern http_ws_recv(ws: ptr) -> int
extern http_ws_recv_timeout(ws: ptr, timeout_ms: int) -> int
extern http_ws_poll(ws: ptr, timeout_ms: int) -> int
extern http_ws_fd(ws: ptr) -> int
extern http_ws_message_data(ws: ptr) -> string
extern http_ws_message_length(ws: ptr) -> int
extern http_ws_close(ws: ptr, code: int, reason: string)
extern http_ws_connect(url: string) -> ptr
extern http_ws_client_free(ws: ptr)

server_websocket(server: ptr, path: string, handler: @keep ptr, user_data: ptr) {
    http_server_websocket(server, path, handler, user_data)
}

// WebSocket CLIENT: dial a ws:// endpoint and complete the upgrade.
//
// The returned handle takes the same verbs as a server-side one --
// ws_send_text / ws_recv / ws_message / ws_close -- because the frame codec
// underneath is shared. The only difference is invisible: RFC 6455 requires a
// client to mask every frame it sends, and this handle does.
//
// Returns null when the URL is malformed, the host is unreachable, the
// response is not 101, or the Sec-WebSocket-Accept hash does not match the
// key we sent. That last check matters: without it any 101 would be accepted,
// including from a server that never saw our handshake.
//
// wss:// dials over TLS, reusing the HTTP client's trust store, so the same
// system CA discovery and TLS floor apply as for https. The peer certificate
// is verified AND pinned to the host in the URL; a cert with a valid chain
// but the wrong host is refused. Default port follows the scheme: 80 for ws,
// 443 for wss.
//
// Free with ws_client_free (NOT for server-side handles, which the request
// loop owns).
ws_connect(url: string) -> ptr {
    return http_ws_connect(url)
}

ws_client_free(ws: ptr) {
    http_ws_client_free(ws)
}

ws_send_text(ws: ptr, text: string) -> int {
    return http_ws_send_text(ws, text)
}

// The bytes behind a string (std.string): bounds a borrowed buffer the
// server hands back typed `string` by the length C reports for it.
extern aether_string_raw_ptr(s: ptr) -> ptr

// Send one binary frame holding the bytes of `data` (#2301: a byte[] whose
// length travels with it). Returns the send result, -1 on a closed socket.
ws_send_binary(ws: ptr, data: byte[]) -> int {
    if data.len < 0 { panic("http.ws_send_binary: the `data` slice has no bound (.len -1); give it one, as `(p as byte[])[0..n]`") }
    return http_ws_send_binary(ws, data, data.len)
}

// Returns: 1 = text frame, 2 = binary, -1 = closed.
// After 1 or 2, the message is accessible via ws_message (text) and
// ws_message_bytes (a binary-safe byte[] view). Both are valid until the
// next ws_recv / ws_send / ws_close call.
ws_recv(ws: ptr) -> int {
    return http_ws_recv(ws)
}

// Bounded receive, for a reader that multiplexes many logical streams over
// one socket and so cannot park a thread in a blocking ws_recv. A
// WebDriver-BiDi demux is the motivating shape: one reader routes each frame
// to either an id-keyed pending-reply table or an event queue, and the caller
// drives the wait with its own event loop.
//
// Returns 1 (text), 2 (binary), -1 (closed) exactly as ws_recv, plus 0 for
// "nothing arrived in time". timeout_ms of 0 polls; negative blocks.
//
// The timeout bounds the wait for the START of a frame. Once a frame header
// has been read the rest of that frame is read to completion, because
// WebSocket framing is a byte stream with no resynchronisation point --
// abandoning a half-read frame would leave the next read treating payload as
// a header. Pings and continuation frames handled during the wait do not
// restart the clock, so a chatty peer cannot extend the call indefinitely.
ws_recv_timeout(ws: ptr, timeout_ms: int) -> int {
    return http_ws_recv_timeout(ws, timeout_ms)
}

// Is a frame readable without blocking? 1 = yes, 0 = timed out,
// -1 = closed/error. Consumes nothing, so a 1 is always followed by a
// ws_recv that does not block.
//
// This asks all three places bytes can be waiting -- the connection's read
// buffer, the TLS layer's decrypted-but-unread payload, and the socket -- so
// unlike polling ws_fd yourself it cannot answer "not ready" while a complete
// frame is already buffered above the socket.
ws_poll(ws: ptr, timeout_ms: int) -> int {
    return http_ws_poll(ws, timeout_ms)
}

// The underlying socket, for a native event loop (asyncio.add_reader, epoll,
// kqueue). Returns -1 when closed.
//
// CONTRACT -- read this before using it. The descriptor is a readiness HINT,
// not an authority: a frame can sit in the connection buffer, or decrypted
// inside the TLS layer, with nothing pending on the socket. An event loop
// that waits on this fd alone will eventually miss a frame that has already
// arrived, and then block. The safe pattern is:
//
//   when your event loop reports the fd readable, drain it dry:
//
//     draining = 1
//     while draining == 1 {
//         k = http.ws_recv_timeout(ws, 0)   // never blocks
//         if k == 0 { draining = 0 }        // nothing left; go back to waiting
//         if k > 0 { route(k) }
//         if k < 0 { draining = 0 }         // peer gone
//     }
//
// i.e. treat readability as "go look", and let ws_recv_timeout(ws, 0) be the
// authority on whether a frame is actually there. If you want one call that
// answers authoritatively, use ws_poll instead.
ws_fd(ws: ptr) -> int {
    return http_ws_fd(ws)
}

ws_message(ws: ptr) -> string {
    return http_ws_message_data(ws)
}

// The current message as a borrowed byte[] view (#2301): binary-safe, its
// length is the message length. Valid until the next ws_recv / ws_send /
// ws_close; copy it out (bytes.from_slice) to keep it.
ws_message_bytes(ws: ptr) -> byte[] {
    n = http_ws_message_length(ws)
    if n <= 0 { return null }
    return (aether_string_raw_ptr(http_ws_message_data(ws)) as byte[])[0..n]
}

ws_close(ws: ptr, code: int, reason: string) {
    http_ws_close(ws, code, reason)
}

// Drain a single accepted connection through the full HTTP lifecycle:
// optional TLS handshake, request parsing loop with keep-alive, route
// dispatch, response emission, socket close. This is the building
// block that user-side actor step functions plug into when running
// the server in actor-dispatch mode (set via
// http_server_set_actor_handler) — the actor's step receives a
// MSG_HTTP_CONNECTION with a client_fd and should call this helper
// to get the same TLS / keep-alive / route-dispatch behaviour the
// thread-pool worker path uses. (#260 Tier 0 / Phase C3.)
extern http_server_drain_connection(server: ptr, client_fd: int)

// Go-style wrappers for server lifecycle. Return "" on success, error
// string on failure.
server_bind(server: ptr, host: string, port: int) -> {
    rc = http_server_bind_raw(server, host, port)
    if rc < 0 {
        return "bind failed"
    }
    return ""
}

// Set the bind host before server_start. Default is "0.0.0.0".
// Pass "127.0.0.1" to bind loopback only, "::1" for IPv6 loopback, or "::"
// for every interface of both families (IPv4 clients arrive as IPv4 peers).
server_set_host(server: ptr, host: string) -> {
    http_server_set_host(server, host)
    return ""
}

server_start(server: ptr) -> {
    rc = http_server_start_raw(server)
    if rc < 0 {
        return "server start failed"
    }
    return ""
}

// Start a server on a detached native thread. Useful for integration
// tests and embedding hosts that need multiple local servers in one
// process without tying up the Aether actor scheduler.
server_start_background(server: ptr) -> {
    rc = http_server_start_background_raw(server)
    if rc < 0 {
        return "server background start failed"
    }
    return ""
}

// HTTP Server - routing.
//
// The `user_data` slot is plumbed end-to-end (the C side stores it on
// the route and passes it back as the 3rd arg of the registered
// handler). To carry a per-route context — a DB handle, a config
// struct, an auth scheme — declare a struct, `malloc`+init it, and
// pass the resulting `ptr` as `user_data`. The handler casts the
// `ud` arg back via `ud as *YourStruct`. Worked example at
// `tests/integration/http_handler_user_data/server.ae` and in
// `docs/http-handler-context.md`. (#633)
//
// The slot is per-route, so a server can host routes with distinct
// contexts without coordination. Passing `0` for `user_data`
// continues to work — opting in is purely additive.
extern http_server_add_route(server: ptr, method: string, path: string, handler: @retain ptr, user_data: ptr)
extern http_server_get(server: ptr, path: string, handler: @retain ptr, user_data: ptr)
extern http_server_post(server: ptr, path: string, handler: @retain ptr, user_data: ptr)
extern http_server_put(server: ptr, path: string, handler: @retain ptr, user_data: ptr)
extern http_server_delete(server: ptr, path: string, handler: @retain ptr, user_data: ptr)

// HTTP Server - middleware
extern http_server_use_middleware(server: ptr, middleware: ptr, user_data: ptr)

// HTTP Request - accessors
extern http_get_header(req: ptr, name: string) -> string
extern http_get_query_param(req: ptr, name: string) -> string
extern http_get_path_param(req: ptr, name: string) -> string
extern http_request_free(req: ptr)

// HTTP Response - building
extern http_response_create() -> ptr
extern http_response_set_status(res: ptr, code: int)
// The status the response will be sent with (200 until a handler sets one).
extern http_response_get_status(res: ptr) -> int
extern http_response_set_header(res: ptr, name: string, value: string)
// Append a header verbatim, even if a header with the same name already
// exists. Use for protocols that allow/require repeated headers — e.g.
// SVN's WebDAV uses 13+ `DAV:` headers per response. The replace-on-
// duplicate behaviour of `set_header` collapses these into the last
// value, breaking SVN clients. `add_header` preserves order and
// multiplicity through to the wire serializer.
extern http_response_add_header(res: ptr, name: string, value: string)
// Drop every header on the response, including the `Content-Type` and
// `Server` defaults injected by http_response_create. Used by VCR's
// dispatcher to reset to a blank slate before emitting the tape's
// recorded headers verbatim — record/replay must not have Aether's
// defaults overlaid on the captured response.
extern http_response_clear_headers(res: ptr)
extern http_response_set_body(res: ptr, body: string)
// Length-aware sibling — binary-safe set_body. Wrapped by
// response_set_body_bytes; `body` is `ptr` and this is not exported
// (#2301): the wrapper passes a byte[] slice's raw data pointer, and a heap
// string passed to a `ptr` parameter would send its header. std.net no
// longer declares it, so the two prototypes cannot disagree.
extern http_response_set_body_n(res: ptr, body: ptr, length: int)

// Set a binary-safe response body: the bytes of `body` (#2301: a byte[]
// whose length travels with it — a string as `string.bytes(s)`, a
// `std.bytes` buffer as `bytes.view(buf)`). The server copies it.
response_set_body_bytes(res: ptr, body: byte[]) {
    if body.len < 0 { panic("http.response_set_body_bytes: the `body` slice has no bound (.len -1); give it one, as `(p as byte[])[0..n]`") }
    http_response_set_body_n(res, body, body.len)
}
// Send the current HTTP response immediately and take ownership of
// the underlying cleartext HTTP/1.1 connection as a std.tcp socket.
// Returns null if the response is not attached to a live connection,
// the connection is TLS-wrapped, or the HTTP parser has buffered
// bytes that a raw socket could not replay. The returned socket is
// caller-owned and must be closed with tcp.close.
extern http_response_accept_tunnel(res: ptr) -> ptr
extern http_response_json(res: ptr, json: string)
extern http_server_response_free(res: ptr)

response_accept_tunnel(res: ptr) -> ptr {
    return http_response_accept_tunnel(res)
}

// HTTP Server - actor dispatch mode
extern http_server_set_actor_handler(server: ptr, step_fn: ptr, send_fn: ptr, spawn_fn: ptr, release_fn: ptr)

// HTTP Request - field accessors (for actor dispatch mode).
// Raw externs first; `http.request_*` wrappers below give callers
// the namespaced form so user code reads `http.request_path(req)`
// rather than the bare `http_request_path` raw symbol.
extern http_request_method(req: ptr) -> string
extern http_request_path(req: ptr) -> string
extern http_request_body(req: ptr) -> string
// Byte length of the request body — sibling of `http_request_body`.
// Returns 0 if the request has no body (or is null). Use this when
// the body may contain embedded NULs (binary uploads, gzipped JSON,
// svn PUT) — `string.length` on the body would `strlen` and truncate.
extern http_request_body_length(req: ptr) -> int
extern http_request_body_read_raw(req: ptr, offset: int, max: int) -> int
// #644: 1 once the whole body has arrived (streaming request: every
// declared byte pulled off the wire; buffered request: always 1 — the
// dispatcher had the payload before the handler ran). Lets a chunked-
// iteration loop detect "done" without comparing offsets against
// request_body_length.
extern http_request_body_complete(req: ptr) -> int
extern http_get_request_body_read() -> ptr
extern http_get_request_body_read_length() -> int
extern http_release_request_body_read()
extern string_new_with_length(data: ptr, length: long) -> string @heap
extern http_request_query(req: ptr) -> string

// Trusted TCP peer address — the IP `getpeername(2)` reports for the
// connection that carried this request. Use this (NOT the
// `X-Forwarded-For` header) when building an in-app source-IP
// allow/deny list on a directly-exposed listener: clients can put
// any value they like into the header, but only the kernel's
// notion of the peer reflects reality. Behind a trusted reverse
// proxy, `std.http.middleware.use_real_ip` remains the right tool.
// Returns "" when unavailable (Unix-domain socket, syscall failed,
// or req is null). Dotted-quad for IPv4 ("203.0.113.7"); the
// inet_ntop AF_INET6 form for IPv6 ("2001:db8::1") — no brackets,
// no scope id.
extern http_request_remote_addr(req: ptr) -> string

// Companion port — 0 when the address is unavailable too.
extern http_request_remote_port(req: ptr) -> int

// Server-side socket name from `getsockname(2)`. Needed when the
// listener binds 0.0.0.0 and the handler wants to know which NIC
// fielded this request (admin-on-loopback, multi-tenant per-IP
// routing). Same return semantics as the remote-* pair.
extern http_request_local_addr(req: ptr) -> string
extern http_request_local_port(req: ptr) -> int

// Transport scheme — "https" when this connection was TLS-wrapped
// at accept/handshake time, "http" otherwise. Source of truth is
// the local conn->ssl pointer, not anything in the wire bytes;
// drives canonical-URL building, redirect targets, and cookie
// Secure-flag decisions in app code. Behind a TLS-terminating
// proxy use the X-Forwarded-Proto middleware instead — the value
// here is what THIS server saw.
extern http_request_scheme(req: ptr) -> string
// Same flag as a 0/1 int — saves a string compare for callers
// that just need a bool.
extern http_request_is_tls(req: ptr) -> int

// HTTP version on the request line — "HTTP/1.0", "HTTP/1.1", or
// "HTTP/2.0". Surfaces a field the parser already captured.
extern http_request_http_version(req: ptr) -> string

// Request-header iteration. `http_get_header` only does a named lookup;
// these enumerate every received header so a handler can capture an
// unknown set (e.g. a faithful record/replay recorder). Order is wire
// order with duplicates preserved — no sort/dedup. Index range is
// [0, http_request_header_count); out-of-range returns "". Same 50-header
// cap as parsing.
extern http_request_header_count(req: ptr) -> int
extern http_request_header_name(req: ptr, index: int) -> string
extern http_request_header_value(req: ptr, index: int) -> string

// Go-style wrappers for the request field accessors.
request_method(req: ptr) -> string {
    return http_request_method(req)
}

request_path(req: ptr) -> string {
    return http_request_path(req)
}

request_body(req: ptr) -> string {
    return http_request_body(req)
}

request_body_length(req: ptr) -> int {
    return http_request_body_length(req)
}

// The request body as a borrowed byte[] view (#2301): binary-safe, bounded
// by the real body length. Like request_body it materialises a streaming
// body first. Valid for the handler's duration. request_body_length is kept
// separately: on a streaming request it reports the declared length
// WITHOUT materialising, which the chunked request_body_read loop relies on.
request_body_bytes(req: ptr) -> byte[] {
    p = aether_string_raw_ptr(http_request_body(req))
    n = http_request_body_length(req)
    if n <= 0 { return null }
    return (p as byte[])[0..n]
}

// Chunked-read access to the request body (#626). Reads up to `max`
// bytes from `offset` into an owned AetherString. Returns
// (bytes, n, "") on success — `n` may be less than `max` at EOF.
// Returns ("", 0, error) on failure.
//
// RAM-bounded for large uploads (#626). A body larger than the 16 KiB
// connection buffer is NOT buffered whole: the server parses headers,
// then this accessor pulls each window straight off the socket. Reads
// must be sequential (offset advances by the returned `n`, which the
// loop below does naturally). Small bodies stay fully buffered and
// support random-access offsets. Either way the loop below is
// identical — peak server memory for a large PUT is one window per
// connection, not the whole object.
//
// Pair with `request_body_length` to drive the loop:
//
//   total = http.request_body_length(req)
//   off = 0
//   while off < total {
//       chunk, n, err = http.request_body_read(req, off, 65536)
//       if err != "" { ...handle... break }
//       if n == 0 { break }
//       fs.pwrite(out_file, string.bytes(chunk)[0..n], off)   // stream to disk
//       off = off + n
//   }
request_body_read(req: ptr, offset: int, max: int) -> {
    ok = http_request_body_read_raw(req, offset, max)
    if ok == 0 {
        return "", 0, "request_body_read failed"
    }
    raw = http_get_request_body_read()
    n = http_get_request_body_read_length()
    owned = string_new_with_length(raw, n)
    http_release_request_body_read()
    return owned, n, ""
}

// #644: has the request body fully arrived? 1 once every declared byte
// has been received (streaming request: pulled off the wire by
// request_body_read / request_body; buffered request: always 1). The
// natural loop terminator for chunked iteration:
//
//   off = 0
//   while http.request_body_complete(req) == 0 {
//       chunk, n, err = http.request_body_read(req, off, 65536)
//       if err != "" { ...handle... break }
//       if n == 0 { break }
//       ...consume chunk...
//       off = off + n
//   }
request_body_complete(req: ptr) -> int {
    return http_request_body_complete(req)
}

request_query(req: ptr) -> string {
    return http_request_query(req)
}

request_remote_addr(req: ptr) -> string {
    return http_request_remote_addr(req)
}

request_remote_port(req: ptr) -> int {
    return http_request_remote_port(req)
}

request_local_addr(req: ptr) -> string {
    return http_request_local_addr(req)
}

request_local_port(req: ptr) -> int {
    return http_request_local_port(req)
}

request_scheme(req: ptr) -> string {
    return http_request_scheme(req)
}

request_is_tls(req: ptr) -> int {
    return http_request_is_tls(req)
}

request_http_version(req: ptr) -> string {
    return http_request_http_version(req)
}

request_header_count(req: ptr) -> int {
    return http_request_header_count(req)
}

request_header_name(req: ptr, index: int) -> string {
    return http_request_header_name(req, index)
}

request_header_value(req: ptr, index: int) -> string {
    return http_request_header_value(req, index)
}

// Static file serving — raw externs.
extern http_serve_static(req: ptr, res: ptr, base_dir: string)
extern http_serve_file(res: ptr, filepath: string)
extern http_mime_type(path: string) -> string

// Go-style wrappers for static file serving. Both return ""
// implicitly (the underlying externs populate res with status
// + headers + body / fd; failure paths set 4xx/5xx on res rather
// than returning an error string).
//
// Issue #383 zero-copy: serve_file stages the file via open+fstat
// when supported, lets the connection writer take the sendfile(2)
// fast path, and falls back to a buffered read for TLS / HTTP/2
// / Range requests / Windows. Callers see identical behaviour
// either way.
serve_file(res: ptr, filepath: string) {
    http_serve_file(res, filepath)
}

serve_static(req: ptr, res: ptr, base_dir: string) {
    http_serve_static(req, res, base_dir)
}

// Reactor-pattern async I/O. See std/net/module.ae for full docs.
// Suspends the current actor until fd is readable. On wake, the
// scheduler delivers `IoReady { fd: int, events: int }` to the
// actor's mailbox.
extern ae_io_await(fd: int) -> int
extern ae_io_cancel(fd: int)

await_io(fd: int) -> {
    rc = ae_io_await(fd)
    if rc < 0 {
        return "await_io failed"
    }
    return ""
}