Bun (the js runtime) is being vibe-ported from zig to rust

Zig → Rust porting guide

You are translating one Zig file to Rust. Read this whole document before writing any code. The goal of Phase A is a draft .rs next to the .zig that captures the logic faithfully — it does not need to compile. Phase B makes it compile crate-by-crate.

Ground rules

• Write the .rs in the same directory as the .zig, same basename. <area> is always the first path component under src/ (the crate root). If the .zig basename equals its immediate parent directory name (any depth), name it mod.rs; if it equals the top-level <area> dir, name it lib.rs. Examples: src/bake/DevServer/HmrSocket.zig → src/bake/DevServer/HmrSocket.rs; src/bake/DevServer/DevServer.zig → src/bake/DevServer/mod.rs; src/http/http.zig → src/http/lib.rs.
• Do not invent crate layouts. Cross-area types are referenced as bun_<area>::Type (see crate map below). Phase B wires the Cargo.toml.
• No tokio, rayon, hyper, async-trait, futures. No std::fs, std::net, std::process. Bun owns its event loop and syscalls. (Rust core/std slice, iter, mem, fmt, and core::ffi are fine — only the I/O-touching modules are banned.)
• No async fn. Everything is callbacks + state machines, same as the Zig.
• unsafe is fine when the Zig was already unsafe. Annotate every block with // SAFETY: <why> mirroring the Zig invariant.
• Leave // TODO(port): <reason> for anything you can't translate confidently. Don't guess. Flagging is better than wrong code.
• Leave // PERF(port): <zig idiom> — profile in Phase B wherever the Zig used a perf-specific idiom (appendAssumeCapacity, arena bulk-free, stack-fallback alloc, comptime monomorphization) and the port uses the plain idiomatic form. Phase A optimizes for correctness+idiom; Phase B greps PERF(port) and benchmarks.
• Match the Zig's structure. Same fn names (snake_case), same field order, same control flow. Phase B reviewers diff .zig ↔ .rs side-by-side. Acronyms collapse to one lowercase word: toAPI→to_api, isCSS→is_css, toUTF8→to_utf8, toJS→to_js, errorInCI→error_in_ci. Rule: a run of ≥2 uppercase letters is one segment. Exception — out-param constructors. fn foo(this: *@This(), ...) !void whose body assigns this.* = .{...} → fn foo(...) -> Result<Self, E>. Zig uses out-params because it lacks guaranteed NRVO for error unions; Rust does not. Diff readers should expect this reshape. If this is a pre-allocated slot in a pool/array (in-place init to avoid a move), keep &mut MaybeUninit<Self> and flag // TODO(port): in-place init. Exception — deinit. pub fn deinit becomes impl Drop, not an inherent method named deinit (see Idiom map).
• Borrow-checker reshaping is allowed. When matching Zig flow yields overlapping &mut, capture the needed scalar (.len(), index) into a local, drop the borrow, then re-borrow. Do NOT reach for raw pointers just to silence borrowck; leave // PORT NOTE: reshaped for borrowck so Phase B diff readers aren't confused.
• Prereq for every crate: #[global_allocator] static ALLOC: bun_alloc::Mimalloc = bun_alloc::Mimalloc; must be set at the binary root before any Box/Rc/Arc/Vec mapping in this guide is valid — otherwise you silently switch from mimalloc to glibc malloc. Phase B asserts this; Phase A can assume it.

Crate map

@import("bun").X → look up X here. @import("../<area>/file.zig") → bun_<area>::file::Thing.

If it's not in this table: the crate is bun_<top> where <top> is the first directory under src/ (verbatim — crash_handler → bun_crash_handler, bun_alloc stays bun_alloc, no double prefix). Intermediate directories become module path segments, snake_cased: src/bake/DevServer/Assets.zig → bun_bake::dev_server::Assets.

Type map

c_int, c_char, c_void come from core::ffi::* — they are not in the prelude.

Idiom map

Comptime reflection

