Guides

Functions

Deploy small pieces of server-side code that MUDBASE runs for you, on a schedule or in reaction to an event.

What a function is

A function is a JavaScript snippet stored against a project, paired with a trigger that decides when it runs: http, document, file, webhook, wallet, messaging, or cron. Each run is sandboxed, time-limited, and fully logged.

The execution sandbox

Your code runs inside an isolated worker with three things injected — nothing else:

export default async function handler(payload, context, env) {
  // payload  — the trigger's data (the changed document, the uploaded file, the request body...)
  // context  — { trigger, functionId, user, apiKey, timestamp, ... } describing the invocation
  // env      — the key/value pairs you set on the function's Environment tab

  const total = payload.items.reduce((sum, item) => sum + item.price, 0);
  return { total, currency: env.DEFAULT_CURRENCY || "USD" };
}

export default async function handler(payload, context, env) {
  // payload  — the trigger's data (the changed document, the uploaded file, the request body...)
  // context  — { trigger, functionId, user, apiKey, timestamp, ... } describing the invocation
  // env      — the key/value pairs you set on the function's Environment tab

  const total = payload.items.reduce((sum, item) => sum + item.price, 0);
  return { total, currency: env.DEFAULT_CURRENCY || "USD" };
}

Limits

• Timeout: 30 seconds per execution (configurable per function, up to your plan's ceiling)
• Max payload size: 1 MB
• Rate: 60 executions/minute and 1,000 executions/hour per function
• Last 100 executions are kept per function, visible from Console → Functions → Logs

Triggers

• http — invoked directly, like a normal API call
• document — a document is created, updated, or deleted in a specific collection
• file — a file is uploaded or deleted in a specific bucket
• webhook — an inbound webhook is received
• wallet — a monitored wallet sees a new tx or a balance change
• messaging — a message is sent or received
• cron — minutely, hourly, daily, weekly, or a custom 5-field expression

See Background Jobs for scheduling details and the retry policy.

Invoking and reading results back

Every invocation — including a manual test run from the Console — is fire-and-forget: the invoke call returns immediately with a queued execution, and the actual result (or error) shows up moments later in the execution log:

// 1. Invoke — returns immediately, doesn't wait for the function to finish
const invoke = await fetch(
  `https://api.mudbase.dev/api/projects/${projectId}/functions/${functionId}/execute`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": apiKey },
    body: JSON.stringify({ payload: { items: [{ price: 12 }, { price: 8 }] } }),
  }
);
const { data } = await invoke.json(); // { executionId, status: "queued" }

// 2. Poll the log for that execution's result
const logs = await fetch(
  `https://api.mudbase.dev/api/projects/${projectId}/functions/${functionId}/logs?limit=1`,
  { headers: { "X-API-Key": apiKey } }
);
const { data: recent } = await logs.json();

// 1. Invoke — returns immediately, doesn't wait for the function to finish
const invoke = await fetch(
  `https://api.mudbase.dev/api/projects/${projectId}/functions/${functionId}/execute`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": apiKey },
    body: JSON.stringify({ payload: { items: [{ price: 12 }, { price: 8 }] } }),
  }
);
const { data } = await invoke.json(); // { executionId, status: "queued" }

// 2. Poll the log for that execution's result
const logs = await fetch(
  `https://api.mudbase.dev/api/projects/${projectId}/functions/${functionId}/logs?limit=1`,
  { headers: { "X-API-Key": apiKey } }
);
const { data: recent } = await logs.json();

There is no synchronous request/response for any trigger type, including http — a function's return value is never sent back as the body of the call that invoked it. It's recorded on the execution's history entry (readable via the logs endpoint above) and used for the Console's run/error/duration stats and for invocation-based billing.