castrum 0.9.2 → 0.9.4

package/rust/http/url_join.rs

@@ -0,0 +1,324 @@
+// rust/http/url_join.rs — URL building: RFC 3986 reference resolution + query builder.
+//
+// `url_resolve(base, reference)` resolves a relative/absolute reference against
+// a base URI (merge paths + remove dot segments). `url_encode_query` builds a
+// percent-encoded query string (deterministic sorted-key order). The
+// `UrlBuilder` higher-order instance parses the base once and reuses it.
+
+use std::collections::BTreeMap;
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+/// A parsed URI reference (RFC 3986 §4.2 components).
+#[derive(Debug, Clone)]
+pub(crate) struct Ref {
+    scheme: Option<String>,
+    authority: Option<String>,
+    path: String,
+    query: Option<String>,
+    fragment: Option<String>,
+}
+
+pub(crate) fn parse_ref(input: &str) -> Ref {
+    let (rest, fragment) = match input.find('#') {
+        Some(i) => (&input[..i], Some(input[i + 1..].to_string())),
+        None => (input, None),
+    };
+
+    let (rest, scheme) = if let Some(i) = rest.find(':') {
+        let candidate = &rest[..i];
+        if !candidate.is_empty()
+            && candidate
+                .chars()
+                .all(|c| c.is_ascii_alphanumeric() || c == '+' || c == '-' || c == '.')
+        {
+            (&rest[i + 1..], Some(candidate.to_string()))
+        } else {
+            (rest, None)
+        }
+    } else {
+        (rest, None)
+    };
+
+    let (rest, authority) = if let Some(rest2) = rest.strip_prefix("//") {
+        let end = rest2.find('/').unwrap_or(rest2.len());
+        (&rest2[end..], Some(rest2[..end].to_string()))
+    } else {
+        (rest, None)
+    };
+
+    let (path, query) = match rest.find('?') {
+        Some(i) => (rest[..i].to_string(), Some(rest[i + 1..].to_string())),
+        None => (rest.to_string(), None),
+    };
+
+    Ref {
+        scheme,
+        authority,
+        path,
+        query,
+        fragment,
+    }
+}
+
+/// RFC 3986 §5.2.4 remove_dot_segments (normalize `.` / `..`).
+fn remove_dot_segments(path: &str) -> String {
+    let leading = path.starts_with('/');
+    let parts: Vec<&str> = path.split('/').collect();
+    let mut segments: Vec<&str> = Vec::new();
+    let mut i = 0usize;
+    if parts.first() == Some(&"") {
+        i = 1;
+    }
+    while i < parts.len() {
+        match parts[i] {
+            "." => {}
+            ".." => {
+                segments.pop();
+            }
+            seg => segments.push(seg),
+        }
+        i += 1;
+    }
+    let body = segments.join("/");
+    if leading {
+        format!("/{body}")
+    } else {
+        body
+    }
+}
+
+/// RFC 3986 §5.3.3 merge paths.
+fn merge_paths(base_path: &str, ref_path: &str) -> String {
+    match base_path.rfind('/') {
+        Some(i) => format!("{}{}", &base_path[..=i], ref_path),
+        None => ref_path.to_string(),
+    }
+}
+
+pub(crate) fn resolve_target(base: &Ref, r: &Ref) -> Ref {
+    if r.scheme.is_some() {
+        let mut t = r.clone();
+        t.path = remove_dot_segments(&r.path);
+        return t;
+    }
+    let mut t = Ref {
+        scheme: base.scheme.clone(),
+        authority: base.authority.clone(),
+        path: String::new(),
+        query: None,
+        fragment: r.fragment.clone(),
+    };
+    if r.authority.is_some() {
+        t.authority = r.authority.clone();
+        t.path = remove_dot_segments(&r.path);
+        t.query = r.query.clone();
+        return t;
+    }
+    if r.path.is_empty() {
+        t.path = base.path.clone();
+        t.query = r.query.clone().or_else(|| base.query.clone());
+        return t;
+    }
+    if r.path.starts_with('/') {
+        t.path = remove_dot_segments(&r.path);
+    } else {
+        t.path = remove_dot_segments(&merge_paths(&base.path, &r.path));
+    }
+    t.query = r.query.clone();
+    t
+}
+
+pub(crate) fn recompose(r: &Ref) -> String {
+    let mut s = String::new();
+    if let Some(sch) = &r.scheme {
+        s.push_str(sch);
+        s.push(':');
+    }
+    if let Some(auth) = &r.authority {
+        s.push_str("//");
+        s.push_str(auth);
+    }
+    s.push_str(&r.path);
+    if let Some(q) = &r.query {
+        s.push('?');
+        s.push_str(q);
+    }
+    if let Some(f) = &r.fragment {
+        s.push('#');
+        s.push_str(f);
+    }
+    s
+}
+
+#[napi]
+pub fn url_resolve(base: Uint8Array, reference: Uint8Array) -> Result<Buffer> {
+    let b =
+        std::str::from_utf8(base.as_ref()).map_err(|_| Error::from_reason("base must be UTF-8"))?;
+    let r = std::str::from_utf8(reference.as_ref())
+        .map_err(|_| Error::from_reason("reference must be UTF-8"))?;
+    let target = resolve_target(&parse_ref(b), &parse_ref(r));
+    Ok(Buffer::from(recompose(&target).into_bytes()))
+}
+
+/// Packed URL-resolve batch (two packed lists: bases + references, zipped) →
+/// `[u32 count]{[u32 len][resolved]}` out. Items that fail UTF-8 parsing yield
+/// an empty result — skip-on-error.
+#[napi]
+pub fn url_resolve_batch_packed(bases: Uint8Array, references: Uint8Array) -> Result<Buffer> {
+    use crate::util::packed::PackedIter;
+    let b = bases.as_ref();
+    let r = references.as_ref();
+    let count = PackedIter::new(b)?.len().min(PackedIter::new(r)?.len());
+    let mut out = Vec::with_capacity(4 + count * 64);
+    out.extend_from_slice(&(count as u32).to_le_bytes());
+    for (base, reference) in PackedIter::new(b)?.zip(PackedIter::new(r)?) {
+        let resolved = match (std::str::from_utf8(base), std::str::from_utf8(reference)) {
+            (Ok(bs), Ok(rs)) => {
+                recompose(&resolve_target(&parse_ref(bs), &parse_ref(rs))).into_bytes()
+            }
+            _ => Vec::new(),
+        };
+        out.extend_from_slice(&(resolved.len() as u32).to_le_bytes());
+        out.extend_from_slice(&resolved);
+    }
+    Ok(Buffer::from(out))
+}
+
+pub(crate) fn encode_query_component(
+    input: &[u8],
+    scratch: &mut Vec<u8>,
+    out: &mut Vec<u8>,
+) -> Result<()> {
+    // Reuse one caller-provided scratch buffer across all keys/values instead of
+    // allocating a fresh `vec![0u8; len*3]` per component. Grows only when the
+    // largest component needs more room.
+    if scratch.len() < input.len().saturating_mul(3) {
+        scratch.resize(input.len().saturating_mul(3), 0);
+    }
+    let written = crate::http::url_codec::url_encode_into_slice(input, scratch)?;
+    out.extend_from_slice(&scratch[..written]);
+    Ok(())
+}
+
+#[napi]
+pub fn url_encode_query(params: BTreeMap<String, String>) -> Result<Buffer> {
+    let mut out = Vec::new();
+    let mut scratch = Vec::new();
+    for (i, (k, v)) in params.iter().enumerate() {
+        if i > 0 {
+            out.push(b'&');
+        }
+        encode_query_component(k.as_bytes(), &mut scratch, &mut out)?;
+        out.push(b'=');
+        encode_query_component(v.as_bytes(), &mut scratch, &mut out)?;
+    }
+    Ok(Buffer::from(out))
+}
+
+/// Higher-order instance: base parsed once, reused across resolves.
+#[napi]
+pub struct UrlBuilder {
+    base: Ref,
+}
+
+/// C-ABI support: resolve `reference` against the precompiled base, returning
+/// the UTF-8 bytes. `Err(())` on non-UTF-8 reference (napi parity: throws).
+///
+/// # Safety
+/// `p` must be a valid `*const UrlBuilder` obtained from `inner_ptr` and must
+/// stay alive for the call (the JS wrapper holds the napi instance).
+pub(crate) unsafe fn url_builder_resolve_core(
+    p: *const UrlBuilder,
+    reference: &[u8],
+) -> std::result::Result<Vec<u8>, ()> {
+    let r = std::str::from_utf8(reference).map_err(|_| ())?;
+    let this = &*p;
+    Ok(recompose(&resolve_target(&this.base, &parse_ref(r))).into_bytes())
+}
+
+#[napi]
+impl UrlBuilder {
+    #[napi(constructor)]
+    pub fn new(base: Uint8Array) -> Result<Self> {
+        let b = std::str::from_utf8(base.as_ref())
+            .map_err(|_| Error::from_reason("base must be UTF-8"))?;
+        Ok(Self { base: parse_ref(b) })
+    }
+
+    /// Opaque handle to the precompiled base, for the `bun:ffi` C-ABI fast path
+    /// (`castrum_url_builder_resolve` in rust/ffi.rs). Only valid while THIS
+    /// instance is alive; the JS wrapper holds the instance for the handle
+    /// lifetime (same contract as `Ingress::ingress_inner_ptr`).
+    #[napi]
+    pub fn inner_ptr(&self) -> u64 {
+        self as *const UrlBuilder as u64
+    }
+
+    #[napi]
+    pub fn resolve(&self, reference: Uint8Array) -> Result<Buffer> {
+        let r = std::str::from_utf8(reference.as_ref())
+            .map_err(|_| Error::from_reason("reference must be UTF-8"))?;
+        let target = resolve_target(&self.base, &parse_ref(r));
+        Ok(Buffer::from(recompose(&target).into_bytes()))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn resolve(base: &str, reference: &str) -> String {
+        recompose(&resolve_target(&parse_ref(base), &parse_ref(reference)))
+    }
+
+    #[test]
+    fn absolute_reference() {
+        assert_eq!(
+            resolve("http://a/b/c/d;p?q", "http://x/y/z"),
+            "http://x/y/z"
+        );
+    }
+
+    #[test]
+    fn authority_reference() {
+        assert_eq!(
+            resolve("http://a/b/c/d;p?q", "//other/path"),
+            "http://other/path"
+        );
+    }
+
+    #[test]
+    fn dot_segment_removal() {
+        assert_eq!(resolve("http://a/b/c/d;p?q", "../../../g"), "http://a/g");
+        assert_eq!(resolve("http://a/b/c/d;p?q", "../../../../g"), "http://a/g");
+        assert_eq!(resolve("http://a/b/c/d;p?q", "./g"), "http://a/b/c/g");
+        assert_eq!(resolve("http://a/b/c/d;p?q", "g/./h"), "http://a/b/c/g/h");
+        assert_eq!(resolve("http://a/b/c/d;p?q", "g/../h"), "http://a/b/c/h");
+    }
+
+    #[test]
+    fn query_and_fragment() {
+        assert_eq!(resolve("http://a/b/c/d;p?q", "g?y#f"), "http://a/b/c/g?y#f");
+        assert_eq!(
+            resolve("http://a/b/c/d;p?q", "#frag"),
+            "http://a/b/c/d;p?q#frag"
+        );
+        assert_eq!(resolve("http://a/b/c/d;p?q", "?y"), "http://a/b/c/d;p?y");
+    }
+
+    #[test]
+    fn empty_path_reference_keeps_base_query() {
+        assert_eq!(resolve("http://a/b/c/d;p?q", ""), "http://a/b/c/d;p?q");
+    }
+
+    #[test]
+    fn query_builder_sorted_and_encoded() {
+        let mut params = BTreeMap::new();
+        params.insert("b".to_string(), "x y".to_string());
+        params.insert("a".to_string(), "1".to_string());
+        let out = url_encode_query(params).unwrap();
+        assert_eq!(out.as_ref(), b"a=1&b=x%20y");
+    }
+}

package/rust/ingress/api.rs

@@ -0,0 +1,355 @@
+// rust/ingress/api.rs — the `Ingress` napi class + `IngressInner` state.
+//
+// The napi boundary of the ingress pipeline. `IngressInner` holds the compiled
+// per-instance configuration (options, CORS, rate limiter, schema, limits); the
+// `Ingress` class exposes the packed and full-sync request entry points. The
+// core 8-stage pipeline logic lives in `pipeline.rs` (`IngressInner`'s
+// `handle_packed`); this module only marshals options into state and routes
+// requests into it. Kept as a separate file so `ingress/mod.rs` stays a pure
+// declaration hub.
+
+use napi::bindgen_prelude::*;
+use napi::Status;
+use napi_derive::napi;
+
+use std::sync::Arc;
+
+use super::{IngressOptions, IngressSchema, Limits};
+use crate::ingress::output::{MAX_OUTPUT_BUFFER_SIZE, OUT_DATA_START};
+use crate::ingress::rate_limit::RateLimiterState;
+
+/// Clamp an ingress output-buffer size into `[OUT_DATA_START, MAX_OUTPUT_BUFFER_SIZE]`
+/// so a misconfigured (huge/negative) `outputBufferSize` can never trigger a
+/// multi-GB native allocation (OOM) in the allocating full_sync entry.
+pub(crate) fn clamp_output_size(output_buffer_size: Option<u32>) -> usize {
+    output_buffer_size
+        .unwrap_or(262_144)
+        .clamp(OUT_DATA_START as u32, MAX_OUTPUT_BUFFER_SIZE) as usize
+}
+
+/// Compiled per-instance ingress state. Constructed once by [`Ingress::new`]
+/// from the JS-facing options; `handle_packed` (in `pipeline.rs`) runs the
+/// 8-stage pipeline over this immutable configuration.
+#[derive(Clone)]
+pub(crate) struct IngressInner {
+    pub https_fixed: Option<bool>,
+    pub max_body_bytes: usize,
+    pub proxy_trust: crate::ingress::ip_trust::ProxyTrustMode,
+    pub parse_cookies: bool,
+    pub parse_query: bool,
+    pub require_json_body: bool,
+    pub guard_enabled: bool,
+    pub emit_metadata_json: bool,
+    pub cors_enabled: bool,
+    pub cors: crate::ingress::cors::CorsEngine,
+    pub rate: RateLimiterState,
+    pub schema: Option<Arc<IngressSchema>>,
+    pub limits: Limits,
+}
+
+#[napi]
+pub struct Ingress {
+    inner: Arc<IngressInner>,
+}
+
+#[napi]
+impl Ingress {
+    #[napi(constructor)]
+    pub fn new(options: IngressOptions) -> Result<Self> {
+        let parse_cookies = options.parse_cookies.unwrap_or(false);
+        let parse_query = options.parse_query.unwrap_or(false);
+        let require_json_body = options.require_json_body.unwrap_or(false);
+        let max_body_bytes = options
+            .max_body_bytes
+            .unwrap_or(crate::ingress::options::DEFAULT_MAX_BODY_BYTES as u32)
+            as usize;
+        let guard_enabled = options.enable_body_size_guard.unwrap_or(true);
+        let emit_metadata_json = options.emit_metadata_json.unwrap_or(false);
+
+        let proxy_trust = if let Some(tp) = options.trusted_proxies {
+            crate::ingress::ip_trust::ProxyTrustMode::from_config(
+                tp.enabled.unwrap_or(false),
+                tp.networks,
+            )
+            .map_err(|e| Error::new(Status::InvalidArg, e))?
+        } else if options.trust_proxy.unwrap_or(false) {
+            crate::ingress::ip_trust::ProxyTrustMode::All
+        } else {
+            crate::ingress::ip_trust::ProxyTrustMode::None
+        };
+
+        let schema = if let Some(schema_bytes) = options.schema {
+            let schema_str = std::str::from_utf8(&schema_bytes)
+                .map_err(|_| Error::new(Status::InvalidArg, "Invalid UTF-8 in schema"))?;
+            let schema_value: serde_json::Value = sonic_rs::from_str(schema_str)
+                .map_err(|e| Error::new(Status::InvalidArg, format!("Schema JSON error: {}", e)))?;
+            // Compile BOTH the authoritative jsonschema validator and the
+            // zero-DOM fast path once at construction — no per-request schema
+            // work (see IngressSchema in pipeline.rs).
+            let compiled = IngressSchema::compile(&schema_value).map_err(|e| {
+                Error::new(Status::InvalidArg, format!("Schema compile error: {}", e))
+            })?;
+            Some(Arc::new(compiled))
+        } else {
+            None
+        };
+
+        let cors_enabled = options.cors.is_some();
+        let cors = crate::ingress::cors::CorsEngine::from_options(options.cors)?;
+
+        let rate = if let Some(rl_opts) = options.rate_limit {
+            let limit = rl_opts.limit.unwrap_or(0);
+            let window_ms = rl_opts.window_ms.unwrap_or(1000);
+            if limit == 0 || limit == u32::MAX {
+                RateLimiterState::Disabled
+            } else {
+                let max_entries = rl_opts.max_entries.map(|v| v as usize);
+                // Shared per-configuration across the process: prevents a client
+                // from bypassing a per-IP limit by spreading requests across routes.
+                RateLimiterState::Enabled(
+                    crate::ingress::rate_limit::shared_limiter(limit, window_ms, max_entries)
+                        .map_err(|e| Error::new(Status::InvalidArg, e))?,
+                )
+            }
+        } else {
+            RateLimiterState::Disabled
+        };
+
+        let limits = Limits::from_options(options.limits);
+
+        Ok(Self {
+            inner: Arc::new(IngressInner {
+                https_fixed: options.https,
+                max_body_bytes,
+                proxy_trust,
+                parse_cookies,
+                parse_query,
+                require_json_body,
+                guard_enabled,
+                emit_metadata_json,
+                cors_enabled,
+                cors,
+                rate,
+                schema,
+                limits,
+            }),
+        })
+    }
+
+    /// Opaque handle to the inner pipeline state, for the `bun:ffi` C-ABI fast
+    /// path (`castrum_ingress_handle_packed` in rust/ffi.rs).
+    ///
+    /// # Safety / lifetime
+    /// The returned value is a raw pointer into the `Arc<IngressInner>` and is
+    /// ONLY valid while THIS `Ingress` instance is alive (napi keeps the native
+    /// state alive while the JS object is referenced; it is dropped on GC). It
+    /// must be treated as an opaque handle — JS must never dereference it, and
+    /// it must be discarded if the instance is dropped. The internal wrapper
+    /// (`src/native/ffi.ts`) holds the instance for the lifetime of the ingress
+    /// handler, so in practice the handle never outlives the state it points
+    /// to. Exposed for the internal fast path only; not part of the public API.
+    #[napi]
+    pub fn ingress_inner_ptr(&self) -> u64 {
+        self.inner.as_ref() as *const IngressInner as u64
+    }
+
+    /// Production API:
+    ///   input = packed metadata frame
+    ///   body = separate zero-copy body
+    ///   output = response decision buffer
+    #[napi(ts_args_type = "input: Uint8Array, body: Uint8Array | null, output: Uint8Array")]
+    pub fn handle_request_packed(
+        &self,
+        input: Uint8Array,
+        body: Option<Uint8Array>,
+        mut output: Uint8Array,
+    ) -> Result<u32> {
+        let inner: &IngressInner = self.inner.as_ref();
+
+        crate::util::run_packed_into(&input, &mut output, move |inp, out| match body {
+            Some(b) => {
+                let b_bytes = b.as_ref();
+                if crate::util::slices_overlap(b_bytes, out) {
+                    let owned = b_bytes.to_vec();
+                    inner.handle_packed(inp, &owned, out)
+                } else {
+                    inner.handle_packed(inp, b_bytes, out)
+                }
+            }
+            None => inner.handle_packed(inp, &[], out),
+        })
+    }
+
+    /// Optimized sync API:
+    /// Accepts raw JS values (no binary packing in JS), packs them in Rust,
+    /// and processes them synchronously.
+    /// This is the fastest path for simple requests.
+    ///
+    /// Allocating variant: allocates a fresh output buffer per call. Hot paths
+    /// should prefer [`Self::handle_request_full_sync_into`], which reuses a
+    /// caller-provided (pooled) output buffer.
+    #[allow(clippy::too_many_arguments)]
+    #[napi(
+        ts_args_type = "methodKind: number, url: string, ip: string, requestId: string, headers: Array<[string, string]>, body: Uint8Array | null, outputBufferSize?: number"
+    )]
+    pub fn handle_request_full_sync(
+        &self,
+        method_kind: u32,
+        url: String,
+        ip: String,
+        request_id: String,
+        headers: Vec<Vec<String>>,
+        body: Option<Uint8Array>,
+        output_buffer_size: Option<u32>,
+    ) -> Result<Uint8Array> {
+        // The fresh `out` vec cannot alias `body` (a distinct JS buffer), so it
+        // is safe to borrow the body without copying.
+        let body_bytes: &[u8] = match &body {
+            Some(b) => b.as_ref(),
+            None => &[],
+        };
+
+        // Default SMALL (the packed decision + metadata JSON is typically a few
+        // hundred bytes — a flat 256 KiB zero-fill per call is wasteful) and
+        // grow on the pipeline's "output buffer too small" signal, capped at
+        // `MAX_OUTPUT_BUFFER_SIZE`. Hot paths use the pooled `_into` variant.
+        let mut output_size = match output_buffer_size {
+            Some(s) => clamp_output_size(Some(s)),
+            // `OUT_DATA_START + 8192` is within `[OUT_DATA_START, MAX]` by
+            // construction, so no clamp is needed for the default.
+            None => OUT_DATA_START + 8192,
+        };
+        let mut out = vec![0u8; output_size];
+        let mut attempt_headers = headers.clone();
+        loop {
+            match self.full_sync_into(
+                method_kind,
+                &url,
+                &ip,
+                &request_id,
+                attempt_headers,
+                body_bytes,
+                &mut out,
+            ) {
+                Ok(written) => {
+                    out.truncate(written);
+                    return Ok(Uint8Array::new(out));
+                }
+                Err(e)
+                    if e.reason == "output buffer too small"
+                        && output_size < MAX_OUTPUT_BUFFER_SIZE as usize =>
+                {
+                    // Grow (bounded) and retry with a fresh header marshal.
+                    output_size = (output_size * 2).min(MAX_OUTPUT_BUFFER_SIZE as usize);
+                    out.resize(output_size, 0);
+                    attempt_headers = headers.clone();
+                }
+                Err(e) => return Err(e),
+            }
+        }
+    }
+
+    /// Reusable-output variant of [`Self::handle_request_full_sync`]: packs raw
+    /// request components in Rust, runs the pipeline, and writes the packed
+    /// decision into the caller-provided `output` buffer, returning the number
+    /// of bytes written.
+    ///
+    /// The caller is expected to pool the output buffer across requests (see
+    /// `src/shared/buffer-pool.ts`) to eliminate per-request allocation. The
+    /// body is zero-copied unless it aliases `output` (guarded by
+    /// `crate::util::slices_overlap`).
+    #[allow(clippy::too_many_arguments)]
+    #[napi(
+        ts_args_type = "methodKind: number, url: string, ip: string, requestId: string, headers: Array<[string, string]>, body: Uint8Array | null, output: Uint8Array"
+    )]
+    pub fn handle_request_full_sync_into(
+        &self,
+        method_kind: u32,
+        url: String,
+        ip: String,
+        request_id: String,
+        headers: Vec<Vec<String>>,
+        body: Option<Uint8Array>,
+        mut output: Uint8Array,
+    ) -> Result<u32> {
+        let body_bytes: &[u8] = match &body {
+            Some(b) => b.as_ref(),
+            None => &[],
+        };
+
+        // Check overlap before taking the mutable slice (can't alias output
+        // mutably and immutably at the same time).
+        let overlaps = crate::util::slices_overlap(body_bytes, output.as_ref());
+
+        if overlaps {
+            // The caller aliased body with output: fall back to an owned copy.
+            let owned = body_bytes.to_vec();
+            // SAFETY: `output` is a caller-provided buffer we write into and
+            // `full_sync_into` does not retain the slice beyond the call. This
+            // mirrors the existing `crate::util::run_packed_into` pattern.
+            let out: &mut [u8] = unsafe { output.as_mut() };
+            let written =
+                self.full_sync_into(method_kind, &url, &ip, &request_id, headers, &owned, out)?;
+            return Ok(written as u32);
+        }
+
+        // SAFETY: see above — the caller-provided buffer is only borrowed for
+        // the duration of the call.
+        let out: &mut [u8] = unsafe { output.as_mut() };
+        let written = self.full_sync_into(
+            method_kind,
+            &url,
+            &ip,
+            &request_id,
+            headers,
+            body_bytes,
+            out,
+        )?;
+        Ok(written as u32)
+    }
+
+    /// Shared core for the full_sync family: packs raw request components in
+    /// Rust and runs the ingress pipeline, writing into `out` (which must be at
+    /// least `OUT_DATA_START` bytes). Returns the number of bytes written.
+    ///
+    /// `body` is borrowed; callers must guarantee it does not alias `out` (the
+    /// into-variant checks overlap before calling).
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn full_sync_into(
+        &self,
+        method_kind: u32,
+        url: &str,
+        ip: &str,
+        request_id: &str,
+        headers: Vec<Vec<String>>,
+        body: &[u8],
+        out: &mut [u8],
+    ) -> Result<usize> {
+        let inner: &IngressInner = self.inner.as_ref();
+
+        // Consume the napi-marshaled header strings by moving the last two
+        // elements out of each Vec — avoids a second allocation per header
+        // name/value (napi already allocated the owned Strings).
+        let header_pairs: Vec<(String, String)> = headers
+            .into_iter()
+            .filter_map(|mut h| {
+                if h.len() < 2 {
+                    return None;
+                }
+                let value = h.pop().unwrap_or_default();
+                let name = h.pop().unwrap_or_default();
+                Some((name, value))
+            })
+            .collect();
+
+        let packed = crate::ingress::packed::build_packed_input_sync(
+            method_kind as u8,
+            url.as_bytes(),
+            ip.as_bytes(),
+            request_id.as_bytes(),
+            &header_pairs,
+        );
+
+        inner.handle_packed(&packed, body, out)
+    }
+}