@TypeOf(param) where param: anytype → drop it; name the generic <T> and use T directly. Zig needs @TypeOf because anytype is unnamed; in Rust the generic param IS the name. @TypeOf only needs special handling when fed into @typeInfo (true reflection) — see below.

@typeInfo(T) / @field(x, "name") have no Rust equivalent. Strategy:

• If used to iterate struct fields to implement equality/hash/clone/drop → #[derive(PartialEq, Eq, Hash, Clone)] (and Drop by hand). If iterating fields to implement a domain protocol (toCss, parse, toJS) → make the protocol a trait and impl it per type (a targeted #[derive(ToCss)] is fine, but the trait comes first). Only reach for a generic Fields reflection derive when the body truly needs field NAMES at runtime.
• if (@hasDecl(T, "foo")) T.foo(x) else @compileError(...) → drop the if; add trait bound T: Foo and call x.foo(). @hasDecl is Zig's structural duck-typing check — a trait bound IS that check. if (@hasDecl(T, "foo")) T.foo(x) else default_expr (optional behavior) → trait with a default method, or a blanket impl that the type can override. Never a runtime check.
• If used to inspect a fn signature (the host_fn pattern) → proc-macro attribute; leave // TODO(port): proc-macro.
• @field(x, comptime name) for intrusive lists → keep raw-ptr offset via core::mem::offset_of!(T, field) (stable since 1.77).

Strings

Data is bytes, not str. Do not use std::string::String / &str / .to_string() / String::from_utf8* for file paths, source code, HTTP bytes, module specifiers, env vars, or anything that came from a syscall or the network. These are &[u8] / Vec<u8> / Box<[u8]>. Bun handles WTF-8 and arbitrary bytes; inserting UTF-8 validation is both a perf tax and a correctness bug (rejects valid Linux paths, lone surrogates, etc.).

Only use &str/String for: (a) string literals you wrote, (b) the final hop into a Rust API that genuinely requires &str (rare — and use bstr::BStr::new(bytes) for Display/Debug instead of from_utf8_lossy). Never .unwrap() a from_utf8 on external data.

Shared/ref-counted strings stay shared. bun.String is the WTFString-backed shared buffer (crosses to JSC without copy). Keep it as bun_str::String — do not "simplify" to Arc<str> or String; you lose zero-copy JS interop and Latin-1/UTF-16 storage.

bun.String is a 5-variant tagged union over WTF-backed and Zig-slice-backed strings. In Rust:

// bun_str::String — #[repr(C)] struct { tag: u8, value: StringValue }
// NOT a Rust enum (C++ mutates tag and value independently across FFI).

• s.toUTF8(alloc) → s.to_utf8() returning bun_str::Utf8Slice<'_> (borrows if already UTF-8, else owns the transcoded buffer; Drop frees). No allocator param. This is encoding (WTF-16→UTF-8), not validation — output is bytes.
• s.toJS(global) → s.to_js(global) — only callable in *_jsc/runtime/jsc crates via the StringJsc extension trait. If your file is in a base crate and calls .toJS, leave // TODO(port): move to *_jsc.
• bun.String.borrowUTF8(slice) → bun_str::String::borrow_utf8(slice) (caller keeps slice alive — 'a lifetime on the borrow).
• ZigString → bun_str::ZigString (legacy; prefer bun_str::String).

[:0]const u8 → &ZStr:

pub struct ZStr<'a> { ptr: *const u8, len: usize, _p: PhantomData<&'a [u8]> }
// .as_bytes() / .as_ptr() / .as_cstr() — len does NOT include the NUL.

Construct from a buffer you just NUL-terminated: unsafe { ZStr::from_raw(buf.as_ptr(), len) } // SAFETY: buf[len] == 0 written above. For [:0]u16 use WStr::from_raw (&WStr) or WStr::from_raw_mut(buf.as_mut_ptr(), len) (&mut WStr). Same for ZStr::from_raw_mut.

Allocators

AST/parser crates keep arenas. Everything else uses the global allocator.

