Skip to content

Rhai

Conduit embeds the Rhai scripting language for rule policy — Rule Rhai, referenced from rules:. Scripts run on the request and response hooks against five host scope objects: txn, runtime, lookup, metrics, and log.

This section is the language-first reference for writing Rhai in Conduit. Feature behavior and YAML wiring are described in Policy & routing.

Host API architecture

Every hook invocation exposes five scopes. Each has a distinct mutability class:

Scope Role Reference
txn Per-query policy — pools, tags, drop/retry, egress, question/response reads Transaction API (txn)
runtime Read-only process state — runtime.routing() for health-aware routing Runtime API
lookup Read-only tables/views from data_sources: via lookup() / lookup_ip() Lookups
metrics Write-only user counters → conduit_user_* User metrics
log Script log lines via Conduit tracing Script logging

Start with Host API overview for the mental model and consistency rules.

What Rhai for rules does

Goal Config Primary API Status
Policy on a matching rule — pool, tags, drop, retry, egress, sampling rules: → type: rhai txn + shared scopes above Shipped
Health-aware pool/backend branching in scripts pools[].health + Rhai runtime.routing() Shipped

Rhai for rules does not edit DNS wire bytes (qname rewrite, response mutation, EDNS/EDE, RD-bit control). It also does not replace rules: request and response rules run on their hooks, and type: rhai is one action among the declarative ones.

Read in order

  1. Rule Rhai overview — when to use scripts, how they attach to rules, minimal example
  2. Host API overview — five scope objects
  3. Rhai policy — blocklist drop and CSV pool routing labs (request hook)
  4. Hooks and phases — request vs response hooks; slow-login and tag + dnstap pairing
  5. Transaction API (txn) — per-query policy methods and YAML equivalents
  6. Runtime API — runtime.routing() pool/backend health reads for policy branching

Behavioral context: Rules and actions, Backend health, Policy & routing.

Prerequisites