How It Works
The Handler Pattern
Every function's index.ts has a default export that takes a Request and returns a Response:
export default async (req: Request): Promise<Response> => {
const { args } = await req.json();
return Response.json({ data: { message: "Hello, " + args.name } });
};
A plain object or value returned instead of a Response is sent as JSON. A file
with no default export, or one whose default export is not a function, is refused
at deploy. A handler that throws answers 500 {"error":"internal error"}; the
error's message goes to the function's logs, never to the caller. To refuse a
caller with a message, return the status yourself:
export default async (req: Request): Promise<Response> => {
if (!req.headers.get("authorization")) {
return Response.json({ error: "sign in first" }, { status: 401 });
}
return Response.json({ data: "ok" });
};
Web Worker Isolation
Each deployed function runs in its own Deno Web Worker. Workers are:
- Memory-isolated — one function cannot access another's state
- Permission-restricted —
netto allowlisted hosts only,envreads your secrets; no filesystem, no subprocess - Long-lived — the Worker stays in memory after deploy for fast warm invocations
- Terminable — delete a function and the Worker is terminated immediately
Deno Runtime Pod
├─ Main thread (HTTP server, routing)
├─ Worker: hello ← isolated
├─ Worker: process-data ← isolated
└─ Worker: notify-slack ← isolated
Permissions
| Permission | Allowed | Why |
|---|---|---|
net | Allowlisted hosts | Your project's outbound allowlist plus its own API host |
env | Your secrets | Deno.env.get reads the project's secrets and the values below, never the runtime's own environment |
read | No | No filesystem access |
write | No | No filesystem writes |
run | No | Cannot spawn subprocesses |
ffi | No | No foreign function interface |
Outbound network
A new project's functions can reach no other host. Add the hosts a function
calls to the project's outbound allowlist (host or host:port; a bare host
means port 443, *.example.com covers subdomains). $TOKEN is a personal
access token with the write scope:
curl -X PUT https://app.excalibase.io/api/projects/$PROJECT_ID/functions/egress \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"allowedHosts": ["api.stripe.com", "hooks.slack.com"]}'
The allowlist belongs to the project, not to one function: all of a project's functions share one runtime, so a host added for one function is reachable from every function in that project. It is enforced twice, by the function sandbox and by the runtime's network policy, which admits only the listed host names on their ports.
Your project's own API host (api.excalibase.io) is always reachable, so a
function can call its project's REST and GraphQL API and its sibling functions.
So is your project's own database, at the address in EXCALIBASE_DB_URL.
Private and internal addresses (other projects, the platform, cloud metadata)
are never reachable, whatever the allowlist says.
Environment
Deno.env.get(name) reads the project's function secrets (Studio, or the
set_function_secret MCP tool) and these values the platform sets:
| Variable | Value |
|---|---|
EXCALIBASE_URL | Your project's functions base URL, for calling sibling functions |
EXCALIBASE_PROJECT_ID | The project id |
EXCALIBASE_ORG_SLUG | The owning organization's slug |
EXCALIBASE_DB_URL | A connection string for the project's database, as your own role: postgres://…?sslmode=require on a Postgres project, mysql://…/<database>?ssl-mode=VERIFY_IDENTITY on a MySQL project |
EXCALIBASE_DB_CA_CERT | MySQL projects only: the server's CA certificate (PEM), which a client of EXCALIBASE_DB_URL verifies the server with |
No API key is set for you. To call your project's API from a function, create a secret key (Studio, API keys), store it as a function secret, and send it like any other client:
const key = Deno.env.get("EXCALIBASE_SECRET_KEY");
Timeouts
Default timeout is 30 seconds. If a function exceeds the timeout, the invocation fails with an error but the Worker stays alive for future calls.
{
"error": "Execution timeout (30s)"
}
Deploy Lifecycle
- POST /deploy — server receives code, creates a Web Worker
- Worker compiles, checks the default export, and sends a
readysignal (10-50ms). A module that does not load or has no default handler is refused with400, and a version already deployed under that id keeps answering - Worker stays in memory, ready for invocations
- Each POST /invoke/{id} sends a message to the Worker, Worker returns result (1-5ms)
- DELETE /delete/{id} — Worker is terminated, memory freed
Provisioning Hooks
When used with the K8s Provisioning service, functions can act as lifecycle hooks:
| Hook | When | Context available |
|---|---|---|
pre-provision | Before pipeline | projectId, tier, databaseType |
post-provision | After ACTIVE | Above + credentials (host, port, password) |
pre-backup | Before backup | projectId |
post-backup | After backup | projectId, backupId |
pre-deprovision | Before delete | projectId |
post-deprovision | After cleanup | projectId |
Example post-provision hook:
export default async (req: Request): Promise<Response> => {
const ctx = await req.json();
// Notify Slack
await fetch("https://hooks.slack.com/services/...", {
method: "POST",
body: JSON.stringify({ text: `DB ${ctx.projectId} is ready!` })
});
return Response.json({ notified: true });
};
Hook failures are non-blocking — the provisioning pipeline always completes regardless.