bynk_emit/emitter/

wrangler.rs

//! `wrangler.toml` generation per Worker (v0.8 §4.4 / §4.5).
//!
//! Each context becomes a Cloudflare Worker with its own wrangler config.
//! Service Bindings are declared for every consumed context. Durable
//! Object bindings + migrations are declared for every agent.

use std::fmt::Write as _;

use crate::project::{UnitTable, worker_dir_name};

/// Compile-time pinned compatibility date. Cloudflare uses this to lock
/// Workers runtime behaviour. Bump cautiously when changing the runtime
/// dependencies.
const COMPATIBILITY_DATE: &str = "2024-11-01";

/// Events track, slice 0 (spine #936, ADR 0284): the class name of a
/// publishing context's fan-out Durable Object (`emitter::events_fanout`).
/// Shared with `emitter::workers` (the `Env` field name + `deps.
/// __eventsDispatch` call it drives) and `emitter::events_fanout` (the class
/// this name must actually export) so the three can never drift apart.
///
/// Double-underscore-prefixed, matching every other compiler-synthesised
/// identifier in emitted output (`__events`, `__eventsDispatch`,
/// `__makeLedger`, …) — a Bynk `agent` name can never start with `_` (a
/// parse error, checked directly: `agent _Foo { … }` fails with
/// `expected identifier after \`agent\`, found \`_\``), so an agent
/// coincidentally named the same as this synthetic class is structurally
/// impossible, not merely unlikely.
pub(crate) const EVENTS_FANOUT_CLASS_NAME: &str = "__EventsFanout";

/// Deploy-time sentinel in generated Worker configuration. The driver replaces
/// this with the persistent Cloudflare KV namespace id immediately before a
/// remote Wrangler command runs.
pub const KV_NAMESPACE_ID_PLACEHOLDER: &str = "<KV_NAMESPACE_ID>";

/// P6.x cutover slice 2 (#1191, narrowed from #1187): `crons`/`queues` arrive
/// pre-collected, sorted and deduped by the caller (`project.rs`'s own
/// `emit_wrangler_toml` call site) rather than being walked here off
/// `table.services`. Both used to match a handler's cron-schedule kind and a
/// service's queue-binding protocol directly, straight off the syntax tree —
/// this file's entire raw-syntax footprint, per #1191's own grounding.
/// `table` already only needs `agents`/`unit_table_uses_emit` (neither
/// syntax-typed from this file's perspective), so relocating just these two
/// matches removes `wrangler.rs` from the `ast_importers` probe outright — no
/// `bynk-emit::ir` equivalent exists to route through instead (#1191's
/// Framing: no project-wide `IrItem::Service` is built at the call site, and
/// `IrHandler::kind` reuses the syntax-tree handler kind unchanged even where
/// one is).
pub(crate) fn emit_wrangler_toml(
    context: &str,
    table: &UnitTable,
    consumes: &[String],
    // v0.19 (C1): this Worker's closure reaches bynk.cloudflare — declare the
    // KV namespace binding (the `id` is a deploy-time placeholder).
    needs_kv: bool,
    // v0.10a: every `on cron "expr"` schedule in the context, sorted+deduped.
    // Sorting is load-bearing, not cosmetic (review of #1192): the caller
    // walks `table.services`, a `HashMap`, so unsorted input makes
    // `wrangler.toml` non-reproducible across runs.
    crons: &[String],
    // v0.10b/v0.44: every `from queue("name")` service's bound queue name,
    // sorted+deduped (same reproducibility requirement as `crons`).
    queues: &[String],
    // #1187's slice 6 plumbing: `unit_table_uses_emit(table, callees)`,
    // precomputed by the caller — passing a bare `bool` rather than the
    // `Callee` map itself keeps this file's own hard-won zero `bynk_syntax::
    // ast` footprint (#1191) intact; the map's own element type would have
    // reintroduced exactly the literal spelling that slice removed.
    uses_emit: bool,
) -> String {
    let name = worker_dir_name(context);
    let mut out = String::new();
    let _ = writeln!(out, "# Generated by bynkc — do not edit by hand.");
    let _ = writeln!(out, "name = \"{name}\"");
    let _ = writeln!(out, "main = \"index.ts\"");
    let _ = writeln!(out, "compatibility_date = \"{COMPATIBILITY_DATE}\"");
    writeln!(out).unwrap();

    let mut sorted_consumes: Vec<&String> = consumes.iter().collect();
    sorted_consumes.sort();
    for target in &sorted_consumes {
        let binding = consumed_binding_name(target);
        let service = worker_dir_name(target);
        let _ = writeln!(out, "[[services]]");
        let _ = writeln!(out, "binding = \"{binding}\"");
        let _ = writeln!(out, "service = \"{service}\"");
        writeln!(out).unwrap();
    }

    if needs_kv {
        let _ = writeln!(out, "[[kv_namespaces]]");
        let _ = writeln!(
            out,
            "binding = \"{}\"",
            bynk_check::firstparty::KV_BINDING_NAME
        );
        let _ = writeln!(
            out,
            "id = \"{KV_NAMESPACE_ID_PLACEHOLDER}\" # set at deploy time"
        );
        writeln!(out).unwrap();
    }

    // Agents → Durable Object bindings + migrations. Events track, slice 0
    // (spine #936, ADR 0284): a context whose handlers emit gets its own
    // fan-out DO folded into the same bindings/migration blocks — Cloudflare
    // only cares that `index.ts` (this Worker's `main`) exports a class with
    // this name, not which generated file it came from.
    let mut class_names: Vec<String> = table.agents.keys().cloned().collect();
    if uses_emit {
        class_names.push(EVENTS_FANOUT_CLASS_NAME.to_string());
    }
    class_names.sort();
    for class_name in &class_names {
        let binding = agent_binding_name(class_name);
        let _ = writeln!(out, "[[durable_objects.bindings]]");
        let _ = writeln!(out, "name = \"{binding}\"");
        let _ = writeln!(out, "class_name = \"{class_name}\"");
        writeln!(out).unwrap();
    }
    if !class_names.is_empty() {
        let _ = writeln!(out, "[[migrations]]");
        let _ = writeln!(out, "tag = \"v1\"");
        let classes: Vec<String> = class_names.iter().map(|n| format!("\"{n}\"")).collect();
        let _ = writeln!(out, "new_classes = [{}]", classes.join(", "));
        writeln!(out).unwrap();
    }

    // v0.10a: cron triggers. Cloudflare uses a single `[triggers]` table with a
    // `crons` array aggregating every `on cron` schedule in the context.
    // Already sorted+deduped by the caller (#1191).
    if !crons.is_empty() {
        let quoted: Vec<String> = crons
            .iter()
            .map(|e| format!("\"{}\"", escape_toml_basic_string(e)))
            .collect();
        let _ = writeln!(out, "[triggers]");
        let _ = writeln!(out, "crons = [{}]", quoted.join(", "));
        writeln!(out).unwrap();
    }

    // v0.10b: queue consumers. Each `on queue "name"` becomes a
    // `[[queues.consumers]]` binding. Already sorted+deduped by the caller
    // (#1191).
    for name in queues {
        let _ = writeln!(out, "[[queues.consumers]]");
        let _ = writeln!(out, "queue = \"{}\"", escape_toml_basic_string(name));
        let _ = writeln!(out, "max_batch_size = 10");
        writeln!(out).unwrap();
    }

    out
}

