Codetje docs

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 an x-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"]
}
  • env lists variable names, never values.
  • fetch lists 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 with http-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.