Repository navigation
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.
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.
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.
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.