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 + `exports` entries are declared for every agent.

use crate::emitter::toml_doc::{TomlBlock, TomlDocument, TomlEntry, TomlValue};
use crate::project::{UnitTable, worker_dir_name};

/// Compile-time pinned compatibility date. Cloudflare uses this to lock
/// Workers runtime behaviour. When to bump it, and the gate a bump must pass,
/// is the policy in `design/bynk-release-discipline.md` ("Part 3 — The Workers
/// compatibility date", #1677): reviewed at each release, and moved only after
/// the workerd smokes pass on the new date.
pub const COMPATIBILITY_DATE: &str = "2026-07-01";

/// #1732: the oldest wrangler whose bundled `workerd` serves
/// [`COMPATIBILITY_DATE`]. An older `workerd` refuses a newer date outright
/// (`wrangler dev` exits: "This Worker requires compatibility date …"), so
/// `bynk doctor` warns about a wrangler below this. Set by the same
/// compatibility-date review that sets the date (Part 3's lag rule keeps it at
/// least three months old). `bynk-emit/tests/compat_date_policy.rs` checks the
/// policy doc names both.
pub const WRANGLER_MIN: &str = "4.107.0";

/// 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_ir` equivalent exists to route through instead: nothing builds a
/// project-wide service IR at the call site (#1191's Framing), and after
/// #1542's Slice D2 nothing builds one anywhere.
///
/// P7.3 (#1303): builds a [`TomlDocument`] rather than writing text directly
/// — the caller (`project.rs`) prints it via `emitter::toml_doc::
/// print_toml_document`. What gets built, in what order, under what gates,
/// is unchanged; only the construction shape moved from direct `writeln!`
/// into pushing typed blocks. String-escaping moved with it: every value
/// below is escaped unconditionally by the printer now, not selectively by
/// this function (`emitter/toml_doc.rs`'s own module doc has the reasoning).
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,
) -> TomlDocument {
    let name = worker_dir_name(context);
    let mut doc = TomlDocument::new(
        "Generated by bynkc — do not edit by hand.",
        vec![
            TomlEntry::kv("name", TomlValue::str(name)),
            TomlEntry::kv("main", TomlValue::str("index.ts")),
            TomlEntry::kv("compatibility_date", TomlValue::str(COMPATIBILITY_DATE)),
        ],
    );

    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);
        doc.push_block(TomlBlock::array_table(
            "services",
            vec![
                TomlEntry::kv("binding", TomlValue::str(binding)),
                TomlEntry::kv("service", TomlValue::str(service)),
            ],
        ));
    }

    if needs_kv {
        doc.push_block(TomlBlock::array_table(
            "kv_namespaces",
            vec![
                TomlEntry::kv(
                    "binding",
                    TomlValue::str(bynk_check::firstparty::KV_BINDING_NAME),
                ),
                TomlEntry::with_comment(
                    "id",
                    TomlValue::str(KV_NAMESPACE_ID_PLACEHOLDER),
                    "set at deploy time",
                ),
            ],
        ));
    }

    // Agents → Durable Object bindings + exports. Events track, slice 0
    // (spine #936, ADR 0284): a context whose handlers emit gets its own
    // fan-out DO folded into the same bindings/exports 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);
        doc.push_block(TomlBlock::array_table(
            "durable_objects.bindings",
            vec![
                TomlEntry::kv("name", TomlValue::str(binding)),
                TomlEntry::kv("class_name", TomlValue::str(class_name.clone())),
            ],
        ));
    }
    // #1796: each class is declared in Cloudflare's declarative `exports`
    // map, not a `[[migrations]]` list. Migrations are picked by tag: Wrangler
    // uploads only the ones after the Worker's applied tag, so the single
    // fixed `v1` this used to emit registered the classes of the *first*
    // deploy and no class added after it (a new agent, or the fan-out class
    // arriving with a context's first `emit`). `exports` has no tag. On every
    // deploy Cloudflare compares the declared set with the Worker's
    // namespaces and creates what's missing, so the config stays a pure
    // function of the source and the ledger still records nothing (ADR 0194
    // D1's principle). Wrangler reads `exports` from 4.107.0, which is
    // [`WRANGLER_MIN`], and `wrangler dev` takes each class's backend from
    // it too.
    //
    // Every class is SQLite-backed (#1779, ADR 0438): the emitted agent uses
    // only `storage.get`/`storage.put` on its single `"state"` key, which a
    // SQLite-backed class supports unchanged, and the fan-out class uses no
    // storage at all. A Worker whose classes an older Bynk created
    // key-value-backed (`new_classes`, ≤ 0.309.10) is refused
    // (`storage_type_mismatch`, per Cloudflare's `exports` docs), because
    // Cloudflare can't change a backend in place. That is a documented
    // pre-1.0 break: such a Worker is torn down and redeployed. No
    // `deleted`/`renamed` tombstone is ever emitted — destroying or moving a
    // class's data is #539's decision. Per Cloudflare's docs, removing an
    // agent then fails the deploy (`orphaned_provisioned_namespace`), which
    // is the loud outcome wanted; that is not yet confirmed against a live
    // account (#1796).
    for class_name in &class_names {
        doc.push_block(TomlBlock::keyed_table(
            "exports",
            class_name.clone(),
            vec![
                TomlEntry::kv("type", TomlValue::str("durable-object")),
                TomlEntry::kv("storage", TomlValue::str("sqlite")),
            ],
        ));
    }

    // 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 = crons.iter().map(TomlValue::str).collect();
        doc.push_block(TomlBlock::table(
            "triggers",
            vec![TomlEntry::kv("crons", TomlValue::Array(quoted))],
        ));
    }

    // v0.10b: queue consumers. Each `on queue "name"` becomes a
    // `[[queues.consumers]]` binding. Already sorted+deduped by the caller
    // (#1191).
    for name in queues {
        doc.push_block(TomlBlock::array_table(
            "queues.consumers",
            vec![
                TomlEntry::kv("queue", TomlValue::str(name.clone())),
                TomlEntry::kv("max_batch_size", TomlValue::Int(10)),
            ],
        ));
    }

    doc
}