AST crates = js_parser, js_printer, css, bundler, bake, sourcemap, shell (parser), interchange, install/lockfile. These build large trees of small nodes bulk-freed at end-of-parse; arena allocation is load-bearing for throughput.

In AST crates:

• MimallocArena / std.heap.ArenaAllocator → bumpalo::Bump (re-exported as bun_alloc::Arena).
• std.mem.Allocator param (when callers in this file pass an arena) → bump: &'bump Bump. Thread it. The struct/fn gets a <'bump> lifetime. When callers pass bun.default_allocator → delete the param (global mimalloc).
• std.ArrayList(T) / ArrayListUnmanaged(T) fed an arena → bumpalo::collections::Vec<'bump, T>. .append(a, x) → v.push(x) (arena bound at construction, not per-call).
• allocator.create(T) (arena) → bump.alloc(init) returns &'bump mut T. allocator.dupe(u8, s) → bump.alloc_slice_copy(s) returns &'bump [u8].
• arena.reset() → bump.reset(). Everything 'bump is invalidated; borrow checker enforces this.
• Expr.Data.Store / Stmt.Data.Store / ASTMemoryAllocator are typed slabs with stable addresses (nodes reference each other) → typed_arena::Arena<T>. Returns &'arena T, never moves. Cross-node refs are &'arena Expr. Do not convert to Vec<Expr>.

In all other crates:

• std.mem.Allocator param → delete it. Box/Vec/String use global mimalloc.
• MimallocArena / ArenaAllocator local → delete the arena and its .reset()/.deinit(). Only leave // PERF(port): was arena bulk-free if the body allocates per-iteration in a hot loop.
• allocator.dupe(u8, s) → Box::<[u8]>::from(s) (or s.to_vec() if it grows). allocator.dupeZ → bun_str::ZStr::from_bytes(s).
• allocator.create(T) / allocator.destroy(p) → Box::new / drop.
• allocator.alloc(T, n) → vec![T::default(); n].into_boxed_slice() or Box::new_uninit_slice(n) if uninitialized.
• StackFallbackAllocator → just use the heap; // PERF(port): was stack-fallback.

Everywhere:

