Wasm logic gear

The Wasm Logic Gear is the primary extensibility point for the fluxrig data plane. It allows developers to inject sandboxed business logic into the signal flow using any language that compiles to WebAssembly (Wasm).

IMPORTANT

Technical Foundation: This gear uses the Wazero runtime, the only zero-dependency WebAssembly implementation in 100% Go. It needs no CGO.

The Wasm Logic Gear is a secure, sandboxed execution environment. Developers use it to run business logic written in any language (Rust, C++, Go, Zig, AssemblyScript) directly within the fluxrig pipeline. That logic can be complex, stateful, or computationally heavy.

Reference

fluxrig gears doc wasm generates the identity, ports, and configuration below from the gear's manifest, so they stay in lockstep with the code.

Type	wasm
Category	logic
Status	stable
Terminus	opaque

Runs a sandboxed WebAssembly module (wazero) as a polyglot message transform.

Ports

Port	Direction	Role	Summary
in	input	message	Message passed to the module.
out	output	message	Message the module returns.

Configuration

Field	Type	Required	Default	Description
source	string	yes	-	Path or URN of the .wasm module (e.g. file://... or a CAS urn).
entrypoint	string		-	Exported function to call per message.
memory_limit_pages	integer		-	Wasm linear-memory cap in 64KiB pages.

Why Wasm?

The core fluxrig engine handles protocol orchestration. Specific business rules often need a programmatic environment instead. Examples include complex tax calculations, custom fraud heuristics, and proprietary signal transformations. Wasm provides that environment while maintaining:

1. Performance: Near-native execution speeds via JIT/AOT compilation.
2. Security: A strict, Default-Deny sandbox model that isolates logic from the host system.
3. Portability: "Build once, run anywhere" across the distributed Rack fleet.

Standards compliance

Our implementation strictly adheres to the following industry standards to ensure long-term ecosystem compatibility:

• W3C WebAssembly Core 2.0: Ensures deterministic execution and binary portability.
• WASI (WebAssembly System Interface): Provides a standardized, capability-based interface for system resources (limited to approved descriptors).
• CBOR-Based ABI: Uses RFC 8949 (CBOR) for signal passing between the Go host and the Wasm guest. This keeps the host/guest boundary off the critical path.

Wasm supply chain security

To prevent malicious payloads from executing at the edge, fluxrig enforces a strict cryptographic supply chain:

1. Vendor Signatures: Third-party developers compile their .wasm binary. They sign it using an Ed25519 private key via fluxrig wasm sign. This embeds a fluxrig.signature directly into the Wasm custom sections.
2. Catalog Import: Ops engineers import the signed .wasm file into the Mixer using fluxrig wasm import. The Mixer cryptographically validates the signature against its trusted data/wasm/keys directory.
3. Mixer Countersignature: Upon successful validation, the Mixer countersigns the binary with its own Cluster Authority key (fluxrig.cluster.signature). It stores the binary in the Catalog, distributed via NATS Object Store or local filesystem depending on the topology.
4. Edge Validation: When an edge Rack hot-loads the binary via NATS Snake, it validates the Mixer's countersignature before passing the payload to wazero for compilation. Any payload failing signature verification is immediately dropped.

Filter architecture & implicit ports

NOTE

Current Topology Role: The Wasm gear currently runs strictly as a Filter gear (1-to-1 or 1-to-0). It receives exactly one input message, processes it synchronously, and returns exactly one output message (or drops it).

Because of this strict filter pattern, the Wasm gear uses implicit ports. You do not need to define a ports block in its configuration.

• Input (.in): The router automatically routes incoming messages to the gear's .in port, which triggers the Wasm process() function.
• Output (.out): The result returned by process() is automatically emitted on the .out port.

(A future release will support Source/Split Wasm gears that generate spontaneous messages via env.emit).

Architecture

Address a module the same way as a spec: by a path, or by a URN into the content-addressable store.

Application binary interface (ABI)

The Wasm gear will communicate with the host Rack using a strictly defined ABI based on CBOR memory pointers.

1. Guest Input: The host Rack writes the serialized fluxMsg into the guest's linear memory.
2. Guest Execution: The Wasm module processes the data.
3. Guest Output: The Wasm module returns a pointer to the modified fluxMsg. It can instead return an array of messages representing fan-out. It also returns an exit code (e.g., 0=OK, 1=Reject, 2=Drop).

Host imports (capabilities)

To remain useful while sandboxed, the host Rack will expose secure functions to the guest:

• flux_kv_get(key) / flux_kv_put(key, val): Access to the global NATS KV store.
• flux_log_info(msg): Emits structured logs into the system telemetry stream.
• flux_req_http(url, body): Optional outbound HTTP fetch capability (requires explicit permission in scenario configuration).
• flux_emit(msg): [Roadmap / Future] Spontaneous message emission to the wire, enabling Source or Fan-out Wasm gears.

Integration example

gears:
  - name: "my-wasm-gear"
    type: "wasm"
    config:
      # Source can be a local file or pulled from the NATS Catalog via URN
      source: "urn:wasm:fraud-scorer:v2.1"
      entrypoint: "process"
      memory_limit_pages: 16

# Note: Because the Wasm gear is currently a pure Filter gear, its ports are implicit.
# Any message routed to `my-wasm-gear.in` will trigger `process()`, and the returned
# result will automatically be emitted on `my-wasm-gear.out`.