/// 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
}

// ---------------------------------------------------------------------------
// P7.4 (#1305): structural post-emission patches — closes R7.6 ("downstream
// consumers couple to nodes, never to emitted text") and R8.20 ("deploy-time
// placeholders are typed, not textual"). `bynk deploy`/`bynk dev --remote`
// and `--emit js` both need to rewrite one field of an *already-emitted*
// `wrangler.toml` after compilation — not build one from scratch (that's
// `emit_wrangler_toml`/`TomlDocument`, P7.3's own construction-side tree).
//
// This is the read-an-existing-document side, and needs a different tool
// than `TomlDocument`'s own from-scratch builder or a plain `toml::Table`
// parse: both discard everything they don't model (`toml::Table` round-trips
// through a `BTreeMap` with no comment/order trivia at all — a first attempt
// using it here silently dropped the "Generated by bynkc" banner and every
// inline comment, and re-sorted the whole document alphabetically, on every
// patch). `toml_edit::DocumentMut` is format-preserving: parse, mutate the
// one value that actually changed, re-serialise, and everything else survives
// byte-for-byte. That's the real shape "immune to a reformat, scoped to the
// actual field" needs — not just "found the right field," but "touched
// nothing else."
// ---------------------------------------------------------------------------

/// Set `item`'s value to `s`, preserving whatever leading/trailing
/// whitespace and comments already decorated it — e.g. the KV namespace
/// id's own `# set at deploy time` note survives materialisation (stale
/// once set, but that's the same text a caller would have seen under the
/// old substring-replace behaviour too; not this slice's concern to change).
fn set_string_preserving_decor(item: &mut toml_edit::Item, s: &str) {
    let decor = item
        .as_value()
        .map(|v| v.decor().clone())
        .unwrap_or_default();
    let mut new_value = toml_edit::Value::from(s);
    *new_value.decor_mut() = decor;
    *item = toml_edit::Item::Value(new_value);
}

/// Whether a generated `wrangler.toml`'s KV namespace id is still the
/// deploy-time placeholder — the same condition [`materialise_kv_namespace_id`]
/// itself checks internally before writing, exposed separately so a caller
/// can decide whether materialising is needed at all *before* doing the
/// (possibly fallible) work of finding the real id to substitute — e.g.
/// `bynk dev --remote` skipping a lock-file lookup entirely for a project
/// that either has no KV binding or is already materialised.
pub fn wrangler_needs_kv_materialisation(text: &str) -> Result<bool, String> {
    let doc: toml_edit::DocumentMut = text
        .parse()
        .map_err(|e| format!("invalid wrangler.toml: {e}"))?;
    Ok(current_kv_namespace_id(&doc) == Some(KV_NAMESPACE_ID_PLACEHOLDER))
}

/// Materialise the deploy-time KV namespace id placeholder in a generated
/// `wrangler.toml`'s text, structurally. Parses `text` and, if (and only
/// if) the first `[[kv_namespaces]]` entry's `id` is currently *exactly*
/// [`KV_NAMESPACE_ID_PLACEHOLDER`], replaces it with `id`.
///
/// Any other state — no `[[kv_namespaces]]` section at all, or an `id`
/// that's already been materialised to a real value — is a **no-op**,
/// returning `text` unchanged (byte-for-byte: the document is never
/// re-serialised in this branch, so there's nothing for a caller to
/// mistakenly treat as a real write). This mirrors the exact gate the old
/// `text.contains(KV_NAMESPACE_ID_PLACEHOLDER)` check enforced; it is not a
/// general "always overwrite with the given id" operation. Widening it into
/// a re-provisioning operation is a different feature, out of scope here
/// (#1305's own Decision B).
pub fn materialise_kv_namespace_id(text: &str, id: &str) -> Result<String, String> {
    let mut doc: toml_edit::DocumentMut = text
        .parse()
        .map_err(|e| format!("invalid wrangler.toml: {e}"))?;
    if current_kv_namespace_id(&doc) != Some(KV_NAMESPACE_ID_PLACEHOLDER) {
        return Ok(text.to_string());
    }
    let item = doc
        .get_mut("kv_namespaces")
        .and_then(|i| i.as_array_of_tables_mut())
        .and_then(|arr| arr.get_mut(0))
        .and_then(|t| t.get_mut("id"))
        .expect("current_kv_namespace_id returned Some, so this navigation cannot fail");
    set_string_preserving_decor(item, id);
    Ok(doc.to_string())
}

