edge-functions.md

Edge Functions

Nubase Edge Functions provide Supabase-style function endpoints with Nubase Spring Boot as the public gateway:

POST /functions/v1/{functionName}
apikey: <project anon/authenticated/service_role key>
Authorization: Bearer <user jwt>

The Spring gateway resolves the project, validates the project key, applies verify_jwt, records invocation logs, and delegates execution to a configured provider.

Architecture

Client
  -> Nubase Spring /functions/v1/{name}
  -> EdgeFunctionExecutor
  -> local executor or Cloudflare private dispatcher
  -> user function

Function metadata lives in the metadata database, not in each project database. Tables include:

• edge_functions
• edge_function_versions
• edge_function_secrets
• edge_function_invocations

CLI Usage

Create a function:

nubase_cli functions new hello

Deploy it:

NUBASE_ALLOW_ADMIN_WRITE=true nubase_cli functions deploy hello

TypeScript entrypoints (index.ts) are bundled with esbuild automatically; pass --bundle to force bundling for plain-JS import graphs, or --no-bundle to upload the directory as-is (the server rejects uncompiled TypeScript with TYPESCRIPT_REQUIRES_BUNDLE):

NUBASE_ALLOW_ADMIN_WRITE=true nubase_cli functions deploy hello --bundle

Invoke it:

nubase_cli functions invoke hello --method POST --body '{"ok":true}'

Manage logs and secrets:

nubase_cli functions logs hello --limit 50
nubase_cli functions secrets list hello
NUBASE_ALLOW_ADMIN_WRITE=true nubase_cli functions secrets set hello API_KEY=value
NUBASE_ALLOW_ADMIN_WRITE=true nubase_cli functions delete hello

Admin APIs expose deployment state directly:

• GET /functions/admin/v1/functions/{slug} returns the active version.
• GET /functions/admin/v1/functions/{slug}/versions returns all deploy attempts, including failed versions.

Runtime Providers

Default local executor:

nubase:
  functions:
    executor:
      provider: local
      local:
        base-url: http://localhost:8787

Cloudflare dispatcher mode:

nubase:
  functions:
    executor:
        provider: cloudflare
      per-project-rpm: ${NUBASE_FUNCTIONS_PER_PROJECT_RPM:600}
      per-function-rpm: ${NUBASE_FUNCTIONS_PER_FUNCTION_RPM:120}
      invocation-log-retention-days: ${NUBASE_FUNCTIONS_INVOCATION_LOG_RETENTION_DAYS:30}
      cloudflare:
        account-id: ${CLOUDFLARE_ACCOUNT_ID}
        dispatch-namespace: ${CLOUDFLARE_WORKERS_DISPATCH_NAMESPACE}
        dispatcher-url: ${NUBASE_FUNCTIONS_CLOUDFLARE_DISPATCHER_URL}
        dispatcher-secret: ${NUBASE_FUNCTIONS_CLOUDFLARE_DISPATCHER_SECRET}

In this mode Nubase remains the public gateway. The Cloudflare dispatcher is private and receives signed requests from Nubase.

The dispatcher template lives in cloudflare/functions-dispatcher/. Deploy it with Wrangler after creating a Workers for Platforms dispatch namespace:

cd cloudflare/functions-dispatcher
cp wrangler.toml.example wrangler.toml
wrangler secret put NUBASE_DISPATCHER_SECRET
wrangler deploy

Set NUBASE_FUNCTIONS_CLOUDFLARE_DISPATCHER_URL to the deployed dispatcher URL and use the same NUBASE_DISPATCHER_SECRET value in NUBASE_FUNCTIONS_CLOUDFLARE_DISPATCHER_SECRET.

Security

• verify_jwt=true requires a valid user JWT or service-role caller.
• service_role is not injected into functions by default.
• Function secrets are encrypted in the metadata database.
• Cloudflare deployments inject function secrets as Worker secret_text bindings.
• Invocation logs store caller type and user id, but not raw Authorization or apikey values.
• Invocation rate limits are enforced per project and per function. Redis is used when configured, otherwise Nubase falls back to per-process Caffeine counters for single-node installs. Set NUBASE_FUNCTIONS_PER_PROJECT_RPM=0 or NUBASE_FUNCTIONS_PER_FUNCTION_RPM=0 to disable either limiter.
• Invocation logs are pruned by a scheduled retention job. Set NUBASE_FUNCTIONS_INVOCATION_LOG_RETENTION_DAYS=0 to disable pruning.

Current Limitations

• Default deploy uploads the function directory as-is, except TypeScript entrypoints which are esbuild-bundled automatically. Use --bundle for plain-JS import graphs that need resolving.
• Cloudflare Workers for Platforms script upload is handled synchronously. Nubase records each deploy attempt as a version and retries transient 429 and 5xx upload responses.
• Invocation log retention is implemented; table partitioning is not.