Script (Rhai)

Runs Rhai scripts to transform, filter, enrich, and route events. The script receives the event as the event variable, and a ctx object exposing the distributed cache, mutable metadata, and resource loading. The script’s return value becomes the next event’s data.

Rhai is a sandboxed, embedded scripting language: it cannot perform IO, spawn processes, or access the host filesystem except through what flowgen explicitly exposes (ctx.cache, ctx.resource, the built-in helpers).

Configuration

- script:
    name: transform
    code: |
      let data = event.data;
      #{
        id: data.id,
        name: data.name,
        processed_at: timestamp_to_iso(timestamp_now())
      }

Fields

limits

What the script sees

Two top-level variables:

event (read-only)

ctx.meta (mutable)

ctx.meta is a copy of event.meta that the script can mutate. Any changes are preserved on the emitted event:

ctx.meta.batch_id = uuid();
ctx.meta.processed = true;
event.data

The next task in the flow sees both the original meta keys and any keys the script set or overrode.

ctx.cache — distributed cache

Keys are automatically namespaced by the flow name, so two flows can use the same logical key without colliding.

ctx.resource — load files at script runtime

Loads content from the resource backend (filesystem or cache, see Resources). Useful when the resource key depends on the event:

let template_key = "templates/" + event.data.tenant + ".html";
let template = ctx.resource.get(template_key);
if template == () {
    throw "no template for tenant: " + event.data.tenant;
}
template

For static resources known at config time, prefer the task’s code: { resource: ... } field — it’s resolved once and supports templating.

Built-in helpers

Identifiers and hashes

Timestamps

All timestamps are Unix epoch in seconds unless noted.

Templating

let body = render("Hello {{name}}, your order #{{order_id}} is ready.", #{
    name: event.data.customer,
    order_id: event.data.id,
});
event.data.notification = body;
event.data

Return values

The script’s return value determines what the next task sees:

// Skip events that fail validation.
if event.data.amount < 0 {
    return ();
}
event.data

Examples

Set metadata:

- script:
    name: enrich
    code: |
      ctx.meta.batch_id = uuid();
      ctx.meta.received_at = timestamp_now();
      event.data

Deduplication with cache:

- script:
    name: dedup
    code: |
      let key = "seen." + event.data.id;
      if ctx.cache.get(key) != () {
          return ();   // Skip duplicate.
      }
      ctx.cache.put(key, "1", 86400);   // TTL 24 hours.
      event.data

Hive-partitioned partition key:

- script:
    name: route
    code: |
      let path = timestamp_to_hive_path(timestamp_now());
      ctx.meta.partition = path;
      event.data

Deterministic ID from composite fields:

- script:
    name: idempotency_key
    code: |
      let key = sha256(event.data.campaign_id + ":" + event.data.reference_id);
      ctx.meta.idempotency_key = key;
      event.data

Routing on error events:

- script:
    name: dlq_router
    code: |
      if event.error != () {
          ctx.meta.lane = "dlq";
      }
      event.data

Load code from a resource file:

- script:
    name: transform
    code:
      resource: scripts/transform.rhai

The file content is rendered as a Handlebars template against the event before execution — see Resources.

Logging

Rhai’s built-in print(value) and debug(value) route through flowgen’s tracing infrastructure. Output inherits the current span context (flow name, task name, task type), so messages are searchable alongside the rest of the worker logs.

print("Processing order: " + event.data.id);
debug(event.data);
event.data