Fastly Compute Native Test Linker Failure

Fastly Compute native test linker failure

Problem

Fastly Compute Rust binaries link against libfastly, which provides FFI symbols that only exist when targeting wasm32-wasip1. On a native host (macOS, Linux x86_64, Linux arm64), the FFI symbols are absent, so linking a test binary for the Fastly Compute crate fails with errors like:

"_version_set", referenced from:
    fastly::http::response::handle::ResponseHandle::set_version::h234bdb33f8878476 in libfastly-XXXX.rlib
"_body_new", referenced from:
    fastly::http::body::Body::new::hYYYY in libfastly-XXXX.rlib
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1
error: could not compile `fastly-blossom` (bin "fastly-blossom" test)

The error appears during cargo test even if none of your tests actually call Fastly SDK code — cargo still tries to compile and link the entire binary as a test target.

This has a nasty consequence: any #[cfg(test)] mod tests { ... } block inside a file compiled into the binary crate is effectively dead code. It never runs via cargo test because cargo can't link the test binary. Developers add tests, the compiler accepts them, they're visible in the source tree — but they never execute. Tests that were meant to regression-guard behavior silently become documentation that rots.

Context / Trigger Conditions

• Fastly Compute Rust project with fastly = "0.11.x" (or similar) as a dependency
• The crate has both src/main.rs and src/lib.rs OR only src/main.rs
• cargo test fails at link time with _version_set / _body_new / _req_send undefined
• cargo check --target wasm32-wasip1 succeeds
• cargo check (native) succeeds (library code compiles, just can't link the binary)
• You added tests in src/admin.rs, src/blossom.rs, src/metadata.rs, or any file that's mod-included from src/main.rs but NOT from src/lib.rs

Root cause

Fastly's Rust SDK (fastly crate) is designed exclusively for wasm32-wasip1. Its public API calls unsafe FFI functions (_version_set, _req_send, _body_new, etc.) that the Fastly Compute runtime provides at execution time inside the POP. On a native host, the rustc compiler still compiles the library crate, but the linker can't resolve those FFI symbols because libfastly-native doesn't exist.

cargo test for a mixed lib+bin crate links two artifacts: the library test binary AND the binary test binary (the main executable with tests enabled). The library test binary can avoid the SDK symbols if lib.rs doesn't import them transitively. The binary test binary can't, because main.rs wires the whole Fastly Compute runtime.

Solution

Structure your crate as lib + bin, and put all testable logic in lib

1. Create src/lib.rs if it doesn't exist:

// src/lib.rs — library target, testable natively
pub mod admin_sweep;   // pure logic, no Fastly SDK
pub mod classifiers;   // pure logic, no Fastly SDK
pub mod parsers;       // pure logic, no Fastly SDK

2. Put any module you want to unit-test in a separate file that does NOT import Fastly SDK types, and expose it via pub mod in lib.rs:

// src/admin_sweep.rs — pure logic, testable natively
pub enum StuckAction { SkipNotStuck, SkipTooRecent, MarkComplete, ResetPending }

pub fn classify_stuck_record(
    is_processing: bool,
    uploaded_iso: &str,
    threshold_iso: &str,
    hls_present: bool,
) -> StuckAction { /* ... */ }

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn skip_not_stuck_when_status_is_not_processing() { /* ... */ }
}

3. In src/main.rs, also declare the module so the binary can use it:

mod admin_sweep;  // same file, compiled twice — once for lib, once for bin

4. The handler in an admin.rs (or wherever) that DOES use Fastly SDK types extracts primitives from SDK types and calls the pure classifier:

// src/admin.rs (part of the bin, uses Fastly SDK types like Request/Response)
pub fn handle_sweep(req: Request) -> Result<Response> {
    let is_processing = meta.transcode_status == Some(TranscodeStatus::Processing);
    let action = crate::admin_sweep::classify_stuck_record(
        is_processing, &meta.uploaded, &threshold_iso, hls_present,
    );
    // ... match on action, make SDK-level calls ...
}

5. Run tests with:

cargo test --lib

Not cargo test (which tries to link the bin). --lib only builds and runs the library test binary, which can link because none of its code touches Fastly SDK symbols.

Do NOT depend on crate internals from the lib module

Your lib-exposed module must NOT transitively import anything that touches the Fastly SDK. Common traps:

• use crate::blossom::BlobMetadata; — if blossom.rs is in the binary crate and uses fastly::Request, importing BlobMetadata drags SDK symbols into the lib build. Solution: pass raw primitives (Option<TranscodeStatus>, &str, etc.) across the boundary, not full SDK-aware structs.
• use crate::storage::current_timestamp; — if storage.rs calls fastly::kv_store::*, same problem. Duplicate the helper in admin_sweep.rs or extract it to a third SDK-free module in lib.rs.

Treat lib.rs as a clean-room: only pure Rust, no SDK types, no platform-specific I/O.

Verify

cargo check --target wasm32-wasip1  # must still succeed (bin compiles for deploy)
cargo test --lib                     # must run and pass (tests exercise pure logic)

You can also add to CI:

- run: cargo test --lib
- run: cargo check --target wasm32-wasip1

cargo test (no flags) will still fail on this project; that's expected and unavoidable. Document it in README or CONTRIBUTING so contributors don't waste time on it.