HTTP & Networking

Kodo provides built-in functions for making HTTP requests, running HTTP servers, and working with JSON. These builtins enable AI agents to build real web services and CLI tools without external dependencies.

HTTP Client

`http_get(url) -> Result<String, String>`

Performs an HTTP GET request. Returns Result::Ok(body) on success or Result::Err(message) on failure.

let result: Result<String, String> = http_get("http://httpbin.org/get")

`http_post(url, body) -> Result<String, String>`

Performs an HTTP POST request with a string body.

let result: Result<String, String> = http_post("http://httpbin.org/post", "hello")

Plain HTTP Only

In v1, HTTP builtins use plain HTTP (no TLS). If you need to reach an HTTPS endpoint, route through a local proxy or use a service that exposes an HTTP interface.

HTTP Server

Kodo includes a synchronous HTTP server powered by tiny_http. Servers and requests are managed via opaque Int handles.

`http_server_new(port) -> Int`

Creates a new HTTP server listening on the given port. Returns a handle, or 0 on failure.

let server: Int = http_server_new(8080)
if server == 0 {
    println("failed to create server")
}

`http_server_recv(server) -> Int`

Blocks until a request is received. Returns a request handle, or 0 on error.

let req: Int = http_server_recv(server)

`http_request_method(req) -> String`

Returns the HTTP method ("GET", "POST", etc.).

`http_request_path(req) -> String`

Returns the URL path (e.g., "/api/data").

`http_request_body(req) -> String`

Returns the request body as a string.

`http_respond(req, status, body)`

Sends an HTTP response with a status code and body. After calling this, the request handle is consumed and must not be reused.

http_respond(req, 200, "OK")

`http_server_free(server)`

Frees an HTTP server handle when done.

Complete Server Example

module http_api {
    meta {
        purpose: "HTTP server with JSON responses"
        version: "0.1.0"
    }

    fn main() -> Int {
        let server: Int = http_server_new(8080)
        if server == 0 {
            println("failed to create server")
            return 1
        }
        println("server listening on port 8080")

        let req: Int = http_server_recv(server)
        let method: String = http_request_method(req)
        let path: String = http_request_path(req)
        println(f"received {method} {path}")

        let body: Int = json_new_object()
        json_set_string(body, "status", "ok")
        let response: String = json_stringify(body)
        http_respond(req, 200, response)

        http_server_free(server)
        return 0
    }
}

JSON Parsing

Kodo represents parsed JSON as an opaque handle (an Int). You obtain a handle by parsing a JSON string, extract values from it by key, and free it when done.

`json_parse(str) -> Int`

Parses a JSON string and returns a handle. Returns 0 if parsing fails.

let handle: Int = json_parse("{\"count\": 42}")

`json_get_int(handle, key) -> Int`

Extracts an integer value by key. Returns 0 if the key does not exist.

`json_get_string(handle, key) -> String`

Extracts a string value by key.

`json_free(handle)`

Frees the memory associated with a parsed JSON handle. Passing 0 is safe.

JSON Builder

Build JSON objects programmatically without string manipulation.

`json_new_object() -> Int`

Creates a new empty JSON object and returns a handle.

let obj: Int = json_new_object()

`json_set_string(handle, key, value)`

Sets a string field on the JSON object.

`json_set_int(handle, key, value)`

Sets an integer field.

`json_set_bool(handle, key, value)`

Sets a boolean field.

`json_stringify(handle) -> String`

Serializes a JSON object to a string.

let obj: Int = json_new_object()
json_set_string(obj, "name", "kodo")
json_set_int(obj, "version", 1)
json_set_bool(obj, "stable", false)
let output: String = json_stringify(obj)
println(output)  // {"name":"kodo","stable":false,"version":1}

Summary of Builtins

HTTP Client

Builtin	Parameters	Returns	Description
`http_get`	`url: String`	`Result<String, String>`	GET request
`http_post`	`url: String, body: String`	`Result<String, String>`	POST request

HTTP Server

Builtin	Parameters	Returns	Description
`http_server_new`	`port: Int`	`Int` (handle)	Create server
`http_server_recv`	`server: Int`	`Int` (request handle)	Block for request
`http_request_method`	`req: Int`	`String`	Get HTTP method
`http_request_path`	`req: Int`	`String`	Get URL path
`http_request_body`	`req: Int`	`String`	Get request body
`http_respond`	`req: Int, status: Int, body: String`	`()`	Send response
`http_server_free`	`server: Int`	`()`	Free server

JSON

Builtin	Parameters	Returns	Description
`json_parse`	`str: String`	`Int` (handle)	Parse JSON
`json_get_int`	`handle: Int, key: String`	`Int`	Extract integer
`json_get_string`	`handle: Int, key: String`	`String`	Extract string
`json_free`	`handle: Int`	`()`	Free JSON handle
`json_new_object`	—	`Int` (handle)	Create empty object
`json_set_string`	`handle: Int, key: String, value: String`	`()`	Set string field
`json_set_int`	`handle: Int, key: String, value: Int`	`()`	Set integer field
`json_set_bool`	`handle: Int, key: String, value: Bool`	`()`	Set boolean field
`json_stringify`	`handle: Int`	`String`	Serialize to string

Next Steps

Concurrency — spawning tasks and the cooperative scheduler
Actors — stateful actors with message passing
Modules and Imports — multi-file programs and the standard library