Writing modules
A module is a WebAssembly component. What it exports decides what it can do, and it needs one or both of these:
| Export | What it gives the package |
|---|---|
wasi:http/incoming-handler |
A URL. It handles HTTP requests on its module host and at /run/... |
An interface named after the package, such as acme:weather/api |
Functions other packages can import. See Calling other packages |
A module can export both. The registry checks the exports when you publish, and rejects a component with none of them, or with a known export of the wrong type.
HTTP handlers
A handler implements the standard wasi:http/proxy world, so anything that targets it works. It receives every request to its package:
- On its module host,
https://{ns}--{name}.codetje.app/any/path, it sees the path as is (/any/path). - At
https://run.codetje.app/run/{ns}/{name}/any/path, it also sees/any/path, and the runner adds anx-forwarded-prefix: /run/{ns}/{name}header, so pages can build links that work in both places.
The runner removes the Authorization header before your module sees it. A module on its own module host keeps its own cookies, since each package has its own origin.
Responses can stream: the runner passes the body on as your module writes it, until the request's time runs out.
The manifest
A module can say what it needs in a manifest: JSON in a custom section of the component named codetje:manifest. The console shows it on the version's page.
{
"env": [{ "name": "API_KEY", "required": true }],
"fetch": ["https://api.example.com"]
}
envlists variable names, never values.fetchlists the origins the module calls.
With the AssemblyScript SDK, put it in assembly/manifest.json and the build embeds it. With any other toolchain, rt publish --manifest manifest.json adds it. Since it's part of the component, it's covered by the version's digest and can't change later. The registry rejects a malformed manifest when you publish. The manifest is a description: your settings decide what the module actually gets.
The sandbox
Every request gets a new instance of the module, and it's thrown away afterwards. So nothing survives from one request to the next: there's no file system, and no database or key-value store yet. Keep state in a service you call over HTTP.
What a module can use:
- The environment: only the variables in its package's settings. It's empty otherwise.
- Outgoing HTTP, through
wasi:http, to the origins in its settings, at public addresses only. Anything else fails withhttp-request-denied. - Clocks and random numbers, from WASI.
- stdout and stderr, which become the package's logs.
What it can't use: files, sockets, DNS, or any process outside the request.
Each request has limits on memory, CPU and time. See Limits.
Logs and errors
Whatever a module prints goes to its package's log stream, which you can watch in the console's run panel. When a module traps (a panic, an abort, running out of memory or fuel), the request gets a 500 and the reason goes to the log as a runner line. A request that runs out of time gets a 504.