/// The first `[[kv_namespaces]]` entry's `id`, if the stanza exists at all.
fn current_kv_namespace_id(doc: &toml_edit::DocumentMut) -> Option<&str> {
    doc.get("kv_namespaces")?
        .as_array_of_tables()?
        .get(0)?
        .get("id")?
        .as_str()
}

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

    /// A full, realistic `wrangler.toml` — every stanza `emit_wrangler_toml`
    /// can produce, in its real order, with its real banner and inline
    /// comment (mirrors `bynkc/tests/fixtures/positive/
    /// 372_kv_agent_queue_workers/expected/workers/ops-hub/wrangler.toml`
    /// byte-for-byte). Review of #1305, finding 2: every test below asserts
    /// **exact** patched text against this fixture, not just "the changed
    /// field has the right value after a re-parse" — a re-parse is blind by
    /// construction to whatever the printer discarded, which is exactly how
    /// finding 1 (the whole-document alphabetical re-sort, dropped banner)
    /// survived a green suite the first time around.
    const REPRESENTATIVE: &str = "\
# Generated by bynkc — do not edit by hand.
name = \"ops-hub\"
main = \"index.ts\"
compatibility_date = \"2026-07-01\"

[[services]]
binding = \"PAYMENT\"
service = \"payment\"

[[kv_namespaces]]
binding = \"BYNK_KV\"
id = \"<KV_NAMESPACE_ID>\" # set at deploy time

[[durable_objects.bindings]]
name = \"JOB_LEDGER\"
class_name = \"JobLedger\"

[exports.JobLedger]
type = \"durable-object\"
storage = \"sqlite\"

[[queues.consumers]]
queue = \"job-intake\"
max_batch_size = 10
";

    #[test]
    fn materialise_kv_namespace_id_changes_only_the_id() {
        let expected = REPRESENTATIVE.replacen("<KV_NAMESPACE_ID>", "abc123", 1);
        assert_eq!(
            materialise_kv_namespace_id(REPRESENTATIVE, "abc123").unwrap(),
            expected
        );
        // The `# set at deploy time` note survives — the old text-replace
        // behaviour left it in place too (it only replaced the placeholder
        // substring, not the whole line), and this slice isn't the one
        // deciding whether that note should still be there post-materialisation.
        assert!(expected.contains("id = \"abc123\" # set at deploy time"));
    }

    #[test]
    fn materialise_kv_namespace_id_is_immune_to_reformatting() {
        let text = "[[kv_namespaces]]\nbinding = \"BYNK_KV\"\nid = \"<KV_NAMESPACE_ID>\" # set at deploy time\n";
        let patched = materialise_kv_namespace_id(text, "abc123").unwrap();
        assert_eq!(
            patched,
            "[[kv_namespaces]]\nbinding = \"BYNK_KV\"\nid = \"abc123\" # set at deploy time\n"
        );
    }

    #[test]
    fn materialise_kv_namespace_id_is_a_no_op_without_a_kv_namespaces_section() {
        let text = "name = \"api\"\nmain = \"index.ts\"\n";
        let patched = materialise_kv_namespace_id(text, "abc123").unwrap();
        assert_eq!(patched, text);
    }

    #[test]
    fn materialise_kv_namespace_id_is_a_no_op_once_already_materialised() {
        let text = "[[kv_namespaces]]\nbinding = \"BYNK_KV\"\nid = \"already-real\"\n";
        let patched = materialise_kv_namespace_id(text, "abc123").unwrap();
        assert_eq!(patched, text);
    }

    #[test]
    fn wrangler_needs_kv_materialisation_matches_materialise_kv_namespace_ids_own_gate() {
        let placeholder = "[[kv_namespaces]]\nid = \"<KV_NAMESPACE_ID>\"\n";
        assert!(wrangler_needs_kv_materialisation(placeholder).unwrap());

        let no_kv = "name = \"api\"\n";
        assert!(!wrangler_needs_kv_materialisation(no_kv).unwrap());

        let already_real = "[[kv_namespaces]]\nid = \"already-real\"\n";
        assert!(!wrangler_needs_kv_materialisation(already_real).unwrap());
    }

    #[test]
    fn wrangler_needs_kv_materialisation_rejects_invalid_toml() {
        assert!(wrangler_needs_kv_materialisation("not = valid = toml = at = all").is_err());
    }

    #[test]
    fn materialise_kv_namespace_id_rejects_invalid_toml() {
        assert!(materialise_kv_namespace_id("not = valid = toml = at = all", "abc123").is_err());
    }
}