OmniFlux Network & HTTP Standard Library (stdlib/network.of)

The stdlib/network.of library provides a comprehensive set of procedural tasks for making outbound HTTP requests, sending structured HTTP responses, parsing request payloads and URL parameters, handling file uploads, and establishing real-time Server-Sent Events (SSE) streams.

1. Including the Library

To use network functions in your OmniFlux script, add the include directive at the top of your .of file:

include "stdlib/network.of"

2. HTTP Client Functions

networkget(url, headers = {}) (alias: network_get)

Performs an outbound HTTP GET request to the specified target URL. When the external server responds, if the response body is JSON, networkget automatically parses it into an object or array; otherwise, it returns the raw text response body.

include "stdlib/network.of"

on start {
    # Example A: Fetching a plain text response (GitHub's /zen endpoint returns a random engineering quote string)
    var zen = networkget("https://api.github.com/zen", { "User-Agent": "OmniFluxApp" })
    print("GitHub Zen: %s", zen)
    # Printed Output: GitHub Zen: Design for failure.  (or another random quote returned by GitHub)

    # Example B: Fetching a JSON API response (automatically parsed into an object)
    var user_data = networkget("https://api.github.com/users/octocat")
    print("User Name: %s, Company: %s", user_data.name, user_data.company)
    # Printed Output: User Name: The Octocat, Company: @github
}

networkpost(url, data, headers = {}) (alias: network_post)

Performs an HTTP POST request to the specified URL. Automatically sets Content-Type: application/json if data is an object.

include "stdlib/network.of"

on start {
    var res = networkpost("https://httpbin.org/post", { "user": "Maya", "role": "admin" })
    print("Posted User: %s, Role: %s", res.json.user, res.json.role)
    # Printed Output: Posted User: Maya, Role: admin
}

encodeurl(str) / decodeurl(str) (aliases: encode_url / decode_url)

URI encodes or decodes strings for safe inclusion in URLs.

on start {
    var encoded = encodeurl("hello world & omniflux")
    print("Encoded: %s", encoded)
    # Printed Output: Encoded: hello%20world%20%26%20omniflux
}

3. HTTP Server & Response Helpers

http_send_json(res, status = 200, data = null)

Sends a JSON response to the HTTP client with explicit status code and Content-Type: application/json; charset=utf-8.

GET "/api/status" (req, res) {
    http_send_json(res, 200, { "status": "ok", "uptime": 3600 })
    # Sent Client Response: HTTP Status 200 OK
    # Content-Type: application/json; charset=utf-8
    # Body: {"status":"ok","uptime":3600}
}

http_send_html(res, status = 200, html = "")

Sends an HTML fragment or document to the client with Content-Type: text/html; charset=utf-8.

GET "/welcome" (req, res) {
    http_send_html(res, 200, "<h1>Welcome to OmniFlux!</h1>")
    # Sent Client Response: HTTP Status 200 OK
    # Content-Type: text/html; charset=utf-8
    # Body: <h1>Welcome to OmniFlux!</h1>
}

http_redirect(res, target_url)

Redirects the client browser to target_url using HTTP 302 Found status.

GET "/old-dashboard" (req, res) {
    http_redirect(res, "/new-dashboard")
    # Sent Client Response: HTTP Status 302 Found
    # Location: /new-dashboard
}

4. Request Payload & Parameter Parsing

query_param(req, name)

Extracts a URL search parameter value by name from incoming GET/POST requests.

# Client Request: GET /user-info?id=tara&page=2
GET "/user-info" (req, res) {
    var user_id = query_param(req, "id")
    print("Extracted User ID: %s", user_id)
    # Printed Output: Extracted User ID: tara

    if user_id == null {
        http_send_json(res, 400, { "error": "Missing 'id' query parameter" })
        return
    }
    http_send_json(res, 200, { "id": user_id, "active": true })
}

http_read_body_json(req)

Asynchronously reads and parses a JSON payload from an incoming POST request req.

# Client Request: POST /api/items with JSON body: { "name": "Laptop", "price": 1200 }
POST "/api/items" (req, res) {
    var body = await http_read_body_json(req)
    print("New item name: %s, price: %d", body.name, body.price)
    # Printed Output: New item name: Laptop, price: 1200

    http_send_json(res, 201, { "created": true, "item": body.name })
}

uploadfile(req, dest_dir) (alias: upload_file)

Parses multipart/form-data requests, saving uploaded files to dest_dir with unique filenames.

POST "/upload" (req, res) {
    var ok = await uploadfile(req, scriptdir() + "/uploads")
    if ok {
        print("Uploaded original filename: %s", req.file.originalname)
        # Printed Output: Uploaded original filename: report.pdf

        http_send_json(res, 200, { "success": true, "files": req.files })
    } else {
        http_send_json(res, 500, { "error": "Upload failed" })
    }
}

5. Real-Time Streaming (SSE - Server-Sent Events)

sse_handle_connect(req, res)

Establishes a persistent Server-Sent Events (SSE) connection for real-time streaming (e.g., live LLM agent thinking steps, status updates).

GET "/agent/thinking-stream" (req, res) {
    sse_handle_connect(req, res)
    # Client receives stream headers. Broadcast messages via global.phoneClients.
}

6. Full Web & API Server Example

include "stdlib/network.of"

# 1. API Route with Query Parameters
# Incoming Request: GET /api/assistant-info?id=tara
GET "/api/assistant-info" (req, res) {
    var assistant_id = query_param(req, "id")
    if assistant_id == null {
        http_send_json(res, 400, { "error": "id parameter is required" })
        return
    }
    print("Fetching assistant info for ID: %s", assistant_id)
    # Printed Output: Fetching assistant info for ID: tara

    http_send_json(res, 200, { "id": assistant_id, "status": "online" })
}

# 2. POST API Route with Body Reader
# Incoming Request: POST /api/messages with Body: {"text": "Hello Maya!"}
POST "/api/messages" (req, res) {
    var payload = await http_read_body_json(req)
    print("Received message text: %s", payload.text)
    # Printed Output: Received message text: Hello Maya!

    http_send_json(res, 201, { "message": "Received", "data": payload })
}

# 3. Real-Time SSE Channel Route
GET "/agent/events" (req, res) {
    sse_handle_connect(req, res)
}

# 4. Redirect Route
# Incoming Request: GET /legacy-route
GET "/legacy-route" (req, res) {
    http_redirect(res, "/api/assistant-info?id=tara")
}