Runtime Internals

This page documents how hooks execute in Zeptoz today.

Execution pipeline

1. API triggers a hook event.
2. Hook manager resolves active bindings for the event and collection.
3. Input contract is built (event, record, auth, meta).
4. Runtime adapter executes hook (Rust or QuickJS for JS/TS).
5. Result is evaluated by lifecycle rules (before_* vs after_*).
6. Execution status and duration are logged.

Runtime adapters

• Rust hooks run via Rust runtime adapter.
• JavaScript/TypeScript hooks run in QuickJS.
• TypeScript/JavaScript are transpiled so export default function hook becomes globalThis.__zeptoz_hook in compiled artifact.

Timeouts and failure isolation

• Timeout controlled by ZEPTOZ_HOOK_TIMEOUT_MS (default 150).
• Hook runtime runs in a blocking task with timeout guard.
• On timeout, Zeptoz returns HOOK_RUNTIME_TIMEOUT for before_* hooks.
• For after_* hooks, timeout becomes warning metadata and main operation remains successful.

Guardrails

QuickJS source is blocked if it contains tokens like:

• require(
• import
• process.
• fs.
• child_process
• fetch(

Hook source/artifact paths are validated to stay within configured hooks root.

Observability

Hook execution emits runtime logs including:

• event
• runtime
• status (success, failure, timeout, panic)
• duration
• request correlation ID

Add hooks at runtime

You can add hooks while the server is running:

zeptoz hook add Task before_insert --lang ts --new normalize

What happens:

• hook source/artifact files are created (for JS/TS)
• hook_definitions and hook_bindings rows are inserted
• subsequent requests can resolve the new active binding

Remove/disable hooks at runtime (current state)

There is currently no dedicated zeptoz hook remove command.

Current options:

• disable binding in DB (hook_bindings.active = false)
• or disable definition in DB (hook_definitions.enabled = false)

Hook resolution filters by active/enabled flags, so disabled hooks are skipped on subsequent requests.

Dev-mode hot reload details

In zeptoz dev, watcher loop runs every 2 seconds and:

• detects hook file changes
• recompiles changed TS/JS hook sources to .compiled.js
• refreshes runtime snapshot counters
• validates OpenAPI build as part of runtime refresh