/// Escape a source string literal for interpolation into a TOML *basic* string
/// (the `"…"` form). Queue names and cron expressions come from user string
/// literals, which can decode to contain `"`, `\`, newline and tab
/// (`bynk-syntax/src/lexer.rs`) — all of which would otherwise break out of the
/// TOML string and inject config keys. Every character we escape maps to a
/// valid TOML compact escape; remaining control characters fall back to the
/// `\uXXXX` form so the output is always a well-formed basic string.
fn escape_toml_basic_string(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '\\' => out.push_str("\\\\"),
            '"' => out.push_str("\\\""),
            '\n' => out.push_str("\\n"),
            '\t' => out.push_str("\\t"),
            '\r' => out.push_str("\\r"),
            // Control characters have no compact TOML escape besides the ones
            // above and must not appear raw in a basic string.
            c if (c as u32) < 0x20 || c == '\u{7f}' => {
                let _ = write!(out, "\\u{:04X}", c as u32);
            }
            c => out.push(c),
        }
    }
    out
}

/// Service Binding identifier for a consumed context: uppercase with
/// underscores. `commerce.payment` → `COMMERCE_PAYMENT`.
pub(crate) fn consumed_binding_name(target: &str) -> String {
    target.replace('.', "_").to_uppercase()
}

/// Durable Object binding identifier for an agent class. We use the
/// class name in screaming snake case so handlers can grab it by a
/// predictable name (`OrderEntity` → `ORDER_ENTITY`).
pub(crate) fn agent_binding_name(class_name: &str) -> String {
    let mut out = String::new();
    for (i, ch) in class_name.chars().enumerate() {
        if i > 0 && ch.is_uppercase() {
            out.push('_');
        }
        out.push(ch.to_ascii_uppercase());
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn escape_toml_basic_string_neutralises_injection() {
        // The trigger from the defect report: a queue name whose decoded value
        // carries a quote + newline would otherwise close the string and inject
        // a config key.
        assert_eq!(
            escape_toml_basic_string("q\nkey = \"injected"),
            "q\\nkey = \\\"injected"
        );
        assert_eq!(escape_toml_basic_string("a\\b"), "a\\\\b");
        assert_eq!(escape_toml_basic_string("a\tb"), "a\\tb");
    }

    #[test]
    fn escape_toml_basic_string_passes_plain_values_through() {
        // Ordinary cron expressions and queue names are untouched.
        assert_eq!(escape_toml_basic_string("*/5 * * * *"), "*/5 * * * *");
        assert_eq!(escape_toml_basic_string("order-events"), "order-events");
    }

    #[test]
    fn escape_toml_basic_string_escapes_other_control_chars() {
        // A NUL has no compact escape and must not appear raw in a basic string.
        assert_eq!(escape_toml_basic_string("a\u{0}b"), "a\\u0000b");
        assert_eq!(escape_toml_basic_string("a\u{7f}b"), "a\\u007Fb");
    }

    #[test]
    fn escaped_value_is_valid_toml_and_round_trips() {
        // The security invariant, enforced by a real TOML parser (not a golden
        // byte-compare): interpolating the escaped value produces a well-formed
        // single-key table whose decoded value is *exactly* the input — no
        // injected keys, no broken string. Covers the injection payload from the
        // defect report plus a control char that takes the `\uXXXX` fallback.
        for input in ["q\nkey = \"injected", "*/5 * * * *\\\"", "a\u{0}b\ttail"] {
            let doc = format!("queue = \"{}\"", escape_toml_basic_string(input));
            let table: toml::Table = doc
                .parse()
                .unwrap_or_else(|e| panic!("escaped {input:?} is invalid TOML: {e} ({doc:?})"));
            assert_eq!(
                table.len(),
                1,
                "escaped {input:?} injected extra keys: {table:?}"
            );
            assert_eq!(
                table["queue"].as_str(),
                Some(input),
                "escaped {input:?} did not round-trip"
            );
        }
    }
}