XCX 3.0 JSON and HTTP

JSON

JSON objects in XCX 3.0 are mutable.

Creation

json: config <<< {"port": 8080, "debug": false} >>>;
json: user   <<< {"name": "", "age": 0} >>>;

Values in the literal can be placeholders ("", 0, false) to be filled later via .set().

Serialization from Collections

You can also create JSON objects and arrays directly from XCX collections using the .toJson() method. This is available for: - Maps: Returns a JSON object. - Tables: Returns a JSON array of objects.

See the Collections Documentation for more details on mapping and behavior.

Parsing

json: parsed = json.parse(raw_string);

[!CAUTION] Panic on Invalid JSON (R305): If parsing fails, the VM terminates immediately. Verify string content before parsing.

Mutability Pattern

Declare a schema with zero-values, then populate:

json: resp <<< {"token": "", "role": "", "uid": 0, "ok": false} >>>;
resp.set("token", crypto.token(32));
resp.set("role",  "admin");
resp.set("uid",   42);
resp.set("ok",    true);
yield net.respond(200, resp);

JSON Methods

[!NOTE] .push() on JSON arrays: .push() works exclusively on JSON nodes that are arrays ([]). Calling .push() on a JSON object ({}) results in a halt.error.

json: data <<< {"items": []} >>>;
json: obj <<< {"id": 1} >>>;
data.get("items").push(obj);   --- OK: "items" is an array
data.push(obj);                --- halt.error: data is an object, not an array

[!IMPORTANT] .bind() syntax: The second argument must be a previously declared variable. You cannot declare the type inline.

--- Wrong
req.bind("ip", s: ip);

--- Correct
s: ip;
req.bind("ip", ip);

Path Notation

Both dot-notation and bracket notation are supported for nested access:

--- Nested field
json: cfg <<< {"server": {"host": "localhost"}} >>>;
s: host;
cfg.bind("server.host", host);

--- Array index
json: resp <<< {"items": []} >>>;
resp.set("items[0]", first_item);
resp.set("items[1]", second_item);

.inject() — Bulk Import

Import a JSON array directly into an XCX table:

json: data <<< {"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]} >>>;
table: imported { columns=[uid::i, uname::s] rows=[EMPTY] };
map: mapping { schema=[s<->s] data=["uid"::"id", "uname"::"name"] };
data.inject("users", mapping, imported);
imported.show();

JSON in HTTP Requests

Inside HTTP handlers, json: req has this structure:

{
    "method":  "POST",
    "path":    "/api/login",
    "query":   { "page": "1" },
    "headers": { "authorization": "Bearer ..." },
    "body":    { ... },
    "ip":      "1.2.3.4"
}

s: ip;
req.bind("ip", ip);

json: body;
req.bind("body", body);

json: headers;
req.bind("headers", headers);

s: auth;
headers.bind("authorization", auth);

HTTP Client

High-Level API

json: resp = net.get("https://api.example.com/users");

json: body <<< {"name": "Alice"} >>>;
json: resp = net.post("https://api.example.com/users", body);

Response Object

{
    "status":  200,
    "ok":      true,
    "body":    { ... },
    "headers": { "content-type": "application/json" },
    "text":    "...",
    "error":   "..."
}

ok is true when status >= 200 and < 300. Always check ok before accessing body.

json: resp = net.get("https://api.example.com/data");
if (resp.ok) then;
    --- praca z resp.body
else;
    s: err;
    if (resp.exists("error")) then;
        resp.bind("error", err);
    end;
    >! "Error: " + s(resp.get("status")) + " | " + err;
end;

Low-Level Builder (net.request)

net.request {
    method  = "POST",
    url     = "https://api.example.com/data",
    headers = ["Authorization" :: "Bearer xyz", "X-App" :: "XCX"],
    body    = my_json,
    timeout = 5000
} as resp;

HTTP Server

serve Directive

serve: app {
    port    = 8080,
    host    = "0.0.0.0",
    workers = 4,
    routes  = [
        "POST   /api/login"     :: handle_login,
        "GET    /api/user"      :: handle_user,
        "DELETE /api/users"     :: handle_delete,
        "OPTIONS *"             :: handle_options,
        "*"                     :: handle_404
    ]
};

[!NOTE] serve: is a terminal statement. No code after this directive will execute. Wildcard * matches any method or path — always place it last.

Handler Fibers

Every handler must be a fiber with the signature fiber name(json: req -> json):

fiber handle_health(json: req -> json) {
    yield net.respond(200, <<< {"status": "ok"} >>>);
};

A handler that does not call yield net.respond(...) results in an automatic 500 Internal Server Error.

net.respond()

yield net.respond(200, my_json);
yield net.respond(201, my_json, ["Location" :: "/users/42"]);
yield net.respond(204, <<< {} >>>);
yield net.respond(404, <<< {"error": "not found"} >>>);

CORS and Preflight

By default, the XCX engine provides automatic CORS support by adding these headers if they are missing from the response: - Access-Control-Allow-Origin: * - Access-Control-Allow-Methods: GET, POST, OPTIONS, DELETE, PATCH - Access-Control-Allow-Headers: Content-Type, Authorization, X-CSRF-TOKEN

[!TIP] Recommended Practice: While the engine provides defaults, it is highly recommended to explicitly declare these headers in your code. This ensures your application remains predictable across different environments and clearly documents its security policy.

For preflight (OPTIONS) support, use a dedicated handler to explicitly set allowed methods and headers:

fiber handle_options(json: req -> json) {
    yield net.respond(204, <<< {} >>>, [
        {
            "Access-Control-Allow-Methods": "GET, POST, DELETE, PATCH, OPTIONS",
            "Access-Control-Allow-Headers": "Content-Type, Authorization, X-CSRF-TOKEN"
        }
    ]);
};

Concurrent Requests

Fibers allow overlapping I/O:

fiber fetch(s: url -> json) {
    yield net.get(url);
};

fiber:json: f1 = fetch("https://api.example.com/users");
fiber:json: f2 = fetch("https://api.example.com/posts");
json: r1 = f1.next();
json: r2 = f2.next();

Security Constraints