• bun.default_allocator → delete the expression.
• bun.new(T, init) / bun.destroy(p) → Box::new(init) / drop(b). If the pointer crosses FFI as *mut T, use Box::into_raw / Box::from_raw.
• bun.handleOom(expr) → expr (Rust Vec/Box allocation aborts on OOM; handleOom was Zig's panic-on-OOM wrapper, which is now the default).

Concurrency

Rust enforces thread-safety at compile time via Send/Sync auto-traits. Most Zig locks were defensive or init-once; they disappear.

Never std::sync::Mutex (poisoning is noise here); always parking_lot. Never put a lock next to the data — Mutex<T> owns T. If the Zig had lock: Lock, table: HashMap → Rust is table: Mutex<HashMap>.

When unsure if a lock is defensive: delete it, mark the type // PERF(port): was Lock-guarded — verify !Sync is sufficient. Phase B cargo check will error if another thread actually needs it (T: Sync bound fails) and you add the Mutex<T> then.

Dispatch (union(enum) across crate tiers)

Zig's union(enum) { A: *Foo, B: *Bar, fn run(self) { switch(self) { inline else => |p| p.run() } } } is closed-set dynamic dispatch with inlined arms. When the variants live in a higher-tier crate than the union, a naïve port creates a cycle. Break it without losing the inlining:

Cold path (called per-request, not per-tick — most cases): Low tier defines a manual vtable; high tier provides static instances.

// low tier (e.g. bun_io) — leaf, names no high-tier types
pub struct SourceVTable {
    pub on_read:  unsafe fn(*mut (), &[u8]),
    pub on_close: unsafe fn(*mut ()),
}
pub struct Source { pub owner: *mut (), pub vtable: &'static SourceVTable }

// high tier (e.g. bun_runtime)
pub static SUBPROCESS_SOURCE: SourceVTable = SourceVTable {
    on_read:  |p, b| unsafe { &mut *p.cast::<Subprocess>() }.on_read(b),
    on_close: |p|    unsafe { &mut *p.cast::<Subprocess>() }.on_close(),
};

Indirect call; LTO will not devirtualize a heterogeneous list. Acceptable when the callee does real work (syscall, JS callback). Mark // PERF(port): was inline switch.

Hot path (per-tick dispatch — short list below): Low tier stores (tag: u8, ptr: *mut ()) and exposes an iterator; high tier owns the match loop. Direct calls per arm → LLVM inlines exactly like Zig.

// low tier (bun_event_loop)
#[repr(transparent)] pub struct TaskTag(pub u8);
pub struct Task { pub tag: TaskTag, pub ptr: *mut () }
impl Queue { pub fn drain(&mut self) -> impl Iterator<Item = Task> + '_ { ... } }

// high tier (bun_runtime) — the ONLY place variant types are named
#[inline] pub fn run_tasks(q: &mut Queue) {
    for Task { tag, ptr } in q.drain() {
        match tag.0 {
            tag::PROMISE => unsafe { &mut *ptr.cast::<PromiseTask>() }.run(),
            tag::TIMER   => unsafe { &mut *ptr.cast::<TimerTask>()   }.run(),
            // ... one arm per variant
            _ => unsafe { core::hint::unreachable_unchecked() },
        }
    }
}

Hot-path list (use hoisted-match; everything else uses vtable):

• bun_event_loop::Task / ConcurrentTask (microtask queue)
• bun_aio::FilePoll::Owner (TaggedPointerUnion — ~13 variants)
• bun_event_loop::EventLoopTimer::Tag
• bun_io::Source
• bun_threading::WorkPool::Task

Do not use Box<dyn Trait> / enum_dispatch for these. dyn Trait only where Zig already used *anyopaque + fn-ptr (already indirect).

Debug/crash hooks (crash_handler dump callbacks, safety allocator checks): low tier defines static HOOK: AtomicPtr<()>; high tier writes the fn-ptr at init. One-shot registration, no vtable.

Pointers & ownership

Intrusive lists / @fieldParentPtr patterns: keep them. Use raw pointers and core::mem::offset_of! (see @fieldParentPtr row in §Idiom map). Don't try to make them Pin<Box<T>> in Phase A.

Collections

Do not use std::collections::HashMap (SipHash, different iteration order → behavioral diffs).

JSC types

// bun_jsc::JSValue
#[repr(transparent)]
#[derive(Copy, Clone, Eq, PartialEq)]
pub struct JSValue(i64, PhantomData<*const ()>);  // PhantomData<*const ()> = !Send + !Sync
// (negative impls `impl !Send` are nightly-only: feature(negative_impls), tracking #68318)
// No lifetime. Kept alive by conservative stack scan — stack/registers ONLY.

• Never store a bare JSValue as a field on a heap-allocated Rust struct. Conservative scan covers stack/registers only. For struct fields use bun_jsc::Strong (root), bun_jsc::JsRef (self-wrapper ref), or a codegen'd own: property (C++-side WriteBarrier). A JSValue field in a Box/Arc/Vec payload is a use-after-free.
• globalObject: *JSGlobalObject → global: &JSGlobalObject (always borrowed).
• callframe: *CallFrame → frame: &CallFrame.
• .js_undefined → JSValue::UNDEFINED. .jsNull() / .null → ::NULL. .jsBoolean(b) → JSValue::from(b). .true/.false → ::TRUE/::FALSE.
• .zero → JSValue::ZERO (encoded 0). Distinct from UNDEFINED. It means "no value / exception pending" and is what a host fn must return after throwing. value == .zero checks become value.is_empty().
• value.ensureStillAlive() → value.ensure_still_alive(): if value.is_cell() { core::hint::black_box(value.0); }. This matches Zig's doNotOptimizeAway (no-op for non-cells; black_box stable since 1.66). Call it after the last use of any interior pointer derived from value (typed-array .as_slice(), string .characters8()), not before. It is point-in-time, not RAII — for scope-long protection use let _keep = EnsureStillAlive(value); whose Drop calls black_box. If release-only GC crashes persist, upgrade to inline asm matching JSC: unsafe { core::arch::asm!("", in(reg) value.0, options(nostack, preserves_flags)); } — black_box is best-effort per std docs and lacks the "memory" clobber JSC uses.
• Building a slice of JSValues to pass as call arguments? Do not use Vec<JSValue> — its backing storage is on the Rust heap, not stack-scanned. Use bun_jsc::MarkedArgumentBuffer (registered with the VM as a root) or a fixed-size on-stack [JSValue; N]. If any element is created via to_js()/get_index() while looping, earlier elements can be collected mid-loop.
• JSRef field → bun_jsc::JsRef (non-generic; tagged union Weak(JSValue) | Strong(Strong.Optional) | Finalized). Its .weak arm is a bare JSValue, not a JSC::Weak — only sound because the codegen'd finalize() flips it to .finalized. Do not use JsRef on a struct without finalize: true.
• Strong / Strong.Optional → bun_jsc::Strong (a HandleSlot allocated from vm.heap.handleSet() — same root set JSC::Strong<T> uses; GC root; Drop deallocates the slot). If the Rust struct is itself owned by the JS wrapper (m_ctx), a Strong pointing back at the wrapper or anything that can reach it is a permanent leak — use JsRef instead.
• bun_jsc::Strong and bun_jsc::JsRef are !Send + !Sync (enforce via PhantomData<*const ()>). The HandleSlot is owned by the VM's HandleSet; Drop must run on the JS thread. Moving one into an Arc<T> and dropping from a thread-pool thread is UB.
• globalThis.vm().reportExtraMemory(n) → global.vm().deprecated_report_extra_memory(n) (no cell — matches the Zig binding exactly). This is the incremental-growth path (buffer appended, slice cloned). The non-deprecated heap.reportExtraMemoryAllocated(cell, n) is called by the codegen at construction when .classes.ts has estimatedSize: true — do not hand-port that. If the Zig type implements pub fn estimatedSize(...) usize, keep it — codegen wires both reportExtraMemoryAllocated (in construct/__create) and reportExtraMemoryVisited (in visitChildren). You only call deprecated_report_extra_memory(delta) manually for subsequent growth after construction. Both halves are required: alloc-side without visit-side → back-to-back full GCs; visit-side without alloc-side → OOM.
• Host fn signature fn(*JSGlobalObject, *CallFrame) bun.JSError!JSValue (aka JSHostFnZig) →

  #[bun_jsc::host_fn]
  pub fn name(global: &JSGlobalObject, frame: &CallFrame) -> JsResult<JSValue>

  The callconv(jsc.conv) raw form (JSHostFn) is what the attribute macro emits — don't hand-write it.
• Method/getter host fns on .classes.ts types take &mut Self first:

  #[bun_jsc::host_fn(method)]
  pub fn name(this: &mut Self, global: &JSGlobalObject, frame: &CallFrame) -> JsResult<JSValue>
  #[bun_jsc::host_fn(getter)]
  pub fn get_foo(this: &Self, global: &JSGlobalObject) -> JsResult<JSValue>
  #[bun_jsc::host_fn(setter)]
  pub fn set_foo(this: &mut Self, global: &JSGlobalObject, value: JSValue) -> JsResult<bool>

  The macro emits the callconv(jsc.conv) shim that downcasts m_ctx → *mut Self.
• bun.JSError!T → bun_jsc::JsResult<T> (alias for Result<T, JsError> where enum JsError { Thrown, OutOfMemory, Terminated } — exception cell lives on the VM; the variant only records which error path).
• .classes.ts-backed types: the C++ JSCell wrapper stays generated C++. Your Rust struct is the m_ctx payload. Derive #[bun_jsc::JsClass] and the codegen wires toJS/fromJS/hasPendingActivity. Don't hand-write visitChildren — WriteBarrier fields live on the C++ side. hasPendingActivity() runs on the GC thread, concurrently with the mutator. It must use the JSC calling convention (#[bun_jsc::host_call] extern fn(*mut Self) -> bool — same ABI rewrite as host_fn: "sysv64" on Windows-x64, "C" elsewhere), read only Atomic* fields (Ordering::Acquire), and never allocate, take locks, or touch JS. Prefer JsRef upgrade/downgrade over hasPendingActivity when there is a single busy/idle edge.
• .classes.ts finalize: true → implement pub fn finalize(this: *mut Self) on the Rust struct. Runs on the mutator thread during lazy sweep — do not touch any JSValue/Strong content (other cells may already be swept). Call self.this_value.finalize() first, then drop native resources. Do NOT rely on it for prompt cleanup; expose explicit close().

FFI

// Zig: extern fn us_socket_write(s: *Socket, data: [*]const u8, len: c_int) c_int;
unsafe extern "C" {
    // items default to `unsafe fn`; write `safe fn` for fns the caller may treat as safe (1.82+)
    pub fn us_socket_write(s: *mut Socket, data: *const u8, len: c_int) -> c_int;
}

• All extern fn blocks → into the area's *_sys crate. If your file has externs and isn't already *_sys, leave them in place with // TODO(port): move to <area>_sys.
• callconv(.c) → extern "C". JSC host fns: write #[bun_jsc::host_fn] exactly as shown in §JSC types (no extern on the user-facing fn — the attribute macro emits the correct ABI: "sysv64" on Windows-x64, "C" elsewhere). You cannot write extern jsc_conv!(); Rust does not accept a macro in ABI position.
• Exported fns (@export, comptime { @export(...) }) → #[unsafe(no_mangle)] pub extern "C" fn name(...). (On edition 2021 plain #[no_mangle] still works, but match the unsafe extern style above.)

Platform conditionals

if (Environment.isWindows) { ... } else { ... }

→

#[cfg(windows)] { ... }
#[cfg(not(windows))] { ... }
// or: if cfg!(windows) { ... } for trivial value-level selection

Caution: if cfg!(windows) keeps both branches in the type-checker (and monomorphization) — it does NOT remove the dead branch like Zig's if (Environment.isWindows) does. Use the #[cfg(...)] form when the disabled branch references platform-only items.

Environment.isDebug → cfg!(debug_assertions). Environment.isPosix → #[cfg(unix)]. Environment.os == .windows/.mac/.linux/.wasm → #[cfg(target_os = "windows"/"macos"/"linux")] (or #[cfg(windows)] for the windows arm). Treat exactly like isWindows.

Don't translate

• @import lines at the bottom of the file → just use bun_<area>::...; at the top. Don't 1:1 the import block.
• pub const X = @import("../foo_jsc/..").y; alias lines → delete. See "Idiom map".
• comptime { _ = @import(...); } force-reference blocks → drop. Rust links what's pub.
• Generated files (*_generated.zig, grapheme_tables.zig, boringssl_sys/boringssl.zig, libuv_sys/libuv.zig, schema.zig) → write a 3-line .rs stub: // GENERATED: re-run <generator> with .rs output.
• Test blocks (test "..." { ... }) → #[cfg(test)] mod tests { #[test] fn ...() { ... } }.

Output format

End your .rs with a trailer comment:

// ──────────────────────────────────────────────────────────────────────────
// PORT STATUS
//   source:     src/<area>/<file>.zig (NNN lines)
//   confidence: high | medium | low
//   todos:      N
//   notes:      <one line: anything Phase B needs to know>
// ──────────────────────────────────────────────────────────────────────────

confidence: low means "logic is probably wrong, re-read the Zig in Phase B". medium means "types/imports will need fixing but logic is right". high means "should compile with only mechanical import fixes".