Skip to content

Host Operations

sarr-io edited this page Sep 14, 2026 · 3 revisions

Host operations

Trusted package code loads the host API with:

local pa = require("pa")

Eval code does not receive pa. Expose authority through trusted package members that validate their byte protocols.

Filesystem

local package_fs <close> = pa.fs()
local bytes = package_fs:read("notes.txt")

local global_fs <close> = pa.fs("/srv/data")
global_fs:write("notes.txt", bytes)

pa.fs() returns a closeable capability rooted at the package source directory. A relative argument is resolved from that directory. An absolute argument is an explicit global root. :read(path) and :write(path, bytes) accept only relative paths beneath their opened root. The root itself must not be a symlink. Operation paths reject absolute paths, backslashes, . and .. components, NUL bytes, and symlink traversal. Writes replace files atomically and synchronously.

HTTP

local status, body = pa.http(
    "https://example.com",
    "GET",
    "/health",
    "",
    { ["accept"] = "application/json" }
)

The origin must contain only an HTTP or HTTPS scheme and authority. The request path must begin with one / and cannot change authority. Redirects are not followed. Bodies are strings and are rejected for methods that do not accept a body. Header names and values are validated; connection-level headers are forbidden.

Process

local code, stdout, stderr = pa.process(
    "/usr/bin/rg",
    { "--", "needle", "src" },
    ""
)

The executable must be an absolute path. Arguments must be a dense array of strings. Optional input, stdout, and stderr are byte strings. The call returns only for normal process exit.

Host calls are trusted authority. A package should fix roots, origins, executables, and methods in its own wrappers instead of accepting authority from generated code.

Clone this wiki locally