Skip to content
excalibase
how-it-works
Edge Functionsbeta

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 — net to allowlisted hosts only, env reads 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

PermissionAllowedWhy
netAllowlisted hostsYour project's outbound allowlist plus its own API host
envYour secretsDeno.env.get reads the project's secrets and the values below, never the runtime's own environment
readNoNo filesystem access
writeNoNo filesystem writes
runNoCannot spawn subprocesses
ffiNoNo 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:

VariableValue
EXCALIBASE_URLYour project's functions base URL, for calling sibling functions
EXCALIBASE_PROJECT_IDThe project id
EXCALIBASE_ORG_SLUGThe owning organization's slug
EXCALIBASE_DB_URLA 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_CERTMySQL 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

  1. POST /deploy — server receives code, creates a Web Worker
  2. Worker compiles, checks the default export, and sends a ready signal (10-50ms). A module that does not load or has no default handler is refused with 400, and a version already deployed under that id keeps answering
  3. Worker stays in memory, ready for invocations
  4. Each POST /invoke/{id} sends a message to the Worker, Worker returns result (1-5ms)
  5. DELETE /delete/{id} — Worker is terminated, memory freed

Provisioning Hooks

When used with the K8s Provisioning service, functions can act as lifecycle hooks:

HookWhenContext available
pre-provisionBefore pipelineprojectId, tier, databaseType
post-provisionAfter ACTIVEAbove + credentials (host, port, password)
pre-backupBefore backupprojectId
post-backupAfter backupprojectId, backupId
pre-deprovisionBefore deleteprojectId
post-deprovisionAfter cleanupprojectId

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.