Networking & HTTP Reference

Kyna provides native, high-performance networking through the global fetch() function and httpGet() helper. All network operations support HTTP/1.1 and HTTPS with configurable timeouts, headers, and request bodies.

---

The fetch() API

The fetch() function performs non-blocking HTTP requests:

const response = await fetch("https://api.kyna.dev/v1/metrics", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer token_secret_xyz"
    },
    body: jsonStringify({ service: "auth", status: "healthy" }),
    timeout: 5000
});

---

Fetch Options Configuration

Option	Type	Default	Description
method	str	"GET"	HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD)
headers	map	{}	Key-value pairs of request headers
body	str	""	Payload body string (e.g. JSON, form data, plain text)
timeout	int	10000	Request timeout duration in milliseconds

---

Response Object Model

A successful fetch() returns a Response object with the following properties and methods:

Field / Method	Type	Description
status	int	HTTP response status code (e.g., 200, 404, 500)
ok	bool	true if status is in the 200–299 range
headers	map	Response headers received from the server
text()	fn(): str	Returns the raw response body as a UTF-8 string
json()	fn(): any	Decodes the response body directly as JSON

---

Full Example: Authenticated API Client

async fn createDeployment(appName: str, version: str): bool {
    const endpoint = "https://api.kyna.dev/deployments";
    const apiKey = processEnv("KYNA_API_KEY");

    try {
        const res = await fetch(endpoint, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "Authorization": "Bearer " + apiKey
            },
            body: jsonStringify({ app: appName, tag: version }),
            timeout: 8000
        });

        if (res.ok) {
            const data = res.json();
            print("Deployment successful! ID:", data["id"]);
            return true;
        } else {
            print("Deployment failed with HTTP status:", res.status);
            return false;
        }
    } catch (err) {
        print("Network error [", err.code, "]:", err.message);
        return false;
    }
}

---

IP addresses

parseIP(text) returns a canonical IPv4 string, or null when the text is not a valid address. Use it for request tracking, allow-lists, and log fields.

print(parseIP("127.0.0.1"), parseIP("999.1.1.1"), parseIP("10.0.0.2"));
# "127.0.0.1"  null  "10.0.0.2"

---

Network Error Diagnostic Codes

Error Code	Category	Meaning
KNET1001	Argument Error	Invalid URL or missing parameter
KNET1002	Configuration Error	Unsupported HTTP method or invalid timeout format
KNET2001	Transport Error	Connection timeout, DNS failure, or TLS handshake error
KNET2100	Response Error	Attempted to call response methods on invalid object