ndn-rs Wiki

Notice: primarily AI-authored, not yet proven correct. This codebase is primarily authored by an AI coding assistant. A recent spec-compliance audit (docs/notes/spec-compliance-audit-2026-04-20.md) found numerous wire-format and protocol-semantics errors, including BLOCKER-tier issues that any conforming NDN peer would reject. Remediation is in progress in the open — see the spec-compliance summary and testbed/EXPECTED_FAILURES.md. Do not cite ndn-rs as a reference implementation of NDN. For a reference, use NFD / ndn-cxx / NDNts / ndnd / python-ndn.

ndn-rs is a Rust NDN forwarder stack that models Named Data Networking as composable data pipelines with trait-based polymorphism — embeddable as a library, scalable from Cortex-M to multi-core routers.

Pre-release. The workspace reads 0.1.0 but no tag has been published yet — this wiki documents main. Pull ghcr.io/quarmire/ndn-fwd:latest or build from source. See the draft release notes for planned scope.

NDN replaces host-addressed networking with named data: consumers request content by name (Interest), the network locates and returns it (Data), and every Data packet is cryptographically signed at birth — enabling in-network caching and security that travels with the data.

Navigating This Wiki

Crate Map

Dependencies flow strictly downward. ndn-tlv and ndn-packet compile no_std.

%%{init: {"layout": "elk"}}%%
flowchart TD
    subgraph Binaries
        fwd["ndn-fwd"]
        tools["ndn-tools"]
        bench["ndn-bench"]
    end

    subgraph Engine & App
        engine["ndn-engine"]
        app["ndn-app"]
        ipc["ndn-ipc"]
        config["ndn-config"]
        discovery["ndn-discovery"]
    end

    subgraph Pipeline & Security
        strategy["ndn-strategy"]
        security["ndn-security"]
    end

    subgraph Faces
        faces["ndn-faces\n(UDP, TCP, SHM, Ethernet, ...)"]
    end

    subgraph Foundation
        store["ndn-store"]
        transport["ndn-transport"]
        packet["ndn-packet\n(no_std)"]
        tlv["ndn-tlv\n(no_std)"]
    end

    fwd --> engine
    fwd --> config
    tools --> app
    bench --> app
    engine --> strategy
    engine --> security
    engine --> store
    engine --> faces
    app --> ipc
    ipc --> engine
    discovery --> engine
    strategy --> transport
    faces --> transport
    store --> packet
    transport --> packet
    packet --> tlv

    embedded["ndn-embedded\n(no_std)"] -.-> tlv

    subgraph Research["Extensions"]
        sim["ndn-sim"]
        compute["ndn-compute"]
        sync["ndn-sync"]
        wasm_strat["ndn-strategy-wasm"]
    end

    sim -.-> engine
    compute -.-> engine
    sync -.-> app
    wasm_strat -.-> strategy

    style tlv fill:#79c0ff,color:#000
    style packet fill:#79c0ff,color:#000
    style embedded fill:#7ee787,color:#000

{
  "columns": [
    { "label": "Foundation", "nodes": [
        {"id": "ndn-tlv"}, {"id": "ndn-packet"}, {"id": "ndn-store"},
        {"id": "ndn-transport"}, {"id": "ndn-embedded"}
    ]},
    { "label": "Faces", "nodes": [
        {"id": "ndn-faces"}, {"id": "ndn-faces"},
        {"id": "ndn-faces"}, {"id": "ndn-faces"}
    ]},
    { "label": "Pipeline & Strategy", "nodes": [
        {"id": "ndn-engine"}, {"id": "ndn-strategy"}, {"id": "ndn-security"}
    ]},
    { "label": "Engine & App", "nodes": [
        {"id": "ndn-engine"}, {"id": "ndn-app"}, {"id": "ndn-ipc"},
        {"id": "ndn-config"}, {"id": "ndn-discovery"}
    ]},
    { "label": "Binaries", "nodes": [
        {"id": "ndn-fwd"}, {"id": "ndn-tools"}, {"id": "ndn-bench"}
    ]}
  ],
  "satellites": {
    "label": "Research  (depend on engine / app / strategy)",
    "nodes": [
        {"id": "ndn-sim"}, {"id": "ndn-compute"},
        {"id": "ndn-sync"}, {"id": "ndn-strategy-wasm"}
    ]
  },
  "edges": [
    ["ndn-tlv",       "ndn-packet"],
    ["ndn-tlv",       "ndn-embedded"],
    ["ndn-packet",    "ndn-store"],
    ["ndn-packet",    "ndn-transport"],
    ["ndn-transport", "ndn-faces"],
    ["ndn-transport", "ndn-faces"],
    ["ndn-transport", "ndn-faces"],
    ["ndn-transport", "ndn-faces"],
    ["ndn-faces",    "ndn-engine"],
    ["ndn-faces",  "ndn-engine"],
    ["ndn-faces", "ndn-engine"],
    ["ndn-faces",     "ndn-engine"],
    ["ndn-store",       "ndn-engine"],
    ["ndn-engine",    "ndn-strategy"],
    ["ndn-engine",    "ndn-security"],
    ["ndn-strategy",    "ndn-engine"],
    ["ndn-security",    "ndn-engine"],
    ["ndn-engine",    "ndn-ipc"],
    ["ndn-engine",    "ndn-discovery"],
    ["ndn-engine",      "ndn-fwd"],
    ["ndn-engine",      "ndn-tools"],
    ["ndn-engine",      "ndn-bench"],
    ["ndn-app",         "ndn-ipc"],
    ["ndn-app",         "ndn-tools"],
    ["ndn-app",         "ndn-bench"],
    ["ndn-config",      "ndn-fwd"]
  ],
  "satellite_edges": [
    ["ndn-sim",           "ndn-engine"],
    ["ndn-compute",       "ndn-engine"],
    ["ndn-sync",          "ndn-app"],
    ["ndn-strategy-wasm", "ndn-strategy"]
  ]
}

Installation

This page covers how to build ndn-rs from source and install its binaries.

Prerequisites

• Rust 2024 edition – install via rustup. The workspace uses edition = "2024", so you need a nightly or recent stable toolchain that supports it.
• cargo – ships with rustup.
• Linux or macOS – some face types (raw Ethernet, SHM) are Unix-only. The core library compiles on Windows but network tooling is limited.

Clone and build

git clone https://github.com/user/ndn-rs.git   # replace with actual URL
cd ndn-rs

# Build the entire workspace
cargo build

# Run all tests
cargo test

# Lint (treat warnings as errors)
cargo clippy -- -D warnings

# Format check
cargo fmt -- --check

Building the forwarder binary

The standalone forwarder lives in binaries/spec/ndn-fwd:

cargo build -p ndn-fwd

The compiled binary is at target/debug/ndn-fwd (or target/release/ndn-fwd with --release).

To build the CLI tools (ping, peek, put, ctl, traffic, iperf):

cargo build -p ndn-tools

This produces several binaries: ndn-ping, ndn-peek, ndn-put, ndn-ctl, ndn-traffic, and ndn-iperf.

Optional features

ndn-fwd features

The forwarder binary has three optional feature flags, all enabled by default:

To build without WebSocket support, for example:

cargo build -p ndn-fwd --no-default-features --features spsc-shm,serial

ndn-store features

The content store crate has an optional persistent backend:

Enable it from a dependent crate or when running benchmarks:

cargo test -p ndn-store --features fjall

Running the forwarder

Copy the example configuration and adjust it for your environment:

cp ndn-fwd.example.toml ndn-fwd.toml

# Start the forwarder (needs sudo for raw sockets / privileged ports)
sudo ./target/debug/ndn-fwd --config ndn-fwd.toml

The config file can also be specified via the NDN_CONFIG environment variable:

sudo NDN_CONFIG=ndn-fwd.toml ./target/release/ndn-fwd

The log level defaults to info and can be overridden at runtime:

sudo ./target/release/ndn-fwd --config ndn-fwd.toml --log-level debug

Or via the standard RUST_LOG environment variable:

sudo RUST_LOG=ndn_engine=debug ./target/release/ndn-fwd --config ndn-fwd.toml

See Running the Forwarder for a detailed configuration walkthrough.

Verifying the installation

After the forwarder starts, you should see log output indicating that faces are created and the pipeline is running. Use ndn-ctl to confirm the forwarder is alive:

ndn-ctl status

This connects to the forwarder’s management socket (default /run/nfd/nfd.sock) and prints forwarding engine state.

Hello World

A complete Interest/Data exchange in a single Rust program — no external router needed. InProcFace channel pairs connect consumer and producer through the full forwarding pipeline (PIT, FIB, CS, strategy) without touching the network.

sequenceDiagram
    participant C as Consumer
    participant E as ForwarderEngine
    participant P as Producer

    Note over C,P: InProcFace channel pairs — same mechanism used in production

    C->>E: Interest /ndn/hello
    Note over E: PIT entry created<br/>FIB → Producer face
    E->>P: Interest /ndn/hello
    P->>E: Data /ndn/hello "hello, NDN!"
    Note over E: PIT satisfied<br/>CS caches Data
    E->>C: Data /ndn/hello "hello, NDN!"

Dependencies

Add these to your Cargo.toml:

[dependencies]
ndn-app        = { path = "crates/spec/ndn-app" }
ndn-engine     = { path = "crates/spec/ndn-engine" }
ndn-faces = { path = "crates/spec/ndn-faces" }
ndn-packet     = { path = "crates/spec/ndn-packet", features = ["std"] }
ndn-transport  = { path = "crates/spec/ndn-transport" }
tokio          = { version = "1", features = ["rt-multi-thread", "macros"] }

If you are working within the ndn-rs workspace, use workspace = true instead of path dependencies.

Full example

use ndn_app::{Consumer, EngineBuilder, Producer};
use ndn_engine::EngineConfig;
use ndn_faces::local::InProcFace;
use ndn_packet::Name;
use ndn_packet::encode::DataBuilder;
use ndn_store::FibNexthop;
use ndn_transport::FaceId;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Create in-process face pairs.
    //    Each InProcFace::new() returns a face (for the engine) and a handle
    //    (for the application).  They are connected by an mpsc channel.
    let (consumer_face, consumer_handle) = InProcFace::new(FaceId(1), 64);
    let (producer_face, producer_handle) = InProcFace::new(FaceId(2), 64);

    // 2. Build the forwarding engine with both faces.
    let (engine, shutdown) = EngineBuilder::new(EngineConfig::default())
        .face(consumer_face)
        .face(producer_face)
        .build()
        .await?;

    // 3. Install a FIB route: Interests for /ndn/hello -> producer face.
    let prefix: Name = "/ndn/hello".parse()?;
    engine.fib().add_nexthop(&prefix, FibNexthop { face_id: 2, cost: 0 });

    // 4. Create Consumer and Producer from their handles.
    let mut consumer = Consumer::from_handle(consumer_handle);
    let mut producer = Producer::from_handle(producer_handle, prefix.clone());

    // 5. Spawn the producer in a background task.
    //    It loops, waiting for Interests and replying with Data.
    let producer_task = tokio::spawn(async move {
        producer
            .serve(|interest| {
                let name = (*interest.name).clone();
                async move {
                    let wire = DataBuilder::new(name, b"hello, NDN!").build();
                    Some(wire)
                }
            })
            .await
    });

    // 6. Consumer sends an Interest and waits for the Data reply.
    let data = consumer.fetch(prefix.clone()).await?;

    println!("Received Data: {}", data.name);
    println!("Content: {:?}", std::str::from_utf8(
        data.content().unwrap().as_ref()
    ));

    // 7. Clean shutdown: drop consumer/engine, then await the shutdown handle.
    drop(consumer);
    drop(engine);
    shutdown.shutdown().await;
    let _ = producer_task.await;

    Ok(())
}

Step-by-step walkthrough

1. Create InProcFace pairs

InProcFace::new(face_id, capacity) creates a face for the engine side and a handle for the application side, connected by a bounded channel. The capacity parameter controls backpressure – 64 is a good default.

2. Build the engine

EngineBuilder wires the PIT, FIB, content store, pipeline stages, and strategy table. Calling .face(f) registers a face with the engine. .build().await returns the running ForwarderEngine and a ShutdownHandle.

🔧 Implementation note: EngineBuilder uses sensible defaults for everything: LruCs for caching, BestRouteStrategy at the root prefix, and the standard Interest/Data pipeline stages. You only need to configure what you want to customize. The builder pattern ensures the engine is fully wired before it starts processing packets.

%%{init: {"layout": "elk"}}%%
graph TD
    EB["EngineBuilder::new(config)"]
    EB -->|".face(consumer_face)"| F1["Face: Consumer"]
    EB -->|".face(producer_face)"| F2["Face: Producer"]
    EB -->|"default"| CS["ContentStore (LruCs)"]
    EB -->|"default"| PIT["PIT (DashMap)"]
    EB -->|"default"| FIB["FIB (NameTrie)"]
    EB -->|"default"| ST["StrategyTable"]
    EB -->|"default"| PIPE["Pipeline Stages"]

    EB ==>|".build().await"| ENGINE["ForwarderEngine"]
    EB ==>|".build().await"| SH["ShutdownHandle"]

    ENGINE --- F1
    ENGINE --- F2
    ENGINE --- CS
    ENGINE --- PIT
    ENGINE --- FIB
    ENGINE --- ST
    ENGINE --- PIPE

    style EB fill:#e8f4fd,stroke:#2196F3
    style ENGINE fill:#c8e6c9,stroke:#4CAF50
    style SH fill:#fce4ec,stroke:#E91E63

3. Add a FIB route

The FIB maps name prefixes to outgoing faces. add_nexthop(&prefix, FibNexthop { face_id, cost }) tells the engine: “forward Interests matching this prefix to this face.” Cost is used when multiple nexthops exist (lower wins).

4. Consumer and Producer

• Consumer::from_handle(handle) wraps the application-side handle with methods like fetch() and get().
• Producer::from_handle(handle, prefix) wraps the handle with a serve() loop that dispatches incoming Interests to a callback.

5. The exchange

When consumer.fetch(name) is called, it builds an Interest packet, sends it through the InProcFace channel into the engine, which looks up the FIB, finds the producer face, and forwards the Interest. The producer’s serve() callback receives it, builds a Data packet, and sends it back through the engine to the consumer.

Connecting to an external router

If you have a running ndn-fwd instead of an embedded engine, applications connect via the router’s face socket:

use ndn_app::Consumer;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to the router's management socket.
    let mut consumer = Consumer::connect("/run/nfd/nfd.sock").await?;
    let data = consumer.fetch("/ndn/hello").await?;
    println!("Got: {:?}", data.content());
    Ok(())
}

This uses a Unix socket (with optional SHM data plane) instead of in-process channels, but the Consumer API is identical.

Next steps

• Running the Forwarder – deploy ndn-fwd as a standalone forwarder
• PIT, FIB, and Content Store – understand the data structures behind the exchange
• Pipeline Walkthrough – trace a packet through every pipeline stage

Running the Forwarder

This page explains how to configure and run ndn-fwd as a standalone NDN forwarder, connect applications and tools to it, and monitor its state.

Architecture overview

The forwarder is the central forwarding engine. Applications, remote peers, and management tools connect to it through various face types:

%%{init: {"layout": "elk"}}%%
graph TB
    subgraph "ndn-fwd"
        E[Forwarding Engine]
        PIT[PIT]
        FIB[FIB]
        CS[Content Store]
        E --- PIT
        E --- FIB
        E --- CS
    end

    subgraph "Local Applications"
        App1["ndn-ping<br/>(SHM + Unix socket)"]
        App2["Custom App<br/>(SHM + Unix socket)"]
    end

    subgraph "Remote Peers"
        R1["Router B<br/>(UDP 6363)"]
        R2["Router C<br/>(TCP 6363)"]
    end

    subgraph "Link-Local"
        MC["Multicast Peers<br/>(224.0.23.170:56363)"]
    end

    subgraph "Browser / Remote"
        WS["Web Client<br/>(WebSocket 9696)"]
    end

    subgraph "Management"
        CTL["ndn-ctl"]
        DASH["ndn-dashboard"]
    end

    App1 <-->|face socket| E
    App2 <-->|face socket| E
    R1 <-->|UDP| E
    R2 <-->|TCP| E
    MC <-->|UDP multicast| E
    WS <-->|WebSocket| E
    CTL -->|face socket| E
    DASH -->|WebSocket / NDN| E

Configuration file

ndn-fwd reads a TOML configuration file. Start from the provided example:

cp ndn-fwd.example.toml ndn-fwd.toml

The file is loaded via --config (or -c) or the NDN_CONFIG environment variable.

Minimal configuration

🎯 Tip: The three most impactful config options are cs_capacity_mb (how much RAM to dedicate to caching), the [[face]] entries (which transports to enable), and the [[route]] entries (where to forward Interests). Start with the minimal config below and add complexity as needed.

A minimal config to get started with UDP and multicast:

[engine]
cs_capacity_mb = 64

# UDP unicast face -- listen for incoming packets
[[face]]
kind = "udp"
bind = "0.0.0.0:6363"

# IPv4 multicast face -- link-local neighbor discovery
[[face]]
kind = "multicast"
group = "224.0.23.170"
port = 56363

# Static route: forward all /ndn Interests out the UDP face
[[route]]
prefix = "/ndn"
face = 0
cost = 10

[management]
transport = "ndn"
face_socket = "/run/nfd/nfd.sock"

[logging]
level = "info"

Full face type reference

UDP unicast

Point-to-point or open UDP face on port 6363 (the NDN default):

[[face]]
kind = "udp"
bind = "0.0.0.0:6363"
# Optional: restrict to a single remote peer
# remote = "10.0.0.1:6363"

TCP

Outbound connection to a remote router:

[[face]]
kind = "tcp"
remote = "192.168.1.1:6363"
# Optional: local bind address
# bind = "0.0.0.0:6363"

Multicast

Link-local neighbor discovery using the IANA-assigned NDN multicast group:

[[face]]
kind = "multicast"
group = "224.0.23.170"
port = 56363
# Optional: bind to a specific interface
# interface = "eth0"

Raw Ethernet multicast

Uses EtherType 0x8624 (IANA-assigned for NDN). Requires CAP_NET_RAW on Linux or root on macOS:

[[face]]
kind = "ether-multicast"
interface = "eth0"

Unix domain socket

Local app connectivity on Linux/macOS:

[[face]]
kind = "unix"
path = "/tmp/ndn-app.sock"

WebSocket

For browser clients or remote NDN-WS connections. Requires the websocket feature (enabled by default):

# Listen mode
[[face]]
kind = "web-socket"
bind = "0.0.0.0:9696"

# Or connect mode (mutually exclusive with bind)
# [[face]]
# kind = "web-socket"
# url = "ws://remote:9696"

Serial

Point-to-point over RS-232 / USB-serial. Requires the serial feature (enabled by default):

[[face]]
kind = "serial"
path = "/dev/ttyUSB0"
baud = 115200

Content store configuration

[cs]
variant = "lru"           # "lru", "sharded-lru", or "null"
capacity_mb = 64
# shards = 4              # only for "sharded-lru"
admission_policy = "default"  # "default" or "admit-all"

Static routes

Routes pre-load the FIB at startup. The face field is a zero-based index into the [[face]] list:

[[route]]
prefix = "/ndn"
face = 0
cost = 10

[[route]]
prefix = "/localhop"
face = 1
cost = 5

Routes can also be added at runtime via ndn-ctl.

Discovery

Enable neighbor discovery and service announcement:

[discovery]
node_name = "/ndn/site/router1"
profile = "lan"                          # "static", "lan", "campus", "mobile", etc.
served_prefixes = ["/ndn/site/sensors"]

Starting the forwarder

⚠️ Important: sudo is required when the forwarder uses raw sockets (Ethernet faces), privileged ports (UDP/TCP on port 6363 < 1024 on some systems), or multicast group membership. If you only use Unix socket faces and high-numbered ports, sudo is not needed. On Linux, you can alternatively grant CAP_NET_RAW and CAP_NET_BIND_SERVICE capabilities instead of running as root.

# Build in release mode for production
cargo build -p ndn-fwd --release

# Start (sudo required for raw sockets and privileged ports)
sudo ./target/release/ndn-fwd --config ndn-fwd.toml

Override the log level at runtime:

sudo ./target/release/ndn-fwd --config ndn-fwd.toml --log-level debug

# Or with RUST_LOG for per-crate control
sudo RUST_LOG="info,ndn_engine=debug,ndn_discovery=trace" \
    ./target/release/ndn-fwd --config ndn-fwd.toml

Connecting tools

ndn-ctl

ndn-ctl is the management CLI, similar to NFD’s nfdc. It connects to the forwarder’s face socket and sends management commands as NDN Interest/Data:

# Check forwarder status
ndn-ctl status

# List active faces
ndn-ctl face list

# Create a new UDP face at runtime
ndn-ctl face create udp4://192.168.1.1:6363

# Add a route
ndn-ctl route add /ndn --face 1 --cost 10

# List routes
ndn-ctl route list

# View content store info
ndn-ctl cs info

# List discovered neighbors
ndn-ctl neighbors list

# Announce / withdraw service prefixes
ndn-ctl service announce /ndn/myapp
ndn-ctl service withdraw /ndn/myapp

# Browse discovered services
ndn-ctl service browse

# Set forwarding strategy for a prefix
ndn-ctl strategy set /ndn --strategy /localhost/nfd/strategy/best-route

# Graceful shutdown
ndn-ctl shutdown

ndn-ping

Measure round-trip time to a named prefix. Run the server on one machine and the client on another (or the same machine):

# Server: register /ping and respond to ping Interests
sudo ndn-ping server --prefix /ping

# Client: send ping Interests and measure RTT
ndn-ping client --prefix /ping --count 10 --interval 1000

ndn-peek and ndn-put

Fetch or publish a single named Data packet:

# Fetch a packet by name
ndn-peek /ndn/example/data --timeout-ms 4000

# Publish a packet (another terminal)
ndn-put /ndn/example/data --content "hello"

ndn-iperf

Throughput measurement between two NDN endpoints:

# Server
sudo ndn-iperf server --prefix /iperf

# Client
ndn-iperf client --prefix /iperf --duration 10

Monitoring with ndn-dashboard

ndn-dashboard is a native desktop application (built with Dioxus) for managing and monitoring NDN forwarders. It communicates with the forwarder via the NDN management protocol over the face socket.

cargo build -p ndn-dashboard --release
./target/release/ndn-dashboard

The dashboard provides:

• Start Forwarder – launch ndn-fwd as a managed subprocess with one of:
  • Quick Start (built-in defaults)
  • Build Config – interactive config builder with startup faces, startup routes, CS settings, and log level
  • Load Config File – point to an existing TOML file
  • Saved Presets – one-click relaunch of saved configurations
• Overview – engine status, packet counters, throughput graphs
• Faces – active faces with per-face traffic statistics
• Routes – FIB entries and nexthop costs
• Content Store – cache occupancy and hit/miss rates
• Strategy – per-prefix forwarding strategy assignments
• Config – view and edit forwarder configuration; edit startup faces and routes; restart the managed forwarder with an updated config via ↺ Restart with Config
• Logs – real-time log viewer with filter and split-pane modes
• Tools – embedded ndn-ping, ndn-iperf, ndn-peek, and ndn-put
• Light/Dark mode – toggle via the ☀/🌙 button in the toolbar

The dashboard connects to the forwarder’s face socket (default /run/nfd/nfd.sock). If the forwarder is started through the dashboard, log output is captured in the Logs view automatically.

Typical deployment

A common LAN deployment with two forwarders and local apps:

# Router A (10.0.0.1) -- ndn-fwd.toml:
#   UDP face on :6363
#   Multicast face on 224.0.23.170:56363
#   Route /ndn -> UDP face
#   Discovery enabled with node_name = "/ndn/site/routerA"

# Router B (10.0.0.2) -- same config with:
#   remote = "10.0.0.1:6363" on the UDP face for a static tunnel
#   node_name = "/ndn/site/routerB"

# On Router A, start a ping server:
sudo ndn-ping server --prefix /ndn/site/routerA/ping

# From Router B, ping across the link:
ndn-ping client --prefix /ndn/site/routerA/ping --count 5

Next steps

• Installation – build options and feature flags
• Hello World – embedded engine tutorial
• Discovery Protocols – how neighbor and service discovery work
• Performance Tuning – optimize pipeline_threads, CS sharding, and SHM

Browser Demo (Dioxus)

Your first NDN node in the browser.

This walkthrough boots a small Dioxus app that compiles to WebAssembly, opens a [BrowserWebTransportFace] to a local forwarder, and exchanges real Interest/Data packets — both as a consumer (browser → host) and a producer (host → browser).

The demo crate lives at crates/tooling/dioxus-demo/.

Three commands

1. Start the forwarder.

   docker compose --profile demo -f testbed/docker-compose.yml \
     up dioxus-demo-fwd
   

   This boots ndn-fwd with a WebTransport listener on :4433 (self-signed loopback cert) and a UDP face on :6373 for the producer-round-trip witness.

2. Serve the Dioxus app.

   cd crates/tooling/dioxus-demo
   dx serve --release
   

   Open the URL dx serve prints (default http://127.0.0.1:8080/).

3. Use it.

   • The face panel shows connected once the WT handshake completes.

   • Type a name in the consumer panel and click Express Interest. The Data row populates with Name, ContentType, FreshnessPeriod, payload size, signature type, and RTT.

   • The producer panel shows the random /demo/<suffix> prefix the browser registered. Fetch it from the host:

     ndn-tools peek --face-uri udp://127.0.0.1:6373 \
       /demo/<suffix>/counter
     

     Each call increments the counter. This is the load-bearing proof that the browser is producing — not just consuming.

How it fits together

   browser tab (Dioxus, ndn-rs engine + BrowserWebTransportFace)
       │  WebTransport (QUIC datagrams, NDNLPv2)
       ▼
   dioxus-demo-fwd  ──UDP/TCP──▶  ndn-tools peek (host)

The face is the same BrowserWebTransportFace used by the Phase 3 unit-witness, so the wire framing the browser emits is byte-identical to what ndnd’s HTTP3 transport produces (SendDatagram / ReceiveDatagram).

Witnesses

Two Playwright specs exercise the demo end-to-end:

• testbed/tests/browser/dioxus_demo_e2e.spec.ts — consumer side; types a name, clicks Express Interest, asserts the Data panel renders.
• testbed/tests/browser/dioxus_demo_producer.spec.ts — producer side; asserts a host-side ndn-tools peek returns a counter that increments across two consecutive fetches.

Screenshots land in testbed/tests/audit/transcripts/.

NDN Overview for IP Developers

What If the Network Knew About Data?

Every network you have ever used works the same way: you ask to talk to a machine, and the network tries to connect you. “Send these bytes to 10.0.0.5.” The network does not know or care what those bytes mean – it just shuffles them toward an address. If the machine is down, you get nothing. If a copy of exactly what you need is sitting on a router one hop away, the network ignores it and dutifully tries to reach the original host anyway.

Named Data Networking starts from a different question: what if you could just ask for the data by name?

Instead of “connect me to host X,” you say “I need /ucla/papers/2024/ndn-overview.” Any node in the network that has a copy – the original producer, a router that cached it earlier, a nearby peer – can answer. The data itself carries a cryptographic signature from its producer, so it does not matter where it came from. You can verify it is authentic regardless.

This is not just a caching layer bolted onto IP. It is a fundamental architectural inversion: from “where is the host?” to “what is the data?” – and it changes everything about how forwarding, security, and multicast work.

NDN was conceived by Van Jacobson and developed into a full architecture by the NDN project team led by Lixia Zhang at UCLA, with collaborators across multiple universities and research labs.

The Core Shift: Addresses vs. Names

If you are coming from IP networking, the easiest way to feel the difference is to look at the same scenario through both lenses:

The following diagram illustrates the contrast. In IP, the router is stateless and oblivious to content. In NDN, the router maintains a Pending Interest Table (PIT), a Content Store (CS), and a Forwarding Information Base (FIB) – it understands what data flows through it.

flowchart LR
    subgraph IP["IP Model: Where do I send it?"]
        direction LR
        srcA["Host A\n10.0.0.1"] -->|"src: 10.0.0.1\ndst: 10.0.0.5"| routerIP["Router\n(stateless forward)"]
        routerIP -->|"src: 10.0.0.1\ndst: 10.0.0.5"| dstB["Host B\n10.0.0.5"]
        dstB -->|"response\nsrc: 10.0.0.5\ndst: 10.0.0.1"| routerIP
        routerIP --> srcA
    end

    subgraph NDN["NDN Model: What data do I need?"]
        direction LR
        consumer["Consumer"] -->|"Interest\n/app/video/frame1"| routerNDN["Router\n(PIT + CS + FIB)"]
        routerNDN -->|"Interest\n/app/video/frame1"| producer["Producer"]
        producer -->|"Data\n/app/video/frame1\n+ signature"| routerNDN
        routerNDN -->|"Data\n/app/video/frame1\n(cached for next request)"| consumer
    end

The Two Packet Types

NDN’s network layer has exactly two packet types. That is not a simplification for this overview – it is the actual design.

An Interest is a request: “I want the data named X.” A consumer sends it into the network, and the network figures out where to find a copy. A Data packet is the answer: “Here is the data named X, signed by producer Y.” It travels back along the exact reverse path the Interest took, because the network remembers where each Interest came from.

There is no separate routing protocol for return traffic, no connection state, and no session layer. The Interest leaves breadcrumbs (PIT entries) on its way in, and the Data follows them back out.

How Data Stays Trustworthy Without Trusted Channels

In IP, you secure the pipe: TLS encrypts the channel between two endpoints, so you trust the data because you trust the connection. But this breaks down when data is cached, replicated, or served by a third party. Who signed the TLS certificate for a CDN edge node you have never heard of?

NDN sidesteps this entirely. Every Data packet carries a cryptographic signature from its original producer. A cached copy served by a router three hops away is exactly as trustworthy as one served by the producer directly – the consumer verifies the signature against a trust schema and either accepts or rejects the data, regardless of where it came from.

In ndn-rs, this principle is encoded into the type system. The SafeData type can only be constructed after signature verification succeeds. Application callbacks receive SafeData, never raw unverified Data. The compiler itself prevents you from forwarding unverified content.

Inside the Forwarder

An NDN forwarder is more sophisticated than an IP router. Where an IP router has a single table (the routing table) and is stateless per-packet, an NDN forwarder maintains three core data structures that work together on every packet:

Content Store (CS): In-Network Caching

Every NDN forwarder – not just dedicated cache servers – can store Data packets it has forwarded and serve them to future Interests for the same name. When an Interest arrives and the CS has a match, the forwarder responds immediately without forwarding the Interest upstream. In ndn-rs, the CS is trait-based (ContentStore) with pluggable backends: LRU, sharded, and persistent (RocksDB/redb).

Pending Interest Table (PIT): Stateful Forwarding

When an Interest arrives and the CS does not have the data, the forwarder creates a PIT entry recording which face the Interest came from and forwards it upstream. If a second Interest for the same name arrives before the Data comes back, the forwarder simply adds the new face to the existing PIT entry – it does not forward a duplicate Interest. When the Data finally arrives, the forwarder sends it back to all faces listed in the PIT entry, then removes the entry.

This built-in aggregation is one of NDN’s most powerful features. It provides native multicast, loop prevention, and congestion control at the network layer.

Forwarding Information Base (FIB): Name-Based Routing

The FIB maps name prefixes to outgoing faces, just as an IP routing table maps address prefixes to next hops. The key difference is longest-prefix match on hierarchical names rather than IP addresses. In ndn-rs, the FIB is a name trie with HashMap<Component, Arc<RwLock<TrieNode>>> per level, enabling concurrent longest-prefix match without holding parent locks.

Strategy Layer: Adaptive Forwarding

Instead of a single forwarding algorithm, NDN allows per-prefix forwarding strategies. A strategy decides which nexthop(s) to use, whether to probe alternative paths, whether to retry on a different face after a timeout, or whether to suppress forwarding entirely. This makes NDN forwarding adaptive in a way that IP routing generally is not.

In ndn-rs, a name trie (parallel to the FIB) maps prefixes to Arc<dyn Strategy> implementations. Strategies receive an immutable StrategyContext and return a ForwardingAction.

Packet Flow: A Complete Example

Let us trace what happens when a consumer requests data, step by step. The first request goes all the way to the producer. The second request for the same data is satisfied from the router’s cache.

sequenceDiagram
    participant C as Consumer
    participant R as Router
    participant P as Producer

    Note over R: PIT and CS are empty

    C->>R: Interest /app/data/1
    Note over R: CS lookup: miss
    Note over R: PIT insert: record consumer face
    Note over R: FIB lookup: /app -> producer face
    R->>P: Interest /app/data/1

    P->>R: Data /app/data/1 [signed]
    Note over R: PIT match: found entry
    Note over R: CS insert: cache the Data
    Note over R: Forward to all PIT in-record faces
    R->>C: Data /app/data/1 [signed]

    Note over C: Verify signature against trust schema

    C->>R: Interest /app/data/1 (again)
    Note over R: CS lookup: hit!
    R->>C: Data /app/data/1 [from cache]
    Note over R: No PIT entry needed, no upstream forwarding

And here is how all three data structures cooperate within a single forwarder node. Notice how an Interest that hits the CS never touches the PIT or FIB, and how unsolicited Data (with no matching PIT entry) is dropped:

flowchart TD
    interest["Incoming Interest\n/app/video/frame1"] --> cs_check{"Content Store\n(CS)"}
    cs_check -->|"HIT: cached Data found"| reply["Return cached Data\nto incoming face"]
    cs_check -->|"MISS"| pit_check{"Pending Interest\nTable (PIT)"}
    pit_check -->|"Existing entry:\naggregate Interest\n(add in-record)"| suppress["Suppress\n(do not forward again)"]
    pit_check -->|"New entry:\ncreate PIT entry"| fib_lookup{"Forwarding Information\nBase (FIB)"}
    fib_lookup -->|"Longest-prefix match\n/app -> face 3, cost 10\n/app/video -> face 5, cost 5"| strategy["Strategy selects\nnexthop(s)"]
    strategy --> forward["Forward Interest\nupstream"]

    data["Incoming Data\n/app/video/frame1"] --> pit_match{"PIT Lookup"}
    pit_match -->|"No match"| drop["Drop\n(unsolicited)"]
    pit_match -->|"Match found"| cs_insert["Insert into CS"]
    cs_insert --> fan_out["Send Data to all\nPIT in-record faces"]
    fan_out --> consume["Remove PIT entry"]

NDN in Rust: Why the Fit Is Natural

If you have read this far, you might have noticed something: NDN’s architecture is full of shared ownership, concurrent access, and type-level safety guarantees. These are exactly the problems Rust’s ownership model and trait system are designed to solve.

ndn-rs is not a port of C++ code (like ndn-cxx/NFD) or Go code (like ndnd). It is a ground-up design that uses Rust’s strengths to express NDN concepts directly:

• Arc<Name> – names are shared across PIT, FIB, and pipeline stages without copying. Rust’s reference counting ensures they are freed exactly when no longer needed.
• bytes::Bytes – zero-copy slicing for TLV parsing and Content Store storage. A cached Data packet in the CS is the same allocation that came off the wire.
• DashMap for PIT – sharded concurrent access with no global lock on the hot path. Multiple pipeline tasks process packets in parallel without contention.
• PipelineStage trait – each processing step (decode, CS lookup, PIT check, strategy, dispatch) is a composable trait object. The pipeline is a fixed sequence of stages, optimized by the compiler.
• SafeData newtype – the compiler prevents unverified data from being forwarded. This is not a runtime check you might forget; it is a type error.
• Trait-based ContentStore – swap cache backends (LRU, sharded, persistent) without changing the pipeline.

The architecture is documented in detail in ARCHITECTURE.md, and the next pages in this section cover the Interest/Data lifecycle through the pipeline, the PIT, FIB, and CS data structures, and a glossary of NDN terms.

Further Reading

The foundational papers and resources for understanding NDN:

• Van Jacobson, Diana K. Smetters, James D. Thornton, Michael F. Plass, Nicholas H. Briggs, and Rebecca L. Braynard. “Networking Named Content.” Proceedings of the 5th ACM International Conference on Emerging Networking Experiments and Technologies (CoNEXT), 2009. – The paper that started it all.
• Lixia Zhang, Alexander Afanasyev, Jeffrey Burke, Van Jacobson, kc claffy, Patrick Crowley, Christos Papadopoulos, Lan Wang, and Beichuan Zhang. “Named Data Networking.” ACM SIGCOMM Computer Communication Review, 44(3):66-73, 2014. – The NDN project paper describing the full architecture.
• NDN Publications – The complete list of NDN project publications covering security, routing, applications, and more.
• named-data.net – The NDN project homepage.

Interest and Data Lifecycle

Every NDN packet that enters ndn-rs follows a carefully choreographed journey. Let’s trace an Interest from the moment it arrives as raw bytes to the moment matching Data flows back to the consumer.

The Pipeline Machine

At the core of this journey is a pipeline – a fixed sequence of PipelineStage trait objects determined at build time so the compiler can monomorphize the hot path. A runner loop drains a shared mpsc channel fed by all face tasks, picks up each packet, and drives it through the appropriate pipeline. There are no hidden callbacks or middleware chains; the runner simply matches on the Action returned by each stage and decides what happens next.

💡 Key insight: PacketContext is passed by value (moved) through each stage. This means ownership transfers at every step – a stage that short-circuits the pipeline consumes the context, and the compiler prevents any subsequent stage from accidentally using it. In C++, this invariant would require runtime checks; in Rust, it is a compile-time guarantee.

The stage contract is minimal:

#![allow(unused)]
fn main() {
pub trait PipelineStage: Send + Sync + 'static {
    fn process(
        &self,
        ctx: PacketContext,
    ) -> impl Future<Output = Result<Action, DropReason>> + Send;
}
}

And the Action enum gives each stage explicit control over what comes next:

#![allow(unused)]
fn main() {
pub enum Action {
    Continue(PacketContext),  // pass to next stage
    Send(PacketContext, SmallVec<[FaceId; 4]>),  // forward and exit
    Satisfy(PacketContext),   // satisfy PIT entries and exit
    Drop(DropReason),        // discard silently
    Nack(PacketContext, NackReason),  // send Nack to incoming face
}
}

The Traveling Context

Before we follow a packet through the pipeline, it helps to understand what it carries. A PacketContext is born the moment bytes arrive on a face, and it accumulates information as each stage does its work:

#![allow(unused)]
fn main() {
pub struct PacketContext {
    pub raw_bytes: Bytes,              // original wire bytes
    pub face_id:   FaceId,            // face the packet arrived on
    pub name:      Option<Arc<Name>>,  // None until TlvDecodeStage
    pub packet:    DecodedPacket,      // Raw -> Interest/Data after decode
    pub pit_token: Option<PitToken>,   // set by PitCheckStage
    pub out_faces: SmallVec<[FaceId; 4]>,  // populated by StrategyStage
    pub lp_pit_token: Option<Bytes>,  // LP PIT token echoed in responses
    pub cs_hit:    bool,
    pub verified:  bool,
    pub arrival:   u64,                // ns since Unix epoch
    pub tags:      AnyMap,             // extensible per-packet metadata
}
}

Notice that name starts as None – it won’t be populated until the TLV decode stage runs. This progressive population is deliberate: a Content Store hit can short-circuit the pipeline before expensive fields like nonce or lifetime are ever accessed.

flowchart LR
    FC["FaceCheck\n──────────\nface_id\nraw_bytes\narrival"]
    -->|"Continue"| DEC["TlvDecode\n──────────\nname\npacket"]
    -->|"Continue"| CS["CsLookup\n──────────\ncs_hit"]
    -->|"Continue"| PIT["PitCheck\n──────────\npit_token\nnonce check"]
    -->|"Continue"| STR["Strategy\n──────────\nout_faces\nFIB match"]
    -->|"Forward"| DSP["Dispatch\n──────────\nsend to\nout_faces"]

    style FC  fill:#e8f4fd,stroke:#2196F3
    style DEC fill:#e8f4fd,stroke:#2196F3
    style CS  fill:#fff3e0,stroke:#FF9800
    style PIT fill:#e8f4fd,stroke:#2196F3
    style STR fill:#f3e5f5,stroke:#9C27B0
    style DSP fill:#e8f5e9,stroke:#4CAF50

Now let’s follow an Interest through the full journey.

The Interest’s Journey

An Interest packet materializes on a face – perhaps a UDP datagram from a downstream consumer, or bytes pushed through an in-process InProcFace. Its journey begins.

flowchart TD
    A["Packet arrives on Face"] --> B["FaceCheck"]
    B -->|"face valid"| C["TlvDecode"]
    B -->|"face down/invalid"| X1["Drop"]
    C -->|"valid Interest"| D["CsLookup"]
    C -->|"malformed TLV"| X2["Drop"]
    D -->|"CS hit"| Y1["Send cached Data\nback to incoming face"]
    D -->|"CS miss"| E["PitCheck"]
    E -->|"duplicate nonce\n(loop detected)"| X3["Nack: Duplicate"]
    E -->|"existing PIT entry\n(aggregate)"| X4["Suppress\n(add in-record, do not forward)"]
    E -->|"new PIT entry"| F["Strategy"]
    F --> G{"ForwardingAction?"}
    G -->|"Forward"| H["Dispatch to\nnexthop face(s)"]
    G -->|"ForwardAfter"| I["Schedule delayed\nforward + probe"]
    G -->|"Nack"| X5["Nack to\nincoming face"]
    G -->|"Suppress"| X6["Drop\n(policy decision)"]

First contact: FaceCheck

The very first thing the forwarder does is verify that the face the packet arrived on is still alive. If the face has been torn down or is in the process of shutting down, there’s no point proceeding – the packet is dropped immediately. This is a cheap guard that prevents stale packets from wasting pipeline resources.

Making sense of the bytes: TlvDecode

With the face confirmed, the raw Bytes are parsed into a typed Interest struct. The context’s name field is populated with an Arc<Name>, giving subsequent stages a shared, zero-copy reference to the packet’s identity. Malformed TLV drops the packet here.

🔧 Implementation note: Fields like nonce and lifetime are decoded lazily via OnceLock<T>. They sit dormant inside the Interest struct, only computed when a later stage actually reads them. If the pipeline short-circuits before that happens, the CPU cycles are never spent.

The fast path: CsLookup

Now comes the moment that can make the entire rest of the pipeline irrelevant. The forwarder checks its Content Store for a cached Data packet matching this Interest’s name. If one is found, the cached wire-format Bytes are sent directly back to the incoming face. The pipeline short-circuits – no PIT entry is created, no FIB lookup occurs, no upstream forwarding happens.

📊 Performance: The CS short-circuit is the single most important optimization in the pipeline. A cache hit skips PIT insertion, FIB lookup, strategy invocation, and upstream forwarding – reducing a multi-stage pipeline to a hash lookup and a reference-count increment. With lazy OnceLock decoding, even the Interest’s nonce and lifetime fields are never parsed on this path.

Tracking the request: PitCheck

On a cache miss, the Interest reaches the Pending Interest Table. Here the forwarder must answer three questions at once. Has this exact Interest been seen before with the same nonce? If so, there’s a forwarding loop – the packet is Nacked with Duplicate. Is there already an outstanding PIT entry for this name from a different consumer? If so, the Interest is aggregated: its face is added as an in-record to the existing entry, but no new upstream Interest is sent. This is the mechanism behind NDN’s built-in multicast efficiency. Only if the entry is genuinely new does the Interest proceed to the next stage.

Deciding where to go: Strategy

For a fresh Interest that needs forwarding, the forwarder performs a longest-prefix match against the FIB to discover nexthop faces, then invokes the strategy assigned to that prefix. The strategy receives an immutable StrategyContext – it can observe the forwarder’s state but cannot mutate it – and returns a forwarding decision:

#![allow(unused)]
fn main() {
pub enum ForwardingAction {
    Forward(SmallVec<[FaceId; 4]>),
    ForwardAfter { faces: SmallVec<[FaceId; 4]>, delay: Duration },
    Nack(NackReason),
    Suppress,
}
}

Forward sends the Interest immediately. ForwardAfter enables probe-and-fallback patterns without the strategy needing to spawn its own timers – the forwarder handles the scheduling. Nack and Suppress end the journey here.

⚠️ Strategy isolation: Strategies cannot mutate global state. They receive a read-only snapshot and return a decision. This makes strategies safe to swap at runtime and prevents a buggy strategy from corrupting the FIB or PIT.

The final hop: Dispatch

The Interest is sent out on the selected nexthop face(s), and out-records are created in the PIT entry to track when each was sent. The Interest is now in flight, and the forwarder waits for a response.

The Satisfying Return: Data Pipeline

Somewhere upstream – perhaps one hop away, perhaps many – a producer or another router’s cache generates a Data packet matching the Interest. That Data now makes its way back through the network to our router.

flowchart TD
    A["Data arrives on Face"] --> B["FaceCheck"]
    B -->|"face valid"| C["TlvDecode"]
    B -->|"face down/invalid"| X1["Drop"]
    C -->|"valid Data"| D["PitMatch"]
    C -->|"malformed TLV"| X2["Drop"]
    D -->|"no PIT entry\n(unsolicited)"| X3["Drop"]
    D -->|"PIT match found"| E["Strategy\n(after_receive_data)"]
    E --> F["MeasurementsUpdate"]
    F --> G["CsInsert"]
    G --> H["Dispatch Data to\nall PIT in-record faces"]
    H --> I["Remove PIT entry"]

The Data’s journey begins with the same FaceCheck and TlvDecode stages that every packet passes through. But after decoding, the paths diverge.

Finding who asked: PitMatch

The forwarder looks up the PIT for an entry matching this Data’s name. If no entry exists, the Data is unsolicited – nobody asked for it, so it is dropped. This is a fundamental NDN security property: routers only accept Data that was explicitly requested. When a match is found, the PIT entry reveals which downstream faces are waiting for this content.

Learning from success: Strategy and Measurements

The strategy is notified that Data arrived via after_receive_data. This allows it to update its internal state – mark a path as working, cancel retransmission timers, adjust preferences. Then the MeasurementsUpdate stage computes per-face, per-prefix statistics: EWMA RTT (derived from the gap between the out-record’s send timestamp and this Data’s arrival) and satisfaction rate. These measurements feed back into future strategy decisions, letting the forwarder learn which paths perform best.

📊 Performance: Measurements are stored in a DashMap-backed MeasurementsTable, so updating statistics for one prefix never blocks lookups for another. The EWMA computation is a single multiply-and-add – negligible cost for valuable routing intelligence.

Caching for the future: CsInsert

Before the Data reaches its final recipients, it is inserted into the Content Store. The wire-format Bytes are stored directly – no re-encoding – so future cache hits can be served as zero-copy sends. The FreshnessPeriod is decoded once at insert time to compute a stale_at timestamp.

Delivering the payload: Dispatch

Finally, the Data is sent to every face listed in the PIT entry’s in-records. If three consumers requested the same content, all three receive it now. The PIT entry is consumed – removed from the table – and the lifecycle is complete.

The Power of Aggregation

The interplay between the Interest and Data pipelines reveals one of NDN’s most powerful properties. When multiple consumers request the same data, the PIT aggregates their Interests so that only a single Interest is forwarded upstream. When the Data returns, it fans out to all of them:

💡 Key insight: PIT aggregation is what makes NDN inherently multicast-friendly. Three consumers requesting the same video segment generate only one upstream Interest and one Data packet over the bottleneck link. The router’s PIT entry fans the Data out locally. This is fundamentally different from IP, where each consumer opens a separate connection and the same data traverses the network three times.

flowchart LR
    c1["Consumer 1"] -->|"Interest\n/app/data/1"| router["Router"]
    c2["Consumer 2"] -->|"Interest\n/app/data/1"| router
    c3["Consumer 3"] -->|"Interest\n/app/data/1"| router

    router -->|"Single Interest\n/app/data/1"| producer["Producer"]

    producer -->|"Data\n/app/data/1"| router2["Router"]

    router2 -->|"Data"| c1b["Consumer 1"]
    router2 -->|"Data"| c2b["Consumer 2"]
    router2 -->|"Data"| c3b["Consumer 3"]

    subgraph PIT Entry
        direction TB
        pit_name["Name: /app/data/1"]
        in1["InRecord: face 1 (Consumer 1)"]
        in2["InRecord: face 2 (Consumer 2)"]
        in3["InRecord: face 3 (Consumer 3)"]
        out1["OutRecord: face 4 (upstream)"]
    end

Consumer 1’s Interest arrives first and creates a new PIT entry. Consumer 2’s Interest for the same name finds the existing entry and is aggregated – an in-record is added, but no second Interest goes upstream. Consumer 3 is aggregated the same way. When the Data returns, the forwarder reads all three in-records and delivers the Data to each consumer. One upstream packet, three downstream deliveries.

When Things Go Wrong: The Nack Pipeline

Not every Interest finds its Data. Sometimes there is no route in the FIB. Sometimes the upstream path is congested. Sometimes the producer is unreachable. NDN handles these failures with Network Nacks – negative acknowledgements that flow back toward the consumer.

Nacks can be generated at two points in the Interest pipeline. A strategy that finds no viable nexthop returns ForwardingAction::Nack(reason), and any pipeline stage can return Action::Nack(ctx, reason) to signal a problem. The PitCheck stage does this when it detects a loop via duplicate nonce.

When a Nack arrives from upstream, it follows a shortened pipeline: decode, PIT match, and strategy notification. The strategy then faces a choice – try an alternative nexthop if one exists, or propagate the Nack downstream to the consumer. If no alternatives remain, the Nack flows back to every face in the PIT entry’s in-records, and the entry is removed.

⚠️ Nack propagation is conservative: A strategy will exhaust all available nexthops before propagating a Nack downstream. Only when every path has failed does the consumer learn that its Interest cannot be satisfied. This gives the network maximum opportunity to find the data through alternative routes.

The Full Picture

The two pipelines are symmetric and complementary. Interests flow upstream from consumer toward producer, driven by the FIB. Data flows downstream from producer toward consumer, guided by the PIT entries that Interests left behind. The Content Store sits at the junction, short-circuiting the loop when it can. And the strategy system ties it all together, learning from every Data arrival and every Nack to make better forwarding decisions over time.

This is the packet lifecycle in ndn-rs: a pipeline that is small enough to reason about stage by stage, yet powerful enough to express multicast aggregation, in-network caching, and adaptive forwarding – all without a single IP address in sight.

PIT, FIB, and Content Store

Three data structures answer three questions for every packet: CS — “Do I already have this data?”, PIT — “Is someone already looking for it?”, FIB — “Where should I look?”

Quick Reference

The Cooperation

When an Interest arrives, the forwarder consults all three in sequence. When Data returns, the PIT and CS work in concert to cache and deliver:

flowchart LR
    subgraph Interest Path
        I["Interest /a/b/c"] --> CS{"CS Lookup"}
        CS -->|miss| PIT{"PIT Check"}
        PIT -->|new entry| FIB{"FIB LPM"}
        FIB -->|"/a/b -> face 3"| OUT["Forward to face 3"]
    end

    subgraph Data Path
        D["Data /a/b/c"] --> PIT2{"PIT Match"}
        PIT2 -->|"in-records: face 1, face 2"| CS2["CS Insert"]
        CS2 --> SEND["Send to face 1, face 2"]
        PIT2 -->|"remove entry"| DONE["PIT entry consumed"]
    end

    OUT -.->|"Data returns"| D

Interest hits CS → miss → PIT records the requester → FIB finds the route → Interest goes upstream. Data returns → PIT reveals the waiting consumers → CS caches → Data fans out. Three structures, one fluid motion.

Content Store: “Do I Already Have This?”

The CS is the first structure consulted when an Interest arrives, and it has the power to end the pipeline immediately. If a cached Data packet matches the Interest, the forwarder sends it back to the consumer without ever touching the PIT or FIB. This short-circuit is the single most important optimization in the forwarding plane.

The Trait Abstraction

The CS is defined as a trait, not a concrete type. This means the pipeline doesn’t care how data is cached – only that the interface is honored:

#![allow(unused)]
fn main() {
pub trait ContentStore: Send + Sync + 'static {
    fn get(&self, interest: &Interest) -> impl Future<Output = Option<CsEntry>> + Send;
    fn insert(&self, data: Bytes, name: Arc<Name>, meta: CsMeta) -> impl Future<Output = InsertResult> + Send;
    fn evict(&self, name: &Name) -> impl Future<Output = bool> + Send;
    fn capacity(&self) -> CsCapacity;
}

pub struct CsEntry {
    pub data:    Bytes,  // wire-format, not re-encoded
    pub stale_at: u64,   // FreshnessPeriod decoded once at insert time
}
}

Three built-in backends implement this trait, each suited to different deployment scenarios.

LruCs is a byte-bounded LRU cache – the default choice for most deployments. When total cached bytes exceed the configured limit, the least recently used entries are evicted. It stores wire-format Bytes directly, so a cache hit sends the stored bytes to the face with no re-encoding or copying.

flowchart LR
    subgraph "LRU Content Store (byte-bounded)"
        direction LR
        MRU["Most Recently Used"]
        e1["/app/video/frame3\n512 bytes"]
        e2["/app/data/item7\n1024 bytes"]
        e3["/ndn/edu/paper\n2048 bytes"]
        e4["/app/video/frame1\n768 bytes"]
        LRU["Least Recently Used"]
        MRU ~~~ e1 --- e2 --- e3 --- e4 ~~~ LRU
    end

    new["New insert:\n/app/news/article\n1500 bytes"] -->|"Insert at head\n(MRU end)"| MRU
    LRU -->|"Evict from tail\nif over byte limit"| evicted["Evicted:\n/app/video/frame1"]

    style new fill:#d4edda,stroke:#28a745
    style evicted fill:#f8d7da,stroke:#dc3545

ShardedCs wraps any ContentStore implementation with sharding by name hash. Each shard is an independent instance of the inner store. When many pipeline tasks hit the CS concurrently, sharding ensures they don’t all contend on a single lock – the same principle that makes the PIT scale, applied here.

PersistentCs is backed by an on-disk key-value store (RocksDB or redb). It’s the right choice when the cache should survive restarts or when the dataset exceeds available memory. Its existence is invisible to the pipeline – the trait abstraction means swapping backends requires no code changes upstream.

Why Wire-Format Storage Matters

The CS stores Data as the original wire-format Bytes, not as decoded Rust structs. On a cache hit, those bytes are handed directly to face.send() with zero allocation and zero copying – Bytes uses reference-counted shared memory internally.

Note: Storing wire-format bytes instead of decoded structs means the CS cannot patch fields (e.g., decrementing a hop count) on cache hits. NDN Data packets are immutable and cryptographically signed – modifying them would invalidate the signature anyway – so wire-format storage avoids unnecessary re-encoding.

This design choice connects directly to the PIT: because the CS returns raw bytes, a cache hit bypasses not just the PIT and FIB, but also any decoding that would be needed to re-encode the Data for transmission. The pipeline stage that performs CsLookup simply returns Action::Send with the cached bytes – no further stages execute.

Pending Interest Table: “Is Someone Already Looking?”

If the CS can’t satisfy an Interest, the next question is whether another consumer has already asked for the same data. The PIT tracks every outstanding Interest that has been forwarded upstream but not yet satisfied. It is the bridge between the Interest and Data pipelines – Interests create PIT entries on the way up, and Data consumes them on the way down.

Structure

#![allow(unused)]
fn main() {
// Conceptual: DashMap keyed on PIT token hash
type Pit = DashMap<PitToken, PitEntry>;

pub struct PitEntry {
    pub name:        Arc<Name>,
    pub selector:    Option<Selector>,
    pub in_records:  Vec<InRecord>,
    pub out_records: Vec<OutRecord>,
    pub nonces_seen: SmallVec<[u32; 4]>,
    pub is_satisfied: bool,
    pub created_at:  u64,
    pub expires_at:  u64,
}

pub struct InRecord  { pub face_id: FaceId, pub nonce: u32, pub expiry: u64, pub lp_pit_token: Option<Bytes>, }
pub struct OutRecord { pub face_id: u32, pub last_nonce: u32, pub sent_at: u64 }
}

The PIT key is a PitToken derived from the Interest name and selectors. Two Interests for the same name but different MustBeFresh or CanBePrefix values produce distinct PIT entries, matching NDN semantics exactly.

Each entry maintains two lists. In-records track which downstream faces sent Interests – these are the faces that need to receive Data when it arrives. Out-records track which upstream faces the Interest was forwarded to – these provide the timestamps needed to compute round-trip time and detect forwarding failures.

Concurrency Without Compromise

The PIT is the hottest data structure in the forwarder. Every Interest and every Data packet touches it. A naive global mutex would serialize all packet processing onto a single core. ndn-rs uses DashMap instead.

📊 Performance: DashMap provides sharded concurrent access – internally it is a fixed number of RwLock<HashMap> shards. Different PIT entries hash to different shards, so operations on unrelated Interests never contend. A global mutex (as NFD uses) serializes all packet processing onto one core. DashMap’s sharded design means N cores can process N unrelated packets in parallel with zero contention. This is the single biggest architectural difference enabling multi-core scaling.

Loop Detection

Each Interest carries a random 32-bit nonce. When an Interest arrives and a PIT entry already exists for that name, the entry’s nonces_seen list is checked. If the nonce is already present, the Interest has looped back to a router it already visited – a forwarding loop. The forwarder responds with a Nack carrying the Duplicate reason code.

🔧 Implementation note: nonces_seen uses SmallVec<[u32; 4]> to keep the common case (1–4 nonces) on the stack. Most PIT entries see exactly one nonce and are satisfied quickly. Only in unusual aggregation scenarios does the vector spill to the heap.

The Lifecycle of a PIT Entry

A PIT entry is born when a new Interest passes the CS (miss) and PIT (no existing entry) checks. It lives through possible aggregation – additional consumers requesting the same data add their in-records. It dies in one of three ways: Data arrives and satisfies it, its lifetime expires, or a Nack propagates through it.

stateDiagram-v2
    [*] --> Created: Interest arrives,\nCS miss, no existing entry
    Created --> Pending: In-record added\nfor incoming face
    Pending --> Aggregated: Duplicate Interest\nfrom different face\n(add in-record)
    Aggregated --> Aggregated: More duplicates
    Pending --> Satisfied: Matching Data arrives\n(classical Interest)
    Aggregated --> Satisfied: Matching Data arrives\n(classical Interest)
    Satisfied --> [*]: Data sent to all\nin-record faces,\nentry removed
    Pending --> PersistentPending: Matching Data arrives\n(persistent Interest,\ncredit > 0)
    PersistentPending --> PersistentPending: More Data arrives,\ndecrement credit
    PersistentPending --> Satisfied: Credit exhausted
    Pending --> Expired: Interest lifetime\nelapsed, no Data
    Aggregated --> Expired: Interest lifetime\nelapsed, no Data
    PersistentPending --> Expired: Hard lifetime\n(reap_at) elapsed
    Expired --> [*]: Entry cleaned up\nby expiry reaper
    Pending --> Nacked: Upstream returns Nack,\nno alternative nexthops
    Nacked --> [*]: Nack propagated\ndownstream, entry removed

🔧 Implementation note: ndn-rs does not scan the entire PIT for expired entries on every tick. The expiry reaper drains entries whose expires_at <= now. Both classical (per InterestLifetime) and persistent (per reap_at) entries use the same field, so no separate scheduling is needed for persistent entries.

Persistent Interests

A persistent Interest keeps its PIT entry alive across multiple Data deliveries, enabling subscription-like patterns without application-layer polling. The requesting consumer embeds a SubscriptionRequest sub-TLV (type 0x230) inside the Interest’s ApplicationParameters:

SubscriptionRequest ::= TLV-TYPE(0x230) TLV-LENGTH(9)
                        version:u8          -- must be 1
                        max_data_count:u32  -- BE, upper bound on deliveries
                        max_lifetime_secs:u32 -- BE, hard deadline (≤ 3600 s)

When PitCheckStage sees a valid SubscriptionRequest, it authenticates the Interest via the configured Validator. If validation succeeds, a PersistentState is attached to the new PitEntry:

#![allow(unused)]
fn main() {
pub struct PersistentState {
    pub data_count_remaining: u32,  // decremented on each Data match
    pub reap_at: u64,               // absolute epoch-ns; entry forced-reaped here
}
}

PitMatchStage decrements data_count_remaining instead of removing the entry on each matching Data packet. The entry is removed only when the credit reaches zero, or when the expiry reaper fires at reap_at.

Graceful degradation: If no Validator is configured, or if the Interest’s signature does not pass validation, the entry is treated as a classical Interest — the SubscriptionRequest sub-TLV is silently ignored. This means persistent Interests are backward-compatible: forwarders that lack validation support still forward them as ordinary one-shot Interests.

The PIT’s connection to the other structures is direct and essential. It depends on the CS having already been checked (no point tracking an Interest the CS can satisfy). And when Data arrives, the PIT entry’s in-records tell the dispatch stage exactly where to send it – information that the FIB never had, because the FIB only knows about upstream paths, not about which downstream faces are waiting.

Forwarding Information Base: “Where Should I Look?”

When an Interest passes both the CS (miss) and PIT (new entry), the forwarder needs to decide where to send it. The FIB maps name prefixes to sets of nexthop faces, and a longest-prefix match (LPM) finds the best entry for any given name.

Structure

The FIB is a name trie where each node holds an optional FibEntry:

#![allow(unused)]
fn main() {
pub struct Fib(NameTrie<Arc<FibEntry>>);

pub struct FibEntry {
    pub nexthops: Vec<FibNexthop>,
}

pub struct FibNexthop {
    pub face_id: u32,
    pub cost: u32,
}
}

The Concurrent Trie

Each trie node uses HashMap<NameComponent, Arc<RwLock<TrieNode<V>>>>:

#![allow(unused)]
fn main() {
pub struct NameTrie<V: Clone + Send + Sync + 'static> {
    root: Arc<RwLock<TrieNode<V>>>,
}

struct TrieNode<V> {
    entry: Option<V>,
    children: HashMap<NameComponent, Arc<RwLock<TrieNode<V>>>>,
}
}

The Arc wrapper on each child node is the key to concurrency. When a thread performing LPM visits a child node, it grabs the child’s Arc, then releases the parent’s read lock. This hand-over-hand locking means concurrent lookups on different branches never contend after diverging from their common ancestor.

🔧 Implementation note: The Arc<RwLock<TrieNode>> per child is what makes the FIB a concurrent trie, not just a trie behind a lock. A lookup for /a/b/c grabs the Arc for node a, releases the root lock, then grabs the Arc for b, releases a’s lock, and so on. Two concurrent lookups on different branches (e.g., /a/b and /x/y) never contend after the root level.

Here’s how a FIB trie looks in practice, with green nodes holding actual nexthop entries:

%%{init: {"layout": "elk"}}%%
flowchart TD
    root["/ (root)"] --> ndn["/ndn"]
    ndn --> edu["/ndn/edu"]
    ndn --> com["/ndn/com"]
    edu --> ucla["/ndn/edu/ucla\n☑ nexthop: face 3, cost 10"]
    edu --> memphis["/ndn/edu/memphis\n☑ nexthop: face 5, cost 20"]
    edu --> mit["/ndn/edu/mit\n☑ nexthop: face 7, cost 15"]
    com --> google["/ndn/com/google\n☑ nexthop: face 2, cost 5"]
    ucla --> papers["/ndn/edu/ucla/papers"]
    ucla --> cs_dept["/ndn/edu/ucla/cs\n☑ nexthop: face 4, cost 8"]

    style ucla fill:#d4edda,stroke:#28a745
    style memphis fill:#d4edda,stroke:#28a745
    style mit fill:#d4edda,stroke:#28a745
    style google fill:#d4edda,stroke:#28a745
    style cs_dept fill:#d4edda,stroke:#28a745

Intermediate nodes like /ndn/edu exist only for trie structure – they have no entry. A lookup for /ndn/edu/ucla/papers/2024 walks the trie and returns the deepest match at /ndn/edu/ucla.

Longest-Prefix Match in Action

LPM walks the trie component by component, tracking the deepest node that has an entry. For a lookup of /a/b/c/d:

1. Read-lock root, check child a, clone its Arc, release root lock.
2. Read-lock node a, record its entry (if any), check child b, clone, release.
3. Continue until the name is exhausted or no child matches.
4. Return the deepest recorded entry.

This is O(k) where k is the number of name components, with each level holding a lock only briefly. The result – a set of nexthops with associated costs – is handed to the strategy, which makes the final forwarding decision.

💡 Key insight: The FIB only provides candidates. It says “these faces might lead to the data.” The strategy layer, informed by measurements the PIT helped gather (RTT from out-record timestamps, satisfaction rates from PIT entry outcomes), makes the actual choice. The FIB and PIT are connected not just through the pipeline, but through the feedback loop that makes forwarding adaptive.

The Three Together: A Complete Example

Let’s trace a concrete scenario to see all three structures in action.

A consumer sends an Interest for /app/video/segment-42. The forwarder’s CS is checked first – no cached copy exists. The PIT is consulted next – no existing entry, so a new one is created with an in-record for face 1 (the consumer’s face). The FIB performs LPM and finds a match at /app/video with nexthop face 5 (cost 10) and face 7 (cost 20). The strategy picks face 5, the cheaper path. An out-record is added to the PIT entry with the current timestamp, and the Interest goes out on face 5.

Seconds later, a second consumer on face 2 sends the same Interest. The CS still has nothing. But the PIT already has an entry – the Interest is aggregated. Face 2 is added as a second in-record. No second Interest goes upstream.

The producer responds with Data on face 5. The PIT entry is matched, revealing two in-records (faces 1 and 2). The out-record’s timestamp is used to compute RTT, which is fed into the measurements table. The Data is inserted into the CS for future cache hits. Then the Data is dispatched to both face 1 and face 2. The PIT entry is consumed and removed.

If a third consumer now requests the same segment, the CS has the answer immediately. The PIT and FIB are never consulted. The cached bytes flow directly back to the consumer.

Summary Table

Together, these three structures form a self-reinforcing system. The CS absorbs repeated requests, keeping them off the network. The PIT aggregates concurrent requests, preventing duplicate upstream traffic. The FIB directs new requests toward the right sources, guided by measurements that the PIT helped collect. No single structure works in isolation – their power comes from how they cooperate.

Identity, keys, and SafeBags

This page clears up the most-asked question on the security path:

If I enroll an identity in the browser, persist a SafeBag, and then want to talk to NFD as well, do I have a “split identity”? Why do we even pick an algorithm?

Short answer: no split. An NDN identity is a Name — under it you can have any number of keys, any number of algorithms. The SafeBag is one key bundle, not the identity. You pick the algorithm based on who needs to verify your signatures.

The model

identity   /alice              ← a Name; people / apps know you by this
   │
   ├── key  /alice/KEY/<id1>   ← one Ed25519 keypair under /alice
   │       └── cert            ← certificate issued for this key (self-signed
   │                              for testing, NDNCERT-issued in production)
   │
   └── key  /alice/KEY/<id2>   ← a second keypair, e.g. ECDSA-P256, under
           └── cert              the same /alice identity

An identity can carry many keys simultaneously. Each key has its own certificate. Both keys legitimately speak for /alice.

A SafeBag is the portable on-disk shape of one key:

• the encrypted private key (PKCS#8 PrivateKeyInfo, PBES2-wrapped)
• its certificate (a Data packet)

ndnsec export /alice produces a SafeBag for the active key under /alice. ndnsec import reverses it.

Why algorithm matters: who verifies?

Different NDN implementations support different signature types:

The ndn-cxx KeyType enum at security-common.hpp:106 is the authoritative list of what NFD can generate and verify today:

enum class KeyType { NONE = 0, RSA, EC, AES, HMAC };

No Ed25519, no BLAKE3. ndn-cxx’s wire decoder recognizes code 5 for display strings, but the security stack can’t verify it — tools/ndn-iperf.cpp:290 literally falls back when asked for Ed25519.

The practical guidance

You can also hold both — generate one key per algorithm under the same identity Name, store separate SafeBags, sign with whichever the consumer expects. No split identity; the Name /alice is the same.

What ndn-rs defaults to today

• KeyChain::ephemeral(name) — Ed25519 (the historical default).
• KeyChain::ephemeral_ecdsa(name) — ECDSA-P256.
• ndn-fwd auto-init: ECDSA-P256 since 2026-05-11, because the daemon’s mgmt responses need to be verifiable by whatever client shows up (often ndn-ctl but sometimes nfdc).
• dioxus-demo SharedWorker ephemeral fallback: ECDSA-P256 for consistency. An IdbPib-persisted Ed25519 SafeBag still wins via IdbPib::build_signer, which inspects the SafeBag’s algorithm OID and returns the matching Signer impl.

What IdbPib::build_signer does

#![allow(unused)]
fn main() {
let bag = pib.get_safebag(&key_name).await?;
match bag.algorithm(&passphrase)? {
    SafeBagAlgorithm::Ed25519   => Arc::new(Ed25519Signer::from_seed(seed, key_name)),
    SafeBagAlgorithm::EcdsaP256 => Arc::new(EcdsaP256Signer::from_pkcs8_der(&pkcs8, key_name)?),
    SafeBagAlgorithm::Other(oid) => return Err("unsupported OID"),
}
}

This is the path that lets a single persisted identity be reused across page-loads without baking the algorithm into the codebase.

Witness gates

After 2026-05-11 the engine fails closed if:

• A SafeBag carries an algorithm we can’t build a Signer for (SafeBagAlgorithm::Other).
• A SafeBag is present but the companion passphrase row is missing (storage corruption — the join flow always writes both atomically).

This is intentional: silently falling back to DigestSha256 would mask a real corruption.

What about RSA?

ndn-rs has RSA verification (via the rsa crate, default-features off so it stays wasm-clean) but no RsaSigner yet. Generating an RSA key in-browser is also expensive (slow keygen). Until a real consumer surfaces, RSA stays read-only. SafeBagAlgorithm::Other captures the OID so a future RSA path can dispatch off it without re-touching the public API.

Glossary

Terms used throughout the ndn-rs codebase and NDN literature. Organized alphabetically.

Action

Enum returned by each PipelineStage to control packet flow. Variants: Continue (pass to next stage), Send (forward to faces and exit), Satisfy (satisfy PIT entries), Drop (discard), Nack (send negative acknowledgement).

InProcFace

An in-process face that connects an application to the ndn-rs engine. Implemented as a pair of shared-memory ring buffers with a Unix socket control channel. Applications interact with the forwarder through InProcFace rather than opening network sockets.

CanBePrefix

An Interest selector indicating that the Interest name may be a proper prefix of the Data name. Without this flag, the Data name must exactly match the Interest name.

CS (Content Store)

A per-node cache of Data packets. Any router can serve a cached Data to a future Interest without forwarding upstream. In ndn-rs, CS is a trait (ContentStore) with pluggable backends: LruCs, ShardedCs, PersistentCs.

Data

One of the two NDN network-layer packet types. A Data packet carries a name, content, and a cryptographic signature. Data is always a response to an Interest and travels the reverse path.

Face

An NDN communication interface, analogous to a network interface in IP. A face can be a UDP tunnel, TCP connection, Ethernet link, Unix socket, in-process channel, or any transport that implements the Face trait (recv() + send()). Each face has a unique FaceId.

FaceId

A u32 identifier assigned to each face when it is created. Used throughout PIT records, FIB nexthops, and pipeline dispatch. Application code does not use raw FaceId values directly.

FIB (Forwarding Information Base)

Maps name prefixes to sets of nexthop faces with costs. Implemented as a NameTrie with Arc<RwLock<TrieNode>> per level for concurrent longest-prefix match. Analogous to an IP routing table.

ForwardingAction

Enum returned by a Strategy to tell the pipeline what to do with an Interest. Variants: Forward (send to faces), ForwardAfter (delayed forward for probing), Nack (reject), Suppress (do not forward).

FreshnessPeriod

A field in a Data packet specifying how long (in milliseconds) the Data should be considered “fresh” after arrival. Used by the CS to honor MustBeFresh selectors. Decoded once at CS insert time and stored as a stale_at timestamp.

HopLimit

An optional field in an Interest packet, decremented at each hop. When it reaches zero the Interest is dropped. Prevents Interests from looping indefinitely in misconfigured networks.

Interest

One of the two NDN network-layer packet types. An Interest packet carries a name and optional selectors (CanBePrefix, MustBeFresh, Nonce, Lifetime, HopLimit). It requests a Data packet matching the given name.

MustBeFresh

An Interest selector requesting that the returned Data must not be stale (its FreshnessPeriod must not have expired). A CS entry whose stale_at has passed will not satisfy a MustBeFresh Interest.

Nack (Network Nack)

A negative acknowledgement sent by a router when it cannot satisfy or forward an Interest. Carries a reason code (NoRoute, Congestion, Duplicate). Nacks travel the reverse Interest path, same as Data.

Name

A hierarchical identifier for NDN content. Composed of a sequence of NameComponent values. Example: /ndn/example/data/v1. In ndn-rs, names use SmallVec<[NameComponent; 8]> for stack allocation in the common case and are shared via Arc<Name>.

NameComponent

A single segment of an NDN name. Components are typed (GenericNameComponent, ImplicitSha256DigestComponent, ParametersSha256DigestComponent, etc.) and carry arbitrary bytes, not just UTF-8 strings.

NDNLPv2 (NDN Link Protocol v2)

A link-layer protocol that fragments, reassembles, and annotates NDN packets on a single hop. Carries hop-by-hop fields such as PIT tokens, Nack reasons, congestion marks, and fragmentation headers. In ndn-rs, NDNLPv2 headers are parsed before the packet enters the forwarding pipeline.

Nonce

A random 32-bit value carried in every Interest packet. Used for loop detection: if a PIT entry already contains the same nonce, the Interest is a loop and is Nacked. Stored in SmallVec<[u32; 4]> per PIT entry.

PacketContext

The per-packet state object passed by value through the pipeline. Contains raw bytes, decoded packet, face ID, name, PIT token, output face list, and extensible tags. Fields are populated progressively as stages execute.

PipelineStage

A trait representing one step in the forwarding pipeline. Each stage receives a PacketContext and returns an Action. Built-in stages are monomorphized for zero-cost dispatch; plugin stages use dynamic dispatch via BoxedStage.

PIT (Pending Interest Table)

Records outstanding Interests that have been forwarded but not yet satisfied. Keyed by name + selector hash. Implemented as a DashMap for sharded concurrent access. Each entry tracks in-records (downstream faces), out-records (upstream faces), and nonces seen.

PitToken

A hash derived from the Interest name and selectors, used as the PIT lookup key. Distinct from the NDNLPv2 wire-protocol PIT token (an opaque hop-by-hop value echoed in Data/Nack responses).

SafeData

A newtype wrapper around Data that can only be constructed by the Validator after successful signature verification. Application callbacks and the Content Store receive SafeData, not raw Data. This enforces at compile time that unverified data cannot be forwarded or consumed.

ShmFace

A shared-memory face for high-throughput communication between an application and the ndn-rs router on the same host. Uses a ring buffer in a shared memory segment with a Unix socket control channel for signaling.

Strategy

A per-prefix forwarding policy that decides how to handle Interests and Data. Implements the Strategy trait with methods like after_receive_interest and after_receive_data. Strategies receive an immutable StrategyContext and return ForwardingAction values. A name trie parallel to the FIB maps prefixes to strategy instances.

TrustSchema

A declarative specification of which keys are allowed to sign which names. Uses name pattern matching with capture groups. The Validator checks incoming Data against the trust schema before constructing SafeData.

Building NDN Applications

ndn-app provides two ways to connect an application to NDN: through an external router process, or with the forwarder engine embedded directly in your binary. The high-level API — Consumer, Producer, Subscriber, Queryable — is the same either way.

This guide walks through both modes with complete, runnable examples.

The Two Connection Modes

graph LR
    subgraph "External router mode"
        App1["your app"] -->|"Unix socket\n/run/nfd/nfd.sock"| R["ndn-fwd process"]
        R -->|"UDP / Ethernet"| Net["network"]
    end

    subgraph "Embedded engine mode"
        App2["your app"] -->|"in-process\nInProcFace"| E["ForwarderEngine\n(same process)"]
        E -->|"UDP / Ethernet"| Net2["network"]
    end

External router — ndn-fwd runs as a separate process. Your app connects to its Unix socket. This is the standard deployment: one router per host, many apps sharing it. Requires a running router.

Embedded engine — the ForwarderEngine lives inside your binary. There is no router process. The engine owns all faces and FIB state. This is the right choice for mobile apps, CLI tools, test harnesses, and any scenario where a separate process is inconvenient.

The Consumer and Producer types accept both connection variants behind an NdnConnection enum. The API surface is identical — switching between modes is a one-line change.

Mode 1: External Router

Add ndn-app to your Cargo.toml:

[dependencies]
ndn-app = { path = "crates/spec/ndn-app" }
tokio = { version = "1", features = ["full"] }

Consumer

use ndn_app::{Consumer, AppError};

#[tokio::main]
async fn main() -> Result<(), AppError> {
    let mut consumer = Consumer::connect("/run/nfd/nfd.sock").await?;

    // Fetch raw content bytes — the simplest call.
    let bytes = consumer.get("/example/hello").await?;
    println!("{}", String::from_utf8_lossy(&bytes));

    // Fetch the full Data packet (includes name, content, metadata).
    let data = consumer.fetch("/example/hello").await?;
    println!("name: {}", data.name());
    if let Some(content) = data.content() {
        println!("content: {} bytes", content.len());
    }

    Ok(())
}

fetch uses a 4-second Interest lifetime and a 4.5-second local timeout. For custom lifetimes, build the Interest wire yourself:

#![allow(unused)]
fn main() {
use std::time::Duration;
use ndn_packet::encode::InterestBuilder;

let wire = InterestBuilder::new("/example/sensor/temperature")
    .lifetime(Duration::from_millis(500))
    .must_be_fresh(true)
    .build();

let data = consumer.fetch_wire(wire, Duration::from_millis(600)).await?;
}

To set a hop limit, forwarding hint, or application parameters, use fetch_with. The local timeout is derived automatically from the Interest lifetime:

#![allow(unused)]
fn main() {
use ndn_packet::encode::InterestBuilder;

// Limit the Interest to 4 forwarding hops
let data = consumer.fetch_with(
    InterestBuilder::new("/ndn/remote/data").hop_limit(4)
).await?;

// Steer via a delegation prefix (forwarding hint)
let data = consumer.fetch_with(
    InterestBuilder::new("/alice/files/photo.jpg")
        .forwarding_hint(vec!["/campus/ndn-hub".parse()?])
).await?;

// ApplicationParameters — the ParametersSha256DigestComponent is
// computed and appended to the Name automatically
let data = consumer.fetch_with(
    InterestBuilder::new("/service/query")
        .app_parameters(b"filter=recent&limit=10")
).await?;
}

On the producer side these fields are accessible via the Interest argument:

#![allow(unused)]
fn main() {
producer.serve(|interest| async move {
    println!("hop limit: {:?}", interest.hop_limit());
    println!("params: {:?}", interest.app_parameters());
    println!("hints: {:?}", interest.forwarding_hint());
    // ...
    Some(response_wire)
}).await
}

Producer

use bytes::Bytes;
use ndn_app::{Producer, AppError};
use ndn_packet::{Interest, encode::DataBuilder};

#[tokio::main]
async fn main() -> Result<(), AppError> {
    // Register the prefix and start the serve loop.
    let mut producer = Producer::connect("/run/nfd/nfd.sock", "/example").await?;

    producer.serve(|interest: Interest| async move {
        let name = interest.name.to_string();
        println!("Interest for: {name}");

        // Return Some(wire_bytes) to respond, None to silently drop.
        let wire = DataBuilder::new((*interest.name).clone(), b"hello, NDN").build();

        Some(wire)
    }).await
}

The handler is async, so you can await database queries, file reads, or any other async work before returning the Data. Return None to drop the Interest without a response (the forwarder will Nack with NoRoute when the Interest times out).

Error handling

AppError has three variants:

#![allow(unused)]
fn main() {
match consumer.fetch("/example/data").await {
    Ok(data) => { /* use data */ }
    Err(AppError::Timeout) => {
        // No response within the timeout window.
        // The Interest either had no route or the producer didn't respond.
    }
    Err(AppError::Nacked { reason }) => {
        // The forwarder sent an explicit Nack (e.g. NoRoute).
        eprintln!("nacked: {:?}", reason);
    }
    Err(AppError::Engine(e)) => {
        // Connection error or protocol violation.
        eprintln!("engine error: {e}");
    }
}
}

Mode 2: Embedded Engine

The embedded mode builds a ForwarderEngine inside your process and connects Consumer/Producer to it via in-process InProcFace channel pairs. No Unix sockets, no separate process.

use ndn_app::{Consumer, Producer, EngineBuilder};
use ndn_engine::EngineConfig;
use ndn_faces::local::InProcFace;
use ndn_packet::{Name, encode::DataBuilder};
use ndn_transport::FaceId;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create one InProcFace for the consumer and one for the producer.
    // Each InProcFace::new returns the face (engine side) and its handle (app side).
    let (consumer_face, consumer_handle) = InProcFace::new(FaceId(1), 64);
    let (producer_face, producer_handle) = InProcFace::new(FaceId(2), 64);

    // Build the engine, registering both faces.
    let (engine, _shutdown) = EngineBuilder::new(EngineConfig::default())
        .face(consumer_face)
        .face(producer_face)
        .build()
        .await?;

    // Install a FIB route: Interests for /example go to the producer face.
    let prefix: Name = "/example".parse()?;
    engine.fib().add_nexthop(&prefix, FaceId(2), 0);

    // Build Consumer and Producer from their handles.
    let mut consumer = Consumer::from_handle(consumer_handle);
    let mut producer = Producer::from_handle(producer_handle, prefix);

    // Run the producer in a background task.
    tokio::spawn(async move {
        producer.serve(|interest| async move {
            let wire = DataBuilder::new((*interest.name).clone(), b"hello from embedded engine").build();
            Some(wire)
        }).await.ok();
    });

    // Fetch from the consumer — goes through the in-process engine.
    let bytes = consumer.get("/example/greeting").await?;
    println!("{}", String::from_utf8_lossy(&bytes));

    Ok(())
}

The embedded mode is useful for:

• Integration tests — spin up a full forwarding engine in #[tokio::test] without any external process
• Mobile / Android / iOS — ship the engine as part of your app binary; no system daemon required
• CLI tools — tools like ndn-peek and ndn-ping embed the engine so they work on machines that don’t have ndn-fwd running

Mobile shortcut: If you are targeting Android or iOS, use ndn-mobile instead of assembling EngineBuilder by hand. It pre-configures the engine with mobile-tuned defaults (8 MB CS, single pipeline thread, security enabled), exposes background suspend/resume lifecycle hooks, and provides Bluetooth face support. See the Mobile Apps guide.

Synchronous Applications

The blocking feature wraps Consumer and Producer in synchronous types that manage an internal Tokio runtime, following the same pattern as reqwest::blocking:

[dependencies]
ndn-app = { path = "crates/spec/ndn-app", features = ["blocking"] }

use ndn_app::blocking::{BlockingConsumer, BlockingProducer};

// No async, no #[tokio::main].
fn main() -> Result<(), ndn_app::AppError> {
    let mut consumer = BlockingConsumer::connect("/run/nfd/nfd.sock")?;
    let bytes = consumer.get("/example/hello")?;
    println!("{}", String::from_utf8_lossy(&bytes));
    Ok(())
}

BlockingProducer::serve takes a plain Fn(Interest) -> Option<Bytes> with no async:

#![allow(unused)]
fn main() {
let mut producer = BlockingProducer::connect("/run/nfd/nfd.sock", "/sensor")?;

producer.serve(|interest| {
    // Synchronous handler — called on the runtime thread.
    let reading = read_sensor();  // blocking I/O is fine here
    let wire = DataBuilder::new((*interest.name).clone(), reading.as_bytes()).build();
    Some(wire)
})?;
}

The blocking API is a good fit for Python extensions (ndn-python uses it internally), command-line tools, and any codebase that doesn’t use async.

Fetching with Security Verification

Consumer::fetch_verified validates the Data’s signature against a trust schema before returning it. The result is SafeData — a newtype that the compiler uses to enforce that only verified data reaches security-sensitive code.

#![allow(unused)]
fn main() {
use ndn_app::Consumer;
use ndn_security::KeyChain;

let keychain = KeyChain::open_or_create(
    std::path::Path::new("/etc/ndn/keys"),
    "/com/example/app",
)?;
let validator = keychain.validator();

let mut consumer = Consumer::connect("/run/nfd/nfd.sock").await?;
let safe_data = consumer.fetch_verified("/example/data", &validator).await?;

// safe_data is SafeData — the compiler knows it's been verified.
println!("verified: {}", safe_data.data().name());
}

If the certificate needed to verify the Data is not yet in the local cache, the validator expresses a side-channel Interest to fetch it. This happens transparently; fetch_verified waits for the certificate before returning.

Subscribe / Queryable

For datasets that change over time, Subscriber joins an SVS sync group and delivers new samples as they arrive. Queryable registers a prefix and handles request-response patterns more explicitly than Producer.

Subscriber

#![allow(unused)]
fn main() {
use ndn_app::{Subscriber, SubscriberConfig};

let mut sub = Subscriber::connect(
    "/run/nfd/nfd.sock",
    "/chat/room1",
    SubscriberConfig::default(),
).await?;

while let Some(sample) = sub.recv().await {
    println!(
        "[{}] seq {}: {:?}",
        sample.publisher,
        sample.seq,
        sample.payload,
    );
}
}

SubscriberConfig::auto_fetch (default true) automatically expresses an Interest for each sync update and populates sample.payload with the fetched bytes. Set it to false if you only need the name/seq and will fetch content selectively.

Queryable

#![allow(unused)]
fn main() {
use ndn_app::{Queryable, AppError};

let mut queryable = Queryable::connect("/run/nfd/nfd.sock", "/compute").await?;

while let Some(query) = queryable.recv().await {
    let name = query.interest().name().to_string();
    let result = compute_something(&name);

    let wire = DataBuilder::new(query.interest().name().clone())
        .content(result.as_bytes())
        .build_unsigned();

    query.reply(wire).await?;
}
}

Queryable differs from Producer in that the reply goes directly to the querying consumer via the engine’s PIT, without re-entering the producer’s serve loop. It is better suited to stateless request handlers that want explicit control over the response.

Putting It Together: A Complete Sensor App

This example shows a sensor producer and a monitor consumer running side-by-side against an external router.

use std::time::Duration;
use bytes::Bytes;
use ndn_app::{Consumer, Producer, AppError};
use ndn_packet::{Interest, encode::DataBuilder};
use tokio::time::sleep;

#[tokio::main]
async fn main() -> Result<(), AppError> {
    const SOCKET: &str = "/run/nfd/nfd.sock";
    const PREFIX: &str = "/ndn/sensor/temperature";

    // Spawn the producer in a background task.
    tokio::spawn(async move {
        let mut producer = Producer::connect(SOCKET, PREFIX).await?;
        producer.serve(|interest: Interest| async move {
            // Read a sensor value and build a Data response.
            let reading = format!("{:.1}", read_temperature());
            let wire = DataBuilder::new((*interest.name).clone(), reading.as_bytes())
                .freshness(Duration::from_secs(5))
                .build();
            Some(wire)
        }).await
    });

    // Give the producer a moment to register its prefix.
    sleep(Duration::from_millis(100)).await;

    // Poll the sensor every second from the consumer.
    let mut consumer = Consumer::connect(SOCKET).await?;
    loop {
        match consumer.get(PREFIX).await {
            Ok(bytes) => println!("temperature: {}°C", String::from_utf8_lossy(&bytes)),
            Err(AppError::Timeout) => eprintln!("no response"),
            Err(e) => return Err(e),
        }
        sleep(Duration::from_secs(1)).await;
    }
}

fn read_temperature() -> f32 { 23.5 }

Identity Management with NdnIdentity

ndn-identity provides a higher-level identity API that sits above the raw KeyChain. It manages certificate lifecycle, handles NDNCERT enrollment, and exposes a did() method that returns the W3C DID URI for the identity — all in a single type that persists across restarts.

Ephemeral Identities for Tests

NdnIdentity::ephemeral creates a throw-away identity entirely in memory. The key pair is generated fresh each time and is gone when the process exits. This is ideal for unit tests and integration tests where you want real signing behavior without touching the filesystem:

#![allow(unused)]
fn main() {
use ndn_identity::NdnIdentity;
use ndn_packet::encode::DataBuilder;

#[tokio::test]
async fn test_signed_producer() -> anyhow::Result<()> {
    // A fresh Ed25519 identity for this test run
    let identity = NdnIdentity::ephemeral("/test/sensor").await?;

    println!("test DID: {}", identity.did());
    // → did:ndn:test:sensor

    // Get a signer and sign a packet
    let signer = identity.signer()?;
    let wire = DataBuilder::new("/test/sensor/reading".parse()?, b"23.5°C")
        .sign(&*signer)
        .await?;

    // wire is now a signed Data packet whose key traces back to this identity
    Ok(())
}
}

Persistent Identities for Applications

NdnIdentity::open_or_create creates the identity (and persists it to disk) on first run, then loads it on subsequent runs without re-generating keys:

use std::path::PathBuf;
use ndn_identity::NdnIdentity;
use ndn_app::Producer;
use ndn_packet::{Interest, encode::DataBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // First run: generates key, creates self-signed cert, saves to /var/lib/ndn/sensor-id
    // Subsequent runs: loads existing key and cert from disk
    let identity = NdnIdentity::open_or_create(
        &PathBuf::from("/var/lib/ndn/sensor-id"),
        "/ndn/sensor/node42",
    ).await?;

    println!("Running as: {}", identity.name());
    println!("DID:        {}", identity.did());

    let signer = identity.signer()?;

    let mut producer = Producer::connect("/run/nfd/nfd.sock", "/ndn/sensor/node42").await?;

    producer.serve(move |interest: Interest| {
        // Clone the signer Arc for each handler invocation
        let signer = signer.clone();
        async move {
            let reading = format!("{:.1}", read_sensor());
            // Sign with the identity's key
            let wire = DataBuilder::new((*interest.name).clone(), reading.as_bytes())
                .sign(&*signer)
                .await
                .ok()?;
            Some(wire)
        }
    }).await?;

    Ok(())
}

fn read_sensor() -> f32 { 23.5 }

Advanced: Custom Validator

NdnIdentity implements Deref<Target = KeyChain>, so all KeyChain methods are available directly. For advanced scenarios — custom trust schemas, adding external trust anchors — use manager_arc() to access the underlying SecurityManager:

#![allow(unused)]
fn main() {
use ndn_identity::NdnIdentity;
use ndn_security::{Validator, TrustSchema};
use std::path::PathBuf;

let identity = NdnIdentity::open_or_create(
    &PathBuf::from("/var/lib/ndn/app-id"),
    "/example/app",
).await?;

// NdnIdentity Derefs to KeyChain — signer() and validator() are available directly
let signer = identity.signer()?;

// For advanced access, use manager_arc()
let mgr = identity.manager_arc();
let my_cert = mgr.get_certificate()?;
let validator = Validator::new(TrustSchema::hierarchical());
validator.cert_cache().insert(my_cert);

// ... use validator to verify incoming SafeData
}

For most applications identity.signer() covers the signing case and Consumer::fetch_verified covers the verification case. manager_arc() is the escape hatch for framework code that needs to share the manager across async tasks.

For factory provisioning with NDNCERT, see NdnIdentity::provision and the Fleet and Swarm Security guide.

Cargo Features

KeyChain lives in ndn-security and is re-exported by ndn-app for convenience.

Getting Started — Publish and Subscribe

This guide shows the two main ways to use ndn-rs:

1. Embedded — forwarder runs inside your process (no IPC, ~20 ns round-trip)
2. External — connect to a running ndn-fwd via Unix socket

Both modes share the same Consumer, Producer, and Subscriber API from ndn-app.

Prerequisites

# Cargo.toml
[dependencies]
ndn-app = "0.1"
tokio   = { version = "1", features = ["full"] }

Mode 1: Embedded (in-process forwarder)

No external router needed — ideal for testing, mobile apps, and embedded targets. The engine runs inside your process; InProcFace pairs replace IPC.

use ndn_app::{Consumer, EngineBuilder, Producer};
use ndn_engine::EngineConfig;
use ndn_faces::local::InProcFace;
use ndn_packet::{Name, encode::DataBuilder};
use ndn_transport::FaceId;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Create in-process face pairs: one for the consumer, one for the producer.
    let (consumer_face, consumer_handle) = InProcFace::new(FaceId(1), 64);
    let (producer_face, producer_handle) = InProcFace::new(FaceId(2), 64);

    // 2. Build the forwarding engine with both faces.
    let (engine, shutdown) = EngineBuilder::new(EngineConfig::default())
        .face(consumer_face)
        .face(producer_face)
        .build()
        .await?;

    // 3. Route Interests for /hello → the producer face.
    let prefix: Name = "/hello".parse()?;
    engine.fib().add_nexthop(&prefix, FaceId(2), 0);

    // 4. Producer: serve Data on request.
    let producer = Producer::from_handle(producer_handle, prefix.clone());
    tokio::spawn(async move {
        producer.serve(|interest, responder| {
            let name = (*interest.name).clone();
            async move {
                let wire = DataBuilder::new(name, b"Hello, NDN!").build();
                responder.respond_bytes(wire).await.ok();
            }
        }).await
    });

    // 5. Consumer: fetch /hello/world.
    let mut consumer = Consumer::from_handle(consumer_handle);
    let data = consumer.fetch("/hello/world").await?;
    println!("Received: {:?}", data.content());

    shutdown.shutdown().await;
    Ok(())
}

Mode 2: External (connect to ndn-fwd)

Start the forwarder first:

ndn-fwd --config /etc/ndn-fwd/config.toml
# or: ndn-fwd  # uses /run/nfd/nfd.sock by default

Then connect from your app:

use ndn_app::{Consumer, Producer, AppError};
use ndn_packet::Name;

const SOCKET: &str = "/run/nfd/nfd.sock";

#[tokio::main]
async fn main() -> Result<(), AppError> {
    // Producer side.
    let mut producer = Producer::connect(SOCKET, "/hello").await?;
    tokio::spawn(async move {
        producer.serve(|_interest, responder| async move {
            responder.respond_bytes(b"Hello from ndn-fwd!".to_vec().into()).await.ok();
        }).await;
    });

    // Consumer side (separate connection).
    let consumer = Consumer::connect(SOCKET).await?;
    let name: Name = "/hello/world".parse().unwrap();
    let data = consumer.fetch(&name).await?;
    println!("Received: {:?}", data.content());

    Ok(())
}

Publish/Subscribe (SVS sync)

Subscriber uses State Vector Sync to discover new publications without polling.

#![allow(unused)]
fn main() {
use ndn_app::Subscriber;

let mut sub = Subscriber::connect("/run/nfd/nfd.sock", "/chat/room1").await?;

while let Some(sample) = sub.recv().await {
    println!("[{}] seq={}: {:?}", sample.publisher, sample.seq, sample.payload);
}
}

To use PSync instead of SVS:

#![allow(unused)]
fn main() {
let mut sub = Subscriber::connect_psync("/run/nfd/nfd.sock", "/chat/room1").await?;
}

Next Steps

• Building NDN Apps — in-depth guide with error handling, signing, chunked transfer
• CLI Tools — ndn-peek, ndn-put, ndn-ping usage
• Implementing a Face — add a new transport
• Performance Tuning — SHM transport, CS sizing, pipeline threads

Application Patterns

This page maps common application design patterns to the ndn-rs APIs that implement them. Each pattern includes the recommended crate/type, and a short code snippet showing the key call.

Fetch Content Once

Fetch a named piece of content by name and wait for a response.

API: ndn_app::Consumer::get or Consumer::fetch

#![allow(unused)]
fn main() {
let mut consumer = Consumer::connect("/run/nfd/nfd.sock").await?;
let bytes = consumer.get("/example/data").await?;
}

To set a hop limit, forwarding hint, or application parameters, use Consumer::fetch_with with an InterestBuilder:

#![allow(unused)]
fn main() {
use ndn_packet::encode::InterestBuilder;

// Limit to 4 forwarding hops
let data = consumer.fetch_with(
    InterestBuilder::new("/ndn/remote/data").hop_limit(4)
).await?;

// Reach a producer via a delegation prefix (forwarding hint)
let data = consumer.fetch_with(
    InterestBuilder::new("/alice/files/photo.jpg")
        .forwarding_hint(vec!["/campus/ndn-hub".parse()?])
).await?;

// Parameterised fetch — ApplicationParameters triggers
// ParametersSha256DigestComponent auto-appended to the name
let data = consumer.fetch_with(
    InterestBuilder::new("/service/query")
        .app_parameters(b"filter=recent&limit=10")
).await?;
}

The local receive timeout is derived automatically from the Interest lifetime (+ 500 ms buffer). Call fetch_wire directly if you need a non-standard timeout.

Serve Content on Demand

Register a prefix and respond to Interests with dynamically generated Data.

API: ndn_app::Producer::connect + serve

#![allow(unused)]
fn main() {
let mut producer = Producer::connect("/run/nfd/nfd.sock", "/sensor").await?;
producer.serve(|interest| async move {
    Some(DataBuilder::new((*interest.name).clone(), b"42").build())
}).await
}

Subscribe to a Live Data Stream

Receive all new data published to a shared group prefix (SVS-based sync).

API: ndn_app::Subscriber

#![allow(unused)]
fn main() {
let mut sub = Subscriber::connect(
    "/run/nfd/nfd.sock",
    "/chat/room1",
    SubscriberConfig::default(),
).await?;
while let Some(sample) = sub.recv().await {
    println!(
        "[{}] {}",
        sample.publisher,
        String::from_utf8_lossy(&sample.payload.unwrap_or_default()),
    );
}
}

Request/Response (RPC-style)

Handle request-response pairs where each reply goes only to the querying consumer.

API: ndn_app::Queryable

#![allow(unused)]
fn main() {
let mut queryable = Queryable::connect("/run/nfd/nfd.sock", "/compute").await?;
while let Some(query) = queryable.recv().await {
    let result = do_work(query.interest());
    query.reply(
        DataBuilder::new(query.interest().name().clone())
            .content(result.as_bytes())
            .build_unsigned(),
    ).await?;
}
}

Transfer Large Content (Segmented)

Transfer content larger than a single packet, with automatic segmentation and reassembly.

API: ndn_app::ChunkedProducer + ChunkedConsumer

#![allow(unused)]
fn main() {
// Producer side
ChunkedProducer::connect(socket, "/files/report.pdf", &file_bytes).await?;

// Consumer side
let bytes = ChunkedConsumer::connect(socket).fetch("/files/report.pdf").await?;
}

Verify Content Before Use

Fetch Data and cryptographically verify it against a trust schema before use. The SafeData type ensures only verified data reaches sensitive code paths.

API: Consumer::fetch_verified + KeyChain

#![allow(unused)]
fn main() {
let keychain = KeyChain::load_or_init("/etc/ndn/keys").await?;
let safe_data = consumer
    .fetch_verified("/example/data", &keychain.validator().await?)
    .await?;
// safe_data: SafeData — compiler-enforced proof of verification
}

Embedded / Mobile (No External Router)

Run the full NDN forwarding engine inside your binary. No system daemon required.

For Android / iOS: use ndn_mobile::MobileEngine — a pre-configured wrapper with mobile-tuned defaults, lifecycle suspend/resume, and Bluetooth face support. See the Mobile Apps guide.

#![allow(unused)]
fn main() {
// ndn-mobile: one-liner setup, mobile-tuned defaults
use ndn_mobile::{Consumer, MobileEngine};

let (engine, handle) = MobileEngine::builder().build().await?;
let mut consumer = Consumer::from_handle(handle);
let mut producer = engine.register_producer("/my/prefix");
}

For desktop / testing: use ndn_app::EngineBuilder directly. See the Embedded Engine section.

#![allow(unused)]
fn main() {
use ndn_app::EngineBuilder;
use ndn_engine::EngineConfig;
use ndn_faces::local::InProcFace;
use ndn_transport::FaceId;

let mut builder = EngineBuilder::new(EngineConfig::default());
let app_face_id = builder.alloc_face_id();
let (face, handle) = InProcFace::new(app_face_id, 64);
let (engine, _shutdown) = builder.face(face).build().await?;
let mut consumer = ndn_app::Consumer::from_handle(handle);
}

Publish State to a Sync Group

Publish local state updates to a distributed sync group; all members receive updates.

API: ndn_sync::join_svs_group + SyncHandle

#![allow(unused)]
fn main() {
let sync = join_svs_group(&engine, "/chat/room1", "/ndn/mynode").await?;
sync.publish(b"hello everyone".to_vec()).await?;
while let Some(update) = sync.recv().await {
    println!("from {}: {:?}", update.name, update.data);
}
}

Custom Forwarding Strategy

Override the default forwarding decision for a name prefix.

API: ndn_strategy::Strategy trait + EngineBuilder::strategy

#![allow(unused)]
fn main() {
struct MyStrategy;
impl Strategy for MyStrategy {
    fn on_interest(&self, ctx: &StrategyContext, interest: &Interest) -> ForwardingAction {
        // Custom forwarding logic
        ForwardingAction::Forward(ctx.fib_lookup(interest.name()))
    }
    // on_nack and on_data_in omitted for brevity
}
let engine = EngineBuilder::new(config)
    .strategy("/my/prefix", MyStrategy)
    .build()
    .await?;
}

Peer Discovery and Auto-FIB

Discover NDN neighbors on the local network and automatically populate the FIB.

API: ndn_discovery::UdpNeighborDiscovery + EngineBuilder::discovery

#![allow(unused)]
fn main() {
let discovery = UdpNeighborDiscovery::new(config)?;
let engine = EngineBuilder::new(config)
    .discovery(discovery)
    .build()
    .await?;
// FIB entries for discovered neighbors are installed automatically
}

Integration Testing with Simulated Topology

Spin up a full forwarding engine in tests without any external processes or network.

API: ndn_sim::Simulation

#![allow(unused)]
fn main() {
let mut sim = Simulation::new();
let router = sim.add_router("r1");
let producer = sim.add_producer("p1", "/test");
sim.add_link(router, producer, LinkConfig::default());
let result = sim.send_interest(consumer, "/test/data").await?;
assert!(result.is_ok());
}

Synchronous / Non-Async Applications

Use NDN in blocking code (Python extensions, CLI tools, non-async Rust).

API: ndn_app::blocking::{BlockingConsumer, BlockingProducer}

#![allow(unused)]
fn main() {
let mut consumer = BlockingConsumer::connect("/run/nfd/nfd.sock")?;
let bytes = consumer.get("/example/hello")?;
}

Embedded / Constrained Devices (no_std)

Run a minimal forwarder on ARM Cortex-M or RISC-V with no heap allocator.

API: ndn_embedded::Forwarder (const-generic, no_std)

Refer to the Embedded Targets guide.

For a deeper walkthrough of the most common patterns, see Building NDN Applications.

Security Identity and Key Management

ndn-fwd requires a signing identity to sign Data packets and management responses. This guide explains how identity is provisioned, what happens when things go wrong, and how to manage keys with ndn-sec.

Identity resolution at startup

When ndn-fwd starts, it resolves a signing identity in priority order:

1. Configured identity — security.identity in ndn-fwd.toml points to a key name in the PIB at security.pib_path (default: ~/.ndn/pib/).
2. Ephemeral identity — if no identity is configured, or if the PIB fails to load, an in-memory Ed25519 key is generated. The name is taken from:
   • security.ephemeral_prefix (config), or
   • $HOSTNAME, or
   • pid-<pid> as a last resort.

An ephemeral identity is never written to disk. It is recreated on every restart, so Data signed with it cannot be verified after the process exits.

PIB error recovery

If an identity is configured but the PIB fails (missing directory, corrupt key file, permission error), ndn-fwd behaves differently depending on how it is running:

• Interactive (TTY): an interactive menu is presented:

  PIB error: <description>
  Options:
    [1] Generate a new key at <pib_path>
    [2] Continue with ephemeral identity (not persisted)
    [3] Abort
  Choice:
  

• Daemon (no TTY): the error is logged as a structured tracing event at ERROR level and the router falls back to ephemeral automatically.

Checking identity status

# From CLI (requires a running router)
ndn-ctl security identity-status

# Programmatically (MgmtClient)
let resp = mgmt_client.security_identity_status().await?;
// "identity=/ndn/myhost/KEY/abc is_ephemeral=false pib_path=/var/lib/ndn/pib"

The dashboard Security tab always shows a banner:

• Yellow — ephemeral identity; data cannot be verified after restart. The banner links to the config tab to set a persistent identity.
• Green — persistent identity loaded from PIB.

Managing keys with ndn-sec

# Generate a new anchor key
ndn-sec keygen --anchor /mynet/myhost

# Generate (skip if already exists — idempotent)
ndn-sec keygen --anchor --skip-if-exists /mynet/myhost

# List keys in the default PIB
ndn-sec list

# Use a custom PIB path
ndn-sec --pib /var/lib/ndn/pib list

# Export a certificate (DER)
ndn-sec export /mynet/myhost > myhost.ndnc

NixOS

On NixOS, / is read-only and DynamicUser = true is incompatible with persistent key storage. The ndn-rs NixOS module handles this automatically:

services.ndn-fwd = {
  enable = true;
  identity         = "/mynet/myhost";   # key name
  pibPath          = null;              # defaults to /var/lib/ndn-fwd/pib
  generateIdentity = true;              # run ndn-sec keygen on every boot (idempotent)
};

With generateIdentity = true, the service runs:

ndn-sec --pib /var/lib/ndn-fwd/pib keygen --anchor --skip-if-exists /mynet/myhost

before starting ndn-fwd. This is idempotent — if the key already exists the step is a no-op. Keys are persisted in /var/lib/ndn-fwd/pib/ (the StateDirectory), which survives reboots.

The module creates a stable ndn-fwd user and group to own the state directory and run the service.

Data validation and ContentStore admission

As of 2026-05-08, the ContentStore only admits Data that has passed the validation stage (ctx.verified = true). The trust verdict flows through PacketContext — the CS gate is independent of the admission policy (FreshnessPeriod check) and runs first.

Default validation profile: "default". When no [security] block is configured, the router uses AcceptSigned validation: any Data with a valid signature (DigestSha256 or stronger) is admitted; trust hierarchy is not enforced. Configure a [security] block with trust_anchor or trust_anchor_pib for full hierarchical validation.

Dev/lab opt-out: set validator_enabled = false to skip crypto verification. All incoming Data is then treated as permissive-verified so it can reach the CS. This removes the trust barrier — use only in isolated environments.

[security]
validator_enabled = false   # dev/lab only — no trust anchor required

Trust anchors and the validation profile are independent of validator_enabled. Setting validator_enabled = false overrides profile to "disabled" for the forwarding pipeline regardless of what profile says.

Configuration reference

[security]
identity          = "/mynet/myhost"       # key name; omit for ephemeral
pib_path          = "~/.ndn/pib"          # path to FilePib directory
pib_type          = "file"                # "file" | "memory"
ephemeral_prefix  = "/ndn/ephemeral"      # name prefix for ephemeral identity
validator_enabled = true                  # false = dev/lab, no trust anchor needed
profile           = "default"             # "default" | "accept-signed" | "disabled"

NDN on Android and iOS

ndn-mobile packages the NDN forwarding engine into a pre-configured crate tuned for Android and iOS. The forwarder runs inside the app process — no system daemon, no Unix sockets, no raw Ethernet faces. All app traffic uses in-process InProcFace channels (zero IPC overhead), while UDP faces handle LAN and WAN connectivity.

graph TD
    subgraph "Your Mobile App"
        C["Consumer / Producer"]
        A["InProcHandle (tokio mpsc)"]
        subgraph "MobileEngine"
            FWD["ForwarderEngine\n(FIB · PIT · CS)"]
            AF["InProcFace\n(in-process)"]
            MF["MulticastUdpFace\n(LAN 224.0.23.170)"]
            UF["UdpFace\n(unicast hub)"]
        end
    end
    NET["NDN network"]

    C <-->|"Interest / Data"| A
    A <--> AF
    AF <--> FWD
    FWD <--> MF
    FWD <--> UF
    MF <-->|"UDP multicast"| NET
    UF <-->|"UDP unicast"| NET

    style FWD fill:#2d5016,color:#fff
    style AF fill:#1a3a5c,color:#fff
    style MF fill:#1a3a5c,color:#fff
    style UF fill:#1a3a5c,color:#fff

When to Use ndn-mobile vs. Raw EngineBuilder

Use ndn-mobile when:

• You are targeting Android or iOS/iPadOS
• You want sensible mobile defaults (8 MB CS, single pipeline thread, full security validation) without assembling them from parts
• You need background suspend / foreground resume lifecycle hooks

Use raw EngineBuilder when:

• You are building a desktop router, simulation harness, or test fixture
• You need fine-grained control over every face (custom strategies, raw Ethernet, etc.)

Quick Start

Add ndn-mobile to your Cargo.toml:

[dependencies]
ndn-mobile = { path = "crates/extension/ndn-mobile" }
tokio = { version = "1", features = ["full"] }

Build the engine and fetch some content:

use ndn_mobile::{Consumer, MobileEngine};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (engine, handle) = MobileEngine::builder().build().await?;

    let mut consumer = Consumer::from_handle(handle);
    let data = consumer.fetch("/ndn/edu/example/data/1").await?;
    println!("got {} bytes", data.content().map_or(0, |b| b.len()));

    engine.shutdown().await;
    Ok(())
}

MobileEngine::builder() returns a [MobileEngineBuilder] with mobile-tuned defaults:

LAN Connectivity: UDP Multicast

To discover and exchange content with other NDN nodes on the same Wi-Fi network, add a multicast face pointing at the device’s local interface:

#![allow(unused)]
fn main() {
use std::net::Ipv4Addr;
use ndn_mobile::MobileEngine;

let wifi_ip: Ipv4Addr = "192.168.1.10".parse()?;

let (engine, handle) = MobileEngine::builder()
    .with_udp_multicast(wifi_ip)
    .build()
    .await?;
}

This joins the standard NDN multicast group 224.0.23.170:6363 on the specified interface. The face is created after build() returns, so it is immediately active.

On iOS, pass the current Wi-Fi interface IP obtained from NWPathMonitor or getifaddrs. On Android, use WifiManager.getConnectionInfo().getIpAddress().

Neighbor Discovery

When with_discovery is set alongside with_udp_multicast, the engine runs the NDN Hello protocol (SWIM-based) to discover other ndn-rs nodes on the LAN and populate the FIB automatically:

#![allow(unused)]
fn main() {
use std::net::Ipv4Addr;
use ndn_mobile::MobileEngine;

let (engine, handle) = MobileEngine::builder()
    .with_udp_multicast("192.168.1.10".parse()?)
    .with_discovery("/mobile/device/phone-alice")
    .build()
    .await?;
}

node_name identifies this device on the NDN network. DiscoveryProfile::Mobile is used automatically — it uses conservative hello intervals tuned for topology changes at human-movement timescales, with fast failure detection.

Calling with_discovery without with_udp_multicast logs a warning and silently disables discovery.

WAN Connectivity: Unicast UDP Peers

To connect to a known NDN hub (e.g. a campus router or testbed node):

#![allow(unused)]
fn main() {
use ndn_mobile::MobileEngine;

let hub: std::net::SocketAddr = "203.0.113.10:6363".parse()?;

let (engine, handle) = MobileEngine::builder()
    .with_unicast_peer(hub)
    .build()
    .await?;
}

Multiple unicast peers can be added; each becomes a Persistent UDP face.

Producing Data

register_producer allocates a new InProcFace, installs a FIB route, and returns a ready Producer — all synchronously, with no async overhead:

#![allow(unused)]
fn main() {
let mut producer = engine.register_producer("/mobile/sensor/temperature");

producer.serve(|interest| async move {
    let reading = read_sensor().to_string();
    let wire = ndn_packet::encode::DataBuilder::new(
        (*interest.name).clone(),
        reading.as_bytes(),
    ).build();
    Some(wire)
}).await?;
}

Call register_producer once per prefix. Each call creates an independent InProcFace — a producer registered on /a and one on /b are isolated and can run concurrently.

Multiple App Components

If several independent components in the same app (e.g. a background service and a UI layer) need their own NDN faces, use new_app_handle:

#![allow(unused)]
fn main() {
let (face_id, bg_handle) = engine.new_app_handle();
let (face_id2, ui_handle) = engine.new_app_handle();

// Install FIB routes for each component.
engine.add_route(&"/background/prefix".parse()?, face_id, 0);
engine.add_route(&"/ui/prefix".parse()?, face_id2, 0);

let mut bg_consumer = ndn_mobile::Consumer::from_handle(bg_handle);
let mut ui_consumer = ndn_mobile::Consumer::from_handle(ui_handle);
}

Background and Foreground Lifecycle

Mobile OSes aggressively restrict network I/O while apps are backgrounded. Call suspend_network_faces when the app moves to background and resume_network_faces when it returns to the foreground. The in-process InProcFace (and any active consumers / producers) remains fully functional throughout.

#![allow(unused)]
fn main() {
// Android: call from onStop() or onPause()
// iOS: call from applicationDidEnterBackground(_:) or sceneDidEnterBackground(_:)
engine.suspend_network_faces();

// ... app is in background; in-process communication still works ...

// Android: call from onStart() or onResume()
// iOS: call from applicationWillEnterForeground(_:) or sceneWillEnterForeground(_:)
engine.resume_network_faces().await;
}

suspend_network_faces cancels all network face tasks. resume_network_faces recreates the UDP multicast face (if one was configured) using the same FaceId, preserving the discovery module’s state.

Unicast peer faces are not automatically resumed — their socket addresses are not stored. Re-add them via engine.engine() after calling resume_network_faces.

Bluetooth NDN Faces

Bluetooth requires a platform-supplied connection. The Rust side accepts any async AsyncRead + AsyncWrite pair — you bridge from Android’s BluetoothSocket or iOS’s CBL2CAPChannel over FFI and wrap it with COBS framing:

#![allow(unused)]
fn main() {
use ndn_mobile::{bluetooth_face_from_parts, CancellationToken};

// reader and writer come from your platform bridge (JNI / C FFI).
let face = bluetooth_face_from_parts(
    engine.engine().faces().alloc_id(),
    "bt://AA:BB:CC:DD:EE:FF",
    reader,
    writer,
);

// Use network_cancel_token() so the face suspends with UDP faces on background.
engine.engine().add_face(face, engine.network_cancel_token().child_token());
}

bluetooth_face_from_parts uses COBS framing — the same codec as ndn-faces. COBS is correct for Bluetooth because RFCOMM and L2CAP are stream-oriented; 0x00 never appears in a COBS-encoded payload, making it a reliable frame boundary after a dropped connection.

Android (Kotlin → JNI)

1. Open a BluetoothSocket with createRfcommSocketToServiceRecord() and call connect().
2. Get the socket fd via getFileDescriptor() on the underlying ParcelFileDescriptor.
3. Pass the raw fd to Rust over JNI and wrap:

#![allow(unused)]
fn main() {
use std::os::unix::io::FromRawFd;
use tokio::net::UnixStream;

// SAFETY: fd is a valid, owned RFCOMM socket fd transferred from the JVM.
let stream = unsafe { UnixStream::from_raw_fd(raw_fd) };
let (r, w) = tokio::io::split(stream);
let face = bluetooth_face_from_parts(id, "bt://AA:BB:CC:DD:EE:FF", r, w);
}

iOS / iPadOS (Swift → C FFI)

1. Use CoreBluetooth to open an L2CAP channel (CBPeripheral.openL2CAPChannel) and retrieve the CBL2CAPChannel.
2. Bridge inputStream / outputStream to Rust via a socketpair(2) or a Swift-side copy loop.
3. Wrap the resulting fd in tokio::io::split and pass to bluetooth_face_from_parts.

Persistent Content Store

By default, the content store is an in-memory LRU cache that does not survive app restarts. To enable a persistent on-disk store, add the fjall feature and call with_persistent_cs:

[dependencies]
ndn-mobile = { path = "crates/extension/ndn-mobile", features = ["fjall"] }

#![allow(unused)]
fn main() {
let (engine, handle) = MobileEngine::builder()
    .with_persistent_cs("/data/user/0/com.example.app/files/ndn-cs")
    .build()
    .await?;
}

On iOS, to share the content store between your main app and extensions (widgets, share extensions) in the same App Group:

// Swift — resolve the App Group container path, pass to Rust over FFI
let url = FileManager.default
    .containerURL(forSecurityApplicationGroupIdentifier: "group.com.example.app")!
    .appendingPathComponent("ndn-cs")
rust_engine_set_cs_path(url.path)

On Android, use Context.getFilesDir() in Kotlin/Java and pass the path to Rust via JNI.

Security Profiles

The default security profile (SecurityProfile::Default) performs full chain validation — every Data packet’s signature is verified against its cert chain up to a trust anchor. For isolated test networks or local-only deployments, this can be relaxed:

#![allow(unused)]
fn main() {
use ndn_mobile::{MobileEngine, SecurityProfile};

// Accept any signed packet (verify signature, skip cert-chain fetch):
let (engine, _handle) = MobileEngine::builder()
    .security_profile(SecurityProfile::AcceptSigned)
    .build()
    .await?;

// Disable validation entirely (isolated test network only):
let (engine, _handle) = MobileEngine::builder()
    .security_profile(SecurityProfile::Disabled)
    .build()
    .await?;
}

Do not use Disabled in production; it allows any unsigned or improperly signed Data to be accepted and cached.

Tuning Pipeline Threads

The default of one pipeline thread minimises battery drain. If your app saturates the forwarder at high Interest/Data rates (e.g. a video-streaming producer), increase the thread count:

#![allow(unused)]
fn main() {
let (engine, handle) = MobileEngine::builder()
    .pipeline_threads(2)
    .build()
    .await?;
}

Profile first with cargo flamegraph or Android Profiler / Instruments before increasing this.

Platform Notes

Raw Ethernet, Unix socket IPC, and POSIX SHM faces are excluded because they require OS capabilities unavailable in the Android and iOS application sandboxes.

Cross-Compiling

Install the target toolchains:

# iOS device
rustup target add aarch64-apple-ios

# iOS simulator (Apple Silicon Mac)
rustup target add aarch64-apple-ios-sim

# Android arm64
rustup target add aarch64-linux-android
cargo install cargo-ndk

Build:

# iOS — requires Xcode and the iOS SDK
cargo build --target aarch64-apple-ios -p ndn-mobile

# Android — requires Android NDK r27+
cargo ndk -t arm64-v8a build -p ndn-mobile

# With persistent CS (fjall links C++)
cargo ndk -t arm64-v8a build -p ndn-mobile --features fjall

The CI workflow .github/workflows/mobile.yml runs cargo check against both targets on every push to main.

Complete Example: Mobile Sensor App

use std::net::Ipv4Addr;
use ndn_mobile::{Consumer, MobileEngine, SecurityProfile};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let wifi_ip: Ipv4Addr = get_wifi_ip(); // platform-specific

    let (engine, consumer_handle) = MobileEngine::builder()
        .with_udp_multicast(wifi_ip)
        .with_discovery("/mobile/device/my-phone")
        .security_profile(SecurityProfile::Default)
        .build()
        .await?;

    // Producer: serve temperature readings
    let mut producer = engine.register_producer("/mobile/sensor/temperature");
    tokio::spawn(async move {
        producer.serve(|interest| async move {
            let reading = read_sensor();
            let wire = ndn_packet::encode::DataBuilder::new(
                (*interest.name).clone(),
                reading.as_bytes(),
            ).build();
            Some(wire)
        }).await.ok();
    });

    // Consumer: fetch data from another node on the LAN
    let mut consumer = Consumer::from_handle(consumer_handle);
    let data = consumer.fetch("/mobile/device/other-phone/sensor/temp").await?;
    println!("remote temp: {:?}", data.content());

    engine.shutdown().await;
    Ok(())
}

fn get_wifi_ip() -> Ipv4Addr { "192.168.1.42".parse().unwrap() }
fn read_sensor() -> String { "23.5".into() }

Running ndn-rs on Embedded Targets

NFD requires a full Linux userspace. ndnd requires Go’s runtime with garbage collection. ndn-rs runs on a Cortex-M4 with 256 KB of RAM. Here is how.

The ndn-rs workspace was designed from the start to support bare-metal embedded targets alongside the full-featured Tokio-based forwarder. Three crates form the embedded stack: ndn-tlv and ndn-packet compile with no_std (they just need an allocator), and ndn-embedded provides a minimal forwarding engine that requires no heap allocator at all in its default configuration. No async runtime, no threads, no dynamic dispatch on the hot path – just a polling loop and fixed-size data structures.

graph TD
    subgraph "ndn-rs embedded stack"
        A["ndn-embedded<br/><i>Forwarder, FIB, PIT, CS, Face trait</i><br/><code>#![no_std]</code> always"]
        B["ndn-packet<br/><i>Interest, Data, Name, LpPacket</i><br/><code>no_std</code> via feature flag"]
        C["ndn-tlv<br/><i>TlvReader, TlvWriter, varint codec</i><br/><code>no_std</code> via feature flag"]
    end

    A --> B
    B --> C

    subgraph "Hardware"
        D["UART / SPI / LoRa / Ethernet MAC"]
    end

    A --> D

    style A fill:#2d5016,color:#fff
    style B fill:#1a3a5c,color:#fff
    style C fill:#1a3a5c,color:#fff
    style D fill:#5c3a1a,color:#fff

The no_std stack

ndn-tlv

ndn-tlv compiles without std when you disable the default feature:

ndn-tlv = { version = "...", default-features = false }

In this mode the crate still requires an allocator (for bytes::Bytes and BytesMut), but drops all std-specific dependencies. Everything works: TlvReader for zero-copy parsing, TlvWriter for encoding, and the read_varu64 / write_varu64 varint codec.

ndn-packet

ndn-packet follows the same pattern:

ndn-packet = { version = "...", default-features = false }

With std disabled, the crate drops two modules that require OS-level support:

Everything else compiles: Interest, Data, Name, NameComponent, MetaInfo, SignatureInfo, LpPacket, Nack. Names use SmallVec<[NameComponent; 8]>, so typical 4-8 component names stay on the stack.

Note: Both crates still require an allocator (extern crate alloc) because bytes::Bytes uses heap memory internally. If your target has no heap allocator, use ndn-embedded directly – its wire module encodes packets into caller-supplied &mut [u8] buffers with zero allocation.

The embedded forwarder

The ndn-embedded crate is the heart of the embedded story. It is #![no_std] unconditionally – there is no std feature to enable. It provides a single-threaded, synchronous Forwarder that processes one packet at a time in a polling loop.

Feature flags

In the default configuration (no features enabled), ndn-embedded requires no heap allocator. All data structures are backed by heapless::Vec with compile-time capacity limits.

How it works

The Forwarder is parameterized by three const generics and a clock type:

#![allow(unused)]
fn main() {
pub struct Forwarder<const P: usize, const F: usize, C: Clock> {
    pub pit: Pit<P>,    // P = max pending Interests
    pub fib: Fib<F>,    // F = max routes
    clock: C,           // monotonic millisecond counter
}
}

The processing model is straightforward. Your MCU main loop calls two methods:

• process_packet(raw, incoming_face, faces) – decodes one raw TLV packet, dispatches it as Interest or Data, performs FIB lookup / PIT insert / PIT satisfy, and calls face.send() on the appropriate outbound face.
• run_one_tick() – purges expired PIT entries using the supplied clock.

There is no async runtime, no task spawning, no channel multiplexing. The forwarder runs synchronously in whatever context you call it from – a bare loop {}, an RTOS task, or an Embassy executor.

Face abstraction

Faces use the nb::Result convention from embedded-hal:

#![allow(unused)]
fn main() {
pub trait Face {
    type Error: core::fmt::Debug;
    fn recv(&mut self, buf: &mut [u8]) -> nb::Result<usize, Self::Error>;
    fn send(&mut self, buf: &[u8]) -> nb::Result<(), Self::Error>;
    fn face_id(&self) -> FaceId;  // u8, 0-254
}
}

A face wraps whatever transport your MCU has: UART, SPI, LoRa, raw Ethernet MAC, or a memory-mapped buffer for inter-core communication. The ErasedFace trait provides dynamic dispatch so the forwarder can iterate over a heterogeneous slice of faces.

For serial links (UART, SPI, I2C), ndn-embedded includes a COBS framing module (cobs) that eliminates 0x00 bytes from the payload and uses 0x00 as a frame delimiter. This is compatible with the desktop stack’s ndn-faces framing.

Clock

The Clock trait supplies the monotonic millisecond counter for PIT expiry:

#![allow(unused)]
fn main() {
pub trait Clock {
    fn now_ms(&self) -> u32;  // wraps after ~49 days
}
}

Three implementations are provided:

• NoOpClock – always returns 0. PIT entries never expire (useful when you rely on FIFO eviction from a small PIT).
• FnClock(fn() -> u32) – wraps a function pointer to your hardware timer (SysTick, TIM2, etc.).
• Your own impl – for Embassy, RTIC, or any other framework.

Wire encoding without allocation

The wire module encodes Interest and Data packets directly into &mut [u8] stack buffers, bypassing ndn-packet’s BytesMut-based encoder entirely:

#![allow(unused)]
fn main() {
let mut buf = [0u8; 256];
// From raw components:
let n = wire::encode_interest(&mut buf, &[b"ndn", b"sensor", b"temp"], 42, 4000, false, false)
    .expect("buf too small");
// Or from a name string:
let n = wire::encode_interest_name(&mut buf, "/ndn/sensor/temp", 42, 4000, false, false)
    .expect("buf too small");
// Data packets:
let n = wire::encode_data_name(&mut buf, "/ndn/sensor/temp", b"23.5")
    .expect("buf too small");
}

Data packets are encoded with a DigestSha256 signature stub (type 0, 32 zero bytes). This produces well-formed packets that NDN forwarders accept and cache.

Supported targets

The embedded CI (.github/workflows/embedded.yml) validates the following builds on every push:

The crate is designed to also support RISC-V (riscv32imac-unknown-none-elf) and ESP32 (xtensa-esp32-none-elf) targets. The CI currently cross-compiles against thumbv7em-none-eabihf; additional targets can be added as the ecosystem matures.

Cross-compiling

Install the target toolchain and build:

# ARM Cortex-M4F (the CI-tested target)
rustup target add thumbv7em-none-eabihf
cargo build -p ndn-embedded --target thumbv7em-none-eabihf

# With optional content store
cargo build -p ndn-embedded --features cs --target thumbv7em-none-eabihf

# With heap allocator support
cargo build -p ndn-embedded --features alloc --target thumbv7em-none-eabihf

# RISC-V
rustup target add riscv32imac-unknown-none-elf
cargo build -p ndn-embedded --target riscv32imac-unknown-none-elf

The ndn-tlv and ndn-packet crates can be cross-compiled independently if you only need packet encoding/decoding without the forwarder:

cargo check -p ndn-tlv --no-default-features --target thumbv7em-none-eabihf
cargo check -p ndn-packet --no-default-features --target thumbv7em-none-eabihf

Memory budget

Every data structure in ndn-embedded has a compile-time size. There are no surprise heap allocations. Here is how to estimate your RAM usage.

PIT

Each PitEntry is 24 bytes:

A Pit<64> costs 64 x 24 = 1,536 bytes. For a simple sensor node, Pit<16> (384 bytes) is plenty. The PIT uses FIFO eviction when full – the oldest pending Interest is dropped first.

FIB

Each FibEntry is 16 bytes:

A Fib<8> costs 8 x 16 = 128 bytes. Most embedded nodes need only 2-4 routes (one default route, one per local prefix).

Content Store (optional)

The ContentStore<N, MAX_LEN> stores raw Data packet bytes in fixed-size arrays:

RAM = N * (MAX_LEN + 24 bytes overhead)

For example, ContentStore<4, 256> costs about 4 x 280 = 1,120 bytes. Enable the cs feature only if your node re-serves the same Data packets (e.g., a gateway caching upstream responses). Pure sensor nodes that produce unique readings every cycle should skip it.

Typical configurations

All of these fit comfortably in a Cortex-M4 with 64-256 KB of SRAM, leaving the bulk of memory for application logic, DMA buffers, and the stack.

Tip: The Forwarder struct itself is generic over P and F, so you can tune capacities per deployment without changing any code – just adjust the const generics at the instantiation site.

Example: sensor node producing temperature data

The following example shows a minimal sensor node that produces NDN Data packets containing temperature readings. It has two faces: a UART link to an upstream forwarder, and a local “app” face that generates Data in response to incoming Interests.

graph LR
    subgraph "Sensor MCU (Cortex-M4)"
        APP["App logic<br/><i>reads ADC, encodes Data</i>"]
        FW["ndn-embedded<br/>Forwarder&lt;16, 4, _&gt;"]
        UART_FACE["UART Face<br/>(face 0)"]
    end

    ROUTER["Upstream NDN<br/>forwarder"]

    ROUTER -- "Interest /ndn/sensor/temp" --> UART_FACE
    UART_FACE --> FW
    FW -- "FIB: /ndn/sensor -> app" --> APP
    APP -- "Data /ndn/sensor/temp" --> FW
    FW --> UART_FACE
    UART_FACE -- "Data (wire bytes)" --> ROUTER

    style FW fill:#2d5016,color:#fff
    style APP fill:#1a3a5c,color:#fff
    style ROUTER fill:#5c3a1a,color:#fff

#![no_std]
#![no_main]

use ndn_embedded::{Forwarder, Fib, FnClock, wire};
use ndn_embedded::face::{Face, FaceId};

// -- Hardware-specific face implementation (pseudocode) --

struct UartFace {
    // Your UART peripheral handle goes here
}

impl Face for UartFace {
    type Error = ();

    fn recv(&mut self, buf: &mut [u8]) -> nb::Result<usize, ()> {
        // Read from UART RX ring buffer; return WouldBlock if empty.
        // In practice, use COBS framing (ndn_embedded::cobs) to
        // delimit packets on the byte stream.
        Err(nb::Error::WouldBlock)
    }

    fn send(&mut self, buf: &[u8]) -> nb::Result<(), ()> {
        // Write to UART TX; COBS-encode before sending.
        Ok(())
    }

    fn face_id(&self) -> FaceId { 0 }
}

// -- Clock from SysTick --

fn read_systick_ms() -> u32 {
    // Read your MCU's millisecond counter
    0
}

// -- Main loop --

#[cortex_m_rt::entry]
fn main() -> ! {
    // Initialize hardware (UART, ADC, SysTick, etc.)
    let mut uart_face = UartFace { /* ... */ };

    // Set up the FIB: route everything under /ndn to face 0 (upstream).
    let mut fib = Fib::<4>::new();
    fib.add_route("/ndn", 0);

    // Create the forwarder with a 16-entry PIT and hardware clock.
    let clock = FnClock(read_systick_ms);
    let mut fw = Forwarder::<16, 4, _>::new(fib, clock);

    // Packet buffers
    let mut rx_buf = [0u8; 512];
    let mut tx_buf = [0u8; 512];

    loop {
        // 1. Poll the UART face for incoming packets.
        if let Ok(n) = uart_face.recv(&mut rx_buf) {
            let mut faces: [&mut dyn ndn_embedded::face::ErasedFace; 1] =
                [&mut uart_face];
            fw.process_packet(&rx_buf[..n], 0, &mut faces);
        }

        // 2. If we received an Interest for our prefix, produce Data.
        //    (In a real application, you'd check whether the Interest
        //    matched /ndn/sensor/temp and read the ADC.)
        let temperature = b"23.5";
        if let Some(n) = wire::encode_data_name(
            &mut tx_buf,
            "/ndn/sensor/temp",
            temperature,
        ) {
            let _ = uart_face.send(&tx_buf[..n]);
        }

        // 3. Expire stale PIT entries.
        fw.run_one_tick();
    }
}

This is a simplified sketch. A production sensor node would:

• Use COBS framing (ndn_embedded::cobs) to delimit NDN packets on the UART byte stream.
• Only produce Data when an Interest actually matches (check the PIT or inspect the Interest name).
• Use a hardware RNG or counter for the Interest nonce when the node itself sends Interests upstream.
• Optionally enable the content store (features = ["cs"]) if the same reading is requested multiple times within its freshness period.

The key point is that the entire NDN stack – TLV parsing, FIB longest-prefix match, PIT loop detection, packet forwarding – runs in under 2 KB of RAM with no heap allocator, no async runtime, and no operating system.

Browser WebSocket Interop Testing

ndn-rs includes a browser-based integration test suite that verifies NDN packet exchange between NDNts running inside a real Chromium browser and the ndn-rs forwarder over WebSocket.

Why browser tests?

The ndn-fwd WebSocket face is the primary transport for browser-based NDN applications. Unit and integration tests in Rust can verify the Rust side, but they cannot exercise the browser’s native WebSocket API and the JavaScript NDN stack in the same way a real browser can. Playwright automates a headless Chromium instance, giving confidence that:

• NDNts WsTransport successfully connects to ndn-fwd’s WS face.
• Interest forwarding works across two independent browser WS connections.
• PIT aggregation deduplicates concurrent browser Interests correctly.

Test topology

browser page A (NDNts producer)
    │  WebSocket (ws://localhost:9797)
    ▼
ndn-fwd  ← started as a subprocess by the test
    │  WebSocket (ws://localhost:9797)
    ▼
browser page B (NDNts consumer)

Both pages connect to the same ndn-fwd instance on different WebSocket connections. Page A registers a prefix via the NFD management protocol (rib/register) and produces Data. Page B fetches the Data by name. ndn-fwd routes the Interest from B → A and the Data back from A → B.

Running locally

Prerequisites: Rust toolchain, Node.js ≥ 20, a release build of ndn-fwd.

# Build ndn-fwd
cargo build --release --bin ndn-fwd

# Install Node deps and build the NDNts browser bundle
cd testbed/tests/browser
npm install
node build.mjs

# Install Playwright's Chromium browser
npx playwright install chromium

# Run the tests (ndn-fwd is started automatically)
npm test

# Watch test output in a real browser window
npm run test:headed

NDNts bundle

build.mjs uses esbuild to bundle the following NDNts packages into fixture-page/ndnts.bundle.js as a browser IIFE (window.NDNts):

The bundle is gitignored and must be rebuilt after npm install.

Test scenarios

CI

The workflow .github/workflows/browser.yml runs on:

• Push / PR touching the WebSocket face, ndn-fwd, or browser test code.
• Weekly cron (Monday 04:00 UTC) to catch NDNts upstream changes.
• Manual dispatch.

It builds ndn-fwd --release, installs Playwright, bundles NDNts, and runs the Playwright tests. The Playwright HTML report is uploaded as a CI artifact on failure.

Extending the tests

Add new scenarios to ws-transport.spec.ts. Common patterns:

// Open a fresh browser context per role to avoid shared JS state.
const ctx = await browser.newContext();
const page = await ctx.newPage();
await openPage(page);          // loads fixture page, waits for NDNts bundle

// Start a producer (sends rib/register, waits 600 ms for propagation).
await startProducer(page, '/my/prefix', 'my-content');

// Consume from another page.
const content = await fetchData(consumerPage, '/my/prefix');
expect(content).toBe('my-content');

await ctx.close();

To test TLS WebSocket (wss://), configure ndn-fwd with a [[face]] kind = "web-socket" and a tls sub-table, and change WS_URL in the spec to a wss:// URL with { rejectUnauthorized: false } in the Playwright launch options.

WebTransport face

ndn-fwd ships a server-side WebTransport listener (issue #14). Browsers and other WT clients open a session, and the forwarder treats each session as a face — one NDN packet per QUIC datagram, NDNLPv2-framed.

TOML configuration

[listeners.webtransport]
enabled      = true
listen       = "0.0.0.0:443"
cert_source  = { type = "acme", directory_url = "https://acme-v02.api.letsencrypt.org/directory", email = "ops@example.com", domain = "router.example.com", dns_provider = "cloudflare", params = { api_token = "<token>", zone_id = "<zone>" }, cache_dir = "/var/lib/ndn-fwd/acme" }

cert_source accepts three shapes:

The localhost-cert caveat

Browsers refuse self-signed WT certs by default. Two options for local development:

1. serverCertificateHashes — generate a short-lived (≤14 days) cert, compute its SHA-256 digest, pass that digest to the browser via the WebTransport constructor’s options bag. This is the workflow yoursunny describes in the issue thread.
2. Real cert from a public CA — use cert_source = { type = "acme", … } with a domain you control. Let’s Encrypt rate limits apply (50/week per registered domain); the cert cache under cache_dir keeps you well below that.

DNS-01 providers

ndn-acme ships with a Cloudflare implementation (dns_provider = "cloudflare"). Other providers implement the DnsProvider trait — RFC 2136 nsupdate, Route 53, etc. — and are linked in by operators.

Witnesses

• testbed/tests/audit/i14_wt_loopback.sh — loopback round-trip via wtransport self-signed identity.
• testbed/tests/audit/acme_dns01.sh — full ACME order against Pebble running in Docker.

Browser-side interop (Playwright) lands in phase 3 of the WASM rollout.

WebTransport face — browser client

The ndn-face-webtransport-wasm crate produces a BrowserWebTransportFace that an ndn-rs engine running inside a browser tab — or any wasm32-unknown-unknown target — can use to dial out to the server-side WebTransport listener documented in webtransport.md.

Direction is always outbound. The W3C WebTransport API does not expose an “accept inbound session” surface in the browser, so this face never listens. Wire framing matches the server side and NDNts @ndn/quic-transport: one NDN packet per QUIC datagram, NDNLPv2 envelope.

Build targets

The native backend is wired in so the crate’s loopback unit witness can drive the same Face impl against a Phase 2 listener without spinning up a real browser.

From a Rust-to-WASM app

#![allow(unused)]
fn main() {
use std::sync::Arc;
use ndn_runtime::{Runtime, default_runtime};
use ndn_transport::{Face, FaceId};
use ndn_face_webtransport_wasm::BrowserWebTransportFace;

async fn run() -> Result<(), Box<dyn std::error::Error>> {
let runtime = default_runtime();

// `serverCertificateHashes` workflow: pass the SHA-256 digest of the
// server's self-signed DER cert. For production deployments behind a
// real CA, pass an empty slice and the browser uses WebPKI.
let cert_hash: [u8; 32] = [/* sha256(server.der) */ 0; 32];

#[cfg(target_arch = "wasm32")]
let face = BrowserWebTransportFace::connect(
    FaceId(0),
    "https://router.example.com/ndn",
    &[cert_hash],
    runtime,
).await?;

#[cfg(target_arch = "wasm32")]
face.send(/* an NDN Interest as Bytes */ bytes::Bytes::new()).await?;
Ok(()) }
}

The face holds a single pump task that owns the underlying xwt session; sending and receiving across the Face trait both go through mpsc channels so the JS-handle session never has to satisfy Send + Sync itself.

Why datagrams instead of streams

Same answer as the server side. NDN packets are self-contained TLV objects, the forwarder retransmits when the strategy decides to, and a reliable QUIC stream would add head-of-line blocking on the WT layer for no benefit.

Witnesses

• Native: crates/extension/ndn-face-webtransport-wasm/tests/native_xwt_roundtrip.rs — listener + face in-process via xwt-wtransport, audit script testbed/tests/audit/wasm_wt_browser_face.sh.
• Browser: Playwright spec under testbed/tests/browser/ (Phase 4 bundles this into the Dioxus demo end-to-end run).

WebRTC Datachannel Face

The WebRTC face turns ndn-rs from “browser-as-client” into “browser-as-peer”. Two browser tabs (or browser ↔ native) exchange NDN Interests and Data over a reliable, ordered SCTP datachannel with no NDN forwarder in the path.

This is the load-bearing transport for serverless NDN applications: every browser tab is a forwarding node, peer-to-peer exchange happens directly, and the only infrastructure required is a one-shot signaling rendezvous.

Crate: ndn-face-webrtc. Public API: WebRtcConnector, WebRtcFace, RtcChannel.

How it fits

peer A ───── SCTP / DTLS / UDP ───── peer B
   │                                    │
   └── (one-time) signaling rendezvous ─┘

The signaling rendezvous is short-lived: peers swap an SDP offer + answer pair (and any trickle-ICE candidates) once, the SCTP datachannel comes up, and the rendezvous server is no longer needed. Bytes flow peer-to-peer for the rest of the session.

STUN, TURN, NAT

WebRTC needs at least one STUN server to discover its public-facing address when peers are behind NAT. The default is two of Google’s public STUN endpoints; that is sufficient for the common cases (home routers, mobile networks, most office Wi-Fi).

Symmetric NAT (corporate firewalls, some cellular carriers) defeats STUN — direct UDP between peers is impossible and the connection times out. The fix is a TURN relay, which forwards encrypted UDP between the peers. TURN is opt-in because operators must supply credentials:

#![allow(unused)]
fn main() {
use ndn_face_webrtc::{IceServers, TurnServer};

let servers = IceServers {
    stun: vec!["stun:stun.l.google.com:19302".into()],
    turn: vec![TurnServer {
        url: "turn:turn.example.com:3478".into(),
        username: "user".into(),
        credential: "secret".into(),
    }],
};
}

For testbed deployments behind a symmetric NAT, the repo’s docker compose ships a coturn service.

Signaling

WebRTC peers must swap SDP descriptions and ICE candidates out of band before the datachannel comes up. The transport for those bytes is up to the application.

Manual paste-into-Slack

The simplest possible signaling. Used for the integration test and one-off demos. Zero infrastructure.

#![allow(unused)]
fn main() {
use ndn_face_webrtc::{IceServers, WebRtcConnector};
use ndn_face_webrtc::signaling::manual::{Bundle, encode_bundle, decode_bundle};

let connector = WebRtcConnector::new(IceServers::default())?;

// peer A
let (offer, pending) = connector.create_offer().await?;
let blob = encode_bundle(&Bundle { description: offer, candidates: vec![] })?;
println!("paste this to peer B: {blob}");

// peer A receives an answer blob over Slack
let answer_blob = read_from_slack();
let answer_bundle: Bundle = decode_bundle(&answer_blob)?;
let face = connector.finalize_with_answer(pending, answer_bundle.description).await?;
}

HTTP relay (follow-up phase)

A tiny axum binary mediates one-shot rendezvous over HTTP POST

• GET. The test harness uses it for browser↔native and browser↔browser playwright runs.

NDN-native signaling — deferred

The “obvious” fit would be /<peer>/rtc-offer over an NDN face. This is a chicken-and-egg problem: NDN-native signaling requires the peers to already share a discovery face, which is what WebRTC is bootstrapping. A future phase can add this once we have a clearer answer to “what does an existing face look like when neither peer trusts any forwarder yet.”

Trust model

WebRTC encrypts the datachannel via DTLS with an ephemeral self-signed cert per session. DTLS is the link layer; NDN signatures are the trust layer. Every Data packet carries a signature that chains to a configured trust anchor exactly the same way it would on UDP or WebTransport. The DTLS fingerprint is not bound to NDN identity — that complication is unnecessary as long as ndn-rs is the one consuming both sides.

Try it: two-tab demo (manual signaling)

The dioxus-demo crate ships a “WebRTC Peer” panel that exercises the wasm WebRtcConnector end-to-end. No relay needed — the two tabs paste SDP+ICE bundles between each other.

1. Boot the demo forwarder + serve the demo app:

   sudo target/release/ndn-fwd -c testbed/configs/dioxus-demo-fwd.toml
   cd crates/tooling/dioxus-demo && dx serve --release
   

2. Open the printed URL in two browser tabs.
3. In tab A, scroll to the WebRTC Peer panel and click Create offer. Copy the offer bundle from the textarea.
4. In tab B, paste the bundle into the Paste peer’s offer box, then click Accept offer. Copy the answer bundle.
5. Back in tab A, paste the answer bundle into Paste peer’s answer, then click Finalize with answer. Both tabs should show “connected”.
6. Click Send ping on either side. The other tab will echo it back via the on-channel auto-reply, and you’ll see recv: pong: ping from dioxus-demo in the message line.

This is the load-bearing witness that the wasm WebRtcConnector works at runtime — every web_sys callback fires, the closure bag stays alive long enough, and the SDP/ICE round-trip lands.

Witness status

See docs/notes/webrtc-design-2026-05-07.md for the design rationale and current witness status.

SharedWorker Face

The SharedWorker face is a deployment optimization for browser-tier ndn-rs: instead of one engine instance per tab, one engine instance per origin is shared across every tab the user has open of that origin. WebTransport sessions, WebRTC peerings, the Pending Interest Table, and the Content Store are all amortized across tabs.

Crate: ndn-face-shared-worker. Public API: [SharedWorkerProxyFace] (tab side), [WorkerListener] + [WorkerPortFace] + [init_worker_scope] (worker side).

When to use

Pick the SharedWorker face when:

• A user typically has more than one tab of your application open at once. Without SharedWorker, every tab pays the WebTransport or WebRTC + ICE + DTLS handshake tax independently. With it, every tab after the first is connection-free.
• You want tab B to benefit from tab A’s recent fetches via the shared Content Store.
• You want a did:ndn enrollment + signing identity that survives tab navigation as long as any tab from the origin remains open.

Skip the SharedWorker face when:

• Your application is genuinely single-tab. The extra layer of message-passing buys you nothing.
• You need the engine to outlive all tabs being closed. The SharedWorker dies when its last connected port closes — see Lifecycle below.
• Browser support matters more than the optimization. Safari shipped buggy SharedWorker support for years; the first cut of the witnesses pin to Chromium for that reason.

Architecture

┌─────────── tab A ─────────────┐    ┌────────── SharedWorker ─────────┐
│ app code                      │    │ engine                          │
│      │                        │    │   │                             │
│ SharedWorkerProxyFace ─── port┼────┤  WorkerPortFace (face #1)       │
│      │ (Face trait)           │    │   │                             │
│      │                        │    │  WorkerPortFace (face #2) ──────┼──── tab B
└───────────────────────────────┘    │   │                             │
                                     │  WebTransportFace (upstream) ───┼──── ndn-fwd
                                     │  WebRtcFace (peer) ─────────────┼──── peer X
                                     └─────────────────────────────────┘

The SharedWorker face is a face on both sides of the port:

• The tab installs a [SharedWorkerProxyFace]; from the tab’s POV it is the only face it ever sees, and Interests/Data flow through it to the engine.
• The worker installs a [WorkerListener] on its global scope. Every tab that opens a port becomes a [WorkerPortFace] from the engine’s POV — i.e. just one more local face.

The wire format on the port is raw NDN TLV bytes, one packet per MessagePort.postMessage, transferred as a Uint8Array whose underlying ArrayBuffer is moved (zero-copy) via the transfer list. There is no RPC envelope; the engine on the worker side already knows how to parse NDN packets, and a tab that ships a malformed packet through the port gets the same handling as any other misbehaving face.

Lifecycle

A SharedWorker lives as long as any connected port exists. When the user closes the last tab from your origin, the worker is killed and the engine state inside it — face table, PIT, Content Store, WebRTC peerings, signing identity — is gone.

This is the same lifecycle the W3C spec mandates for SharedWorker; it is not configurable. Two practical consequences:

• Apps that need persistence across the all-tabs-closed gap must ship a separate persistence strategy (e.g. an IndexedDB-backed PIB that the engine repopulates on startup).
• Browser-side WebRTC peer reuse only amortizes within a single worker lifetime. After the worker is killed, the next tab that opens has to re-handshake with every peer.

The CLAUDE-md / cross-stack docs use this caveat to position phase 6 as “browser is a peer per origin” — a real UX cliff drop versus phase 1–5’s “browser is a peer per tab” — without overclaiming persistence.

Why not Service Workers?

Service Workers are activated by fetch events; they are designed to intercept HTTP requests inside a registered scope, not to host long-lived application state. A Service Worker can be terminated by the browser between fetches; relying on one to hold an NDN engine would mean rehydrating the engine on every fetch event, which defeats the purpose.

SharedWorker is the right tool: its lifecycle is tied to having at least one connected port, not to fetch traffic, and its message-passing API is exactly the per-tab face shape this crate needs.

Wiring (sketch)

// Tab side — pick a stable URL for your worker bootstrap and a
// fixed `name`. Same-origin tabs that pass the same (url, name)
// land on the same worker instance.
let face = SharedWorkerProxyFace::connect(
    FaceId(1),
    "/ndn-engine.worker.js",
    Some("ndn"),
    runtime.clone(),
)?;

// Worker side — call once from the wasm entrypoint.
let listener = init_worker_scope()?;
loop {
    let face = listener.accept_one(runtime.clone()).await?;
    engine.add_face(Box::new(face));
}

The /ndn-engine.worker.js bootstrap is a thin importScripts(...) shim that loads the wasm-bindgen output of your worker-side cdylib; dx serve produces the bundle, and the phase-6 demo wires the ?shared-engine=1 URL switch to swap the in-tab engine for the proxy face.

Forward compatibility

The face traits both sides expose are the standard ndn_transport::Face shape — every connected tab is just a face to whatever runs in the worker. Today the dioxus-demo’s worker runs the hand-rolled mini-engine; phase 7 will swap it for the real ForwarderEngine. The face contract on the port does not change in that handover, so applications wired against [SharedWorkerProxyFace] today survive phase 7 unchanged.

Browser as Forwarder

Phase 7 lands the full ndn_engine::ForwarderEngine on wasm32-unknown-unknown. Every browser tab that loads the shared-engine bundle is a real NDN forwarder — the same PIT, FIB, RIB, Content Store, strategy chain, dispatcher, and pipeline tasks that run inside ndn-fwd natively, hosted by a per-origin SharedWorker.

The dashboard ships this too. Loading ndn-dashboard?engine=local (built with --features browser-engine) hosts a ForwarderEngine directly in the dashboard tab — the management UI is the forwarder. See Dashboard → Browser-engine mode.

Crate: ndn-engine (the existing crate, now wasm-buildable). Public API: WasmEngineBuilder + WasmEngineConfig mirroring the native EngineBuilder; ForwarderEngine is identical on both targets.

What you get

The wasm-side engine is the same engine. Specifically:

• PIT — exact same ndn_store::Pit used natively. Inbound Interests create entries, Data satisfies them, expired entries drain via the periodic expiry task.
• FIB / RIB — same Fib and Rib; longest-prefix-match lookup; per-face-down cleanup; route TTL expiry.
• Content Store — LruCs (default) bounded by total bytes, with implicit-digest verification, name-based exact match, CanBePrefix descendant lookup, and MustBeFresh respect.
• Strategy chain — BestRouteStrategy by default; pluggable via with_strategy(...). The strategy runs in the same pipeline order as native (decode → CS lookup → PIT check → strategy → forward → PIT match → CS insert).
• Dispatcher pipeline — single-threaded on wasm (pipeline_threads = 1 is hardcoded; wasm32-unknown-unknown has no thread pool), but otherwise the same ingress / egress logic.
• Per-face reader / sender tasks — each face attached via add_face gets its own pair of tasks driven by the runtime abstraction.
• Expiry tasks — run_expiry_task, run_rib_expiry_task, run_idle_face_task all run on wasm via Runtime::sleep.

What you get from management

The wasm engine answers the same NFD-compatible management surface ndn-fwd serves, mounted via ndn_mgmt::mount_management. Calling it allocates an in-process face, installs /localhost/nfd + /localhop/nfd FIB entries pointing at that face, and returns the handler future for the caller to spawn. The same helper is used by ndn-fwd (native) and dioxus-demo / ndn-dashboard?engine=local (wasm) — one wire protocol, one dispatcher.

Working verbs on wasm: status/general, faces/{list,destroy,counters}, fib/{list,add-nexthop,remove-nexthop}, rib/{list,register,unregister}, cs/{info,config,erase}, strategy-choice/{list,set,unset}, measurements/list, config/get, log/* (with a host-provided LogInspector).

Native-only verbs return 501 NOT_IMPLEMENTED rather than time out: routing/*, discovery/*, service/*, security/*, neighbors/* all depend on crates that don’t build for wasm32-unknown-unknown (ndn-routing, ndn-discovery, FilePib). Extended-module commands under those names that arrive unsigned are caught by the auth gate first and return 403 UNAUTHORIZED per audit E.03 — same fail-secure policy as native.

Witnesses: testbed/tests/browser/wasm_engine_mgmt_status.spec.ts (6 Playwright cases) and testbed/tests/audit/mgmt_native_parity.sh (6 shell cases). Touch the dispatcher → keep both green.

What you still don’t get

• No multi-thread pipeline — pipeline_threads = 1. The wasm event loop doesn’t have threads to spread packet processing across; the option is fixed.
• No discovery tick — the wasm builder skips the discovery.on_tick loop because the only wasm-buildable DiscoveryProtocol is NoDiscovery (which no-ops on tick anyway). Browser-side discovery is application-layer, not link-layer.
• No native routing protocols — NLSR and friends pull ndn-app, not wasm-buildable today. Wasm callers can install a wasm-friendly routing impl after construction via engine.routing().enable(...).

Architecture

                     ┌────────── per-origin SharedWorker ──────────┐
                     │                                              │
                     │   ForwarderEngine                            │
                     │       │                                     │
   tab A ── port ────┼─→ WorkerPortFace (face#2) ──┐                │
                     │                              │               │
   tab B ── port ────┼─→ WorkerPortFace (face#3) ──┼─ pipeline ─→ FIB lookup ─→ AppFace (face#1)
                     │                              │               │            (producer-served names)
                     │   BrowserWebTransportFace ──┘               │       └─→ upstream WT face
                     │   (optional upstream)                        │            (default `/` route)
                     │                                              │
                     └─────────────────────────────────────────────┘

The dioxus-demo’s wrapper Engine (in crates/tooling/dioxus-demo/src/engine.rs) keeps an internal AppFace plumbed into the engine for application-tier I/O. Tabs that connect through SharedWorkerProxyFace become WorkerPortFace instances inside the engine; producers, the demo’s CA flow, and the local consumer share AppFace for their pipeline traffic.

Witness

The phase-6 two-tab cache-hit witness — testbed/tests/browser/sharedworker_cache_hit.spec.ts — now runs against the real ForwarderEngine, not the previous hand-rolled mini-engine. Tab A expresses /cache-test/counter twice; tab B expresses once; tab B’s response equals tab A’s second response, proving:

• The shared engine is shared (same producer counter advances across tabs).
• The CS short-circuits a fresh producer mint on cache hit (tab B’s response matches tab A’s last cached value rather than minting n+1).

Security caveats

• A malicious tab can poison its own engine’s CS with arbitrary Data — but since each origin gets its own SharedWorker, this affects only that origin’s tabs. Cross-origin tabs run independent engines.
• The wasm engine now supports a real [Validator]: pass one to [WasmEngineBuilder::with_validator] (the worker entrypoint seeds one from IdbPib::build_validator at startup). When no validator is passed the engine runs permissive (every Data marked verified) — apps that need verification either install one at engine build time or layer their own at the app tier.
• WebRTC peering can’t be owned by the SharedWorker directly — RTCPeerConnection is not exposed in WorkerGlobalScope per W3C. The practical pattern is a tab-side bridge: a tab owns the RTCPeerConnection (and an [ndn-face-webrtc] WebRtcFace), connects to the per-origin SharedWorker via a [SharedWorkerProxyFace], and pumps bytes between the two faces. The worker then treats the bridge tab like any other tab — its WorkerPortFace shows up in the engine’s face graph and FIB routes apply normally. Sketch in [crates/extension/ndn-face-webrtc/docs/worker-bridge.md].

Discovery on wasm

Link-layer multicast hello has no direct browser-tier analogue (no UDP multicast, no L2). Within an origin, every tab joins the same SharedWorker — discovery is moot. Across origins inside the same browser, a future BroadcastChannelDiscovery impl could serve as a hello-equivalent (origin-local but cross-tab). Cross-host peering uses WebRTC, where discovery is the signaling channel’s job, not the engine’s. Today the wasm engine ships NoDiscovery only — see the candidate design at [docs/notes/wasm-discovery.md].

Wiring (sketch)

// Inside the SharedWorker entrypoint:
let runtime = ndn_runtime::default_runtime();

// Optional upstream — empty string skips the dial.
let upstream: Option<Arc<dyn ErasedFace>> = if !upstream_url.is_empty() {
    let face = BrowserWebTransportFace::connect(
        FaceId(1), &upstream_url, &[], runtime.clone(),
    ).await?;
    Some(Arc::new(face))
} else {
    None
};

// Build the engine via the wasm builder.
let mut builder = WasmEngineBuilder::new(WasmEngineConfig::default())
    .with_runtime(runtime.clone());
if let Some(face) = upstream.as_ref() {
    builder = builder.add_face(Arc::clone(face));
}
let (engine, _shutdown) = builder.build()?;

// Optionally install a default `/` → upstream route.
if let Some(face) = upstream.as_ref() {
    engine.fib().set_nexthops(
        &Name::root(),
        vec![FibNexthop { face_id: face.id(), cost: 1 }],
    );
}

// Accept tab MessagePorts as new inbound faces.
let listener = init_worker_scope()?;
loop {
    let id = engine.faces().alloc_id();   // important: shared allocator
    let port_face = listener.accept_one(id, runtime.clone()).await?;
    engine.add_face(port_face, CancellationToken::new());
}

Next steps

Phase 7 lands the engine; the mgmt-parity follow-on closes the operational surface. The remaining browser-tier work toward full substrate-consumer readiness:

• WebRTC face integration inside the worker (peer-to-peer transit through the shared engine). ndn-face-webrtc runs tab-side today but the SharedWorker’s face graph only accepts WorkerPortFace and (optional) BrowserWebTransportFace.
• IndexedDB-backed PIB persistence so the engine’s signing identity survives the SharedWorker dying when the last tab closes. ndn-pib-idb exists; it is not yet plumbed into the wasm engine builder.
• Wasm-side Validator for engine-tier signature verification. Today ValidationStage::disabled() marks every Data verified on wasm; production callers do verification at the app layer. ndn-security builds wasm-clean with default-features = false, so this is a wiring task rather than a porting one.
• Wasm-friendly discovery beyond NoDiscovery — a multicast-hello equivalent over application-layer broadcast would close the link-layer-discovery gap.
• Native↔browser interop witness: boot ndn-fwd with a WT listener, dial it from the in-browser engine, prove bidirectional forwarding. Pins the cross-impl claim.

CLI Tools

You’ve got ndn-fwd running. Now what? The ndn-tools suite gives you the equivalent of ping, curl, and iperf for NDN networks.

Every tool in the suite communicates with the local router over the same IPC path: a Unix domain socket (default /run/nfd/nfd.sock) with an optional shared-memory data plane for high throughput. The management commands use the NFD-compatible control protocol; the data-plane tools use an InProcFace channel that plugs directly into the forwarding pipeline.

flowchart LR
    subgraph "ndn-tools"
        peek["ndn-peek"]
        put["ndn-put"]
        ping["ndn-ping"]
        iperf["ndn-iperf"]
        traffic["ndn-traffic"]
        ctl["ndn-ctl"]
    end

    subgraph "ndn-fwd"
        mgmt["Mgmt\n(NFD protocol)"]
        pipeline["Forwarding\nPipeline"]
        shm["SHM ring\nbuffer"]
    end

    ctl -- "control Interest/Data" --> mgmt
    peek -- "InProcFace (IPC)" --> pipeline
    put -- "InProcFace (IPC)" --> pipeline
    ping -- "InProcFace / ForwarderClient" --> pipeline
    iperf -- "ForwarderClient + SHM" --> shm
    traffic -- "embedded engine" --> pipeline

All data-plane tools accept a --face-socket flag (or $NDN_FACE_SOCK environment variable) to override the default socket path, and --no-shm to fall back to pure Unix-socket transport when shared memory is unavailable.

ndn-peek and ndn-put

These are the simplest tools in the suite – the equivalent of curl for NDN. One sends a single Interest and prints the Data it gets back; the other publishes a file as named Data segments.

ndn-peek

Fetch a single named Data packet:

ndn-peek /ndn/edu/ucla/ping/42
ndn-peek /ndn/video/frame-001 --timeout-ms 2000

The first argument is the NDN name to request. By default, ndn-peek waits 4 seconds for a response before giving up. Override this with --timeout-ms.

ndn-put

Publish a file as one or more named Data segments:

ndn-put /ndn/files/readme README.md
ndn-put /ndn/video/clip clip.mp4 --chunk-size 4096

ndn-put reads the file, splits it into segments using the NDN segmentation convention, and registers a prefix handler on the router to serve them. The default segment size follows the NDN standard (NDN_DEFAULT_SEGMENT_SIZE); use --chunk-size to override it for larger payloads.

ndn-ping

Reachability and latency testing for named prefixes, modeled directly after ICMP ping. It runs in two modes: a server that registers a prefix and replies to ping Interests, and a client that sends those Interests and measures round-trip time.

Server

Start a ping responder on the default /ping prefix:

ndn-ping server
ndn-ping server --prefix /ndn/my-node/ping --freshness 1000 --sign

The server registers the prefix with the router, then loops: for every Interest it receives, it sends back an empty Data packet. Passing --sign generates an ephemeral Ed25519 identity and signs each reply – useful for testing the cost of cryptographic verification in the pipeline.

The --freshness flag sets the FreshnessPeriod on response Data in milliseconds. A value of 0 (the default) omits the field entirely, meaning the Content Store will not serve stale cached copies.

Client

Measure RTT to a running ping server:

ndn-ping client --prefix /ping --count 10
ndn-ping client --prefix /ndn/remote/ping -c 100 -i 500 --lifetime 2000

The client sends Interests sequentially, printing per-packet timing as they return. When it finishes (or you press Ctrl-C), it prints a summary that mirrors the familiar ping format:

--- /ping ping statistics ---
10 transmitted, 10 received, 0 nacked, 0.0% loss, time 9.0s
rtt min/avg/max/p50/p99/stddev = 45µs/62µs/120µs/58µs/120µs/22 µs

ndn-ctl

Runtime management of a running router, following the same noun verb pattern as NFD’s nfdc. Under the hood, ndn-ctl sends NFD management Interests over the IPC socket and decodes the ControlResponse Data that comes back.

By default command Interests are signed with DigestSha256, which satisfies ndn-fwd and localhost-configured NFD (certfile any). When connecting to testbed NFD with rib.localhop_security, use --identity to sign commands with a key-backed signer:

# Testbed NFD: register a prefix using a key from the local PIB
ndn-ctl --socket /run/nfd/nfd.sock --identity /ndn/router1 route add /ndn --face 1
# Custom PIB path
ndn-ctl --identity /ndn/router1 --pib ~/.ndn/my-pib route add /ndn --face 1

The identity key must already exist in the PIB (ndn-ctl security init --name /ndn/router1 creates one).

Face management

ndn-ctl face create udp4://192.168.1.1:6363
ndn-ctl face create tcp4://router.example.com:6363
ndn-ctl face destroy 3
ndn-ctl face list

Route management

ndn-ctl route add /ndn --face 1 --cost 10
ndn-ctl route remove /ndn --face 1
ndn-ctl route list

Strategy management

ndn-ctl strategy set /ndn --strategy /localhost/nfd/strategy/best-route
ndn-ctl strategy unset /ndn
ndn-ctl strategy list

Content Store

ndn-ctl cs info                          # capacity, entry count, memory usage
ndn-ctl cs config --capacity 1000000     # set max capacity in bytes
ndn-ctl cs erase /ndn/video              # evict cached entries by prefix
ndn-ctl cs erase /ndn/video --count 100  # evict at most 100 entries

Service discovery

ndn-ctl service list                    # locally announced services
ndn-ctl service browse                  # all known services (local + peers)
ndn-ctl service browse /ndn/sensors     # filter by prefix
ndn-ctl service announce /ndn/my-app    # announce a service at runtime
ndn-ctl service withdraw /ndn/my-app    # withdraw announcement

Neighbors, status, and shutdown

ndn-ctl neighbors list
ndn-ctl status
ndn-ctl shutdown

Security (local, no router needed)

The security subcommands operate on the local PIB (Public Information Base) and do not require a running router:

ndn-ctl security init --name /ndn/my-identity
ndn-ctl security info
ndn-ctl security export --name /ndn/my-identity -o cert.hex
ndn-ctl security trust cert.ndnc

Tip: ndn-ctl also supports a --bypass flag that uses the legacy JSON-over-Unix-socket transport instead of the NFD management protocol. This is mainly useful for debugging the router’s management layer itself.

ndn-traffic

A self-contained traffic generator that does not need a running router. It spins up an embedded forwarding engine with in-process InProcFace pairs and drives configurable Interest/Data traffic through the full pipeline. This makes it ideal for stress-testing the pipeline stages in isolation.

ndn-traffic --count 100000 --rate 50000 --size 1024 --concurrency 4
ndn-traffic --mode sink --count 10000   # no producer, all Interests Nack

In echo mode, ndn-traffic creates a FIB route from the prefix to a producer face, so every Interest is satisfied. In sink mode, no producer exists, so every Interest results in a Nack – useful for measuring Nack processing overhead.

The output includes loss percentage, throughput in pps and Mbps, and latency percentiles (min, avg, p50, p95, p99, max):

ndn-traffic: mode=echo count=100000 rate=unlimited size=1024B concurrency=4
  sent=100000  received=100000  lost=0 (0.00%)
  throughput: 245000 pps, 2006.42 Mbps
  latency: min=8us avg=16us p50=14us p95=32us p99=58us max=210us
  elapsed: 0.41s

ndn-iperf

Sustained bandwidth measurement between two nodes, modeled after iperf3. Unlike ndn-traffic (which embeds its own engine), ndn-iperf connects to a running router and measures real network throughput including IPC overhead, SHM transfer, and pipeline processing.

Server

ndn-iperf server
ndn-iperf server --prefix /iperf --size 8192 --sign
ndn-iperf server --hmac --freshness 1000

The server registers its prefix, optionally announces it via service discovery, then replies to every Interest with a Data packet of the configured payload size. Signing options:

• --sign: Ed25519 signatures (cryptographically strong, slower)
• --hmac: HMAC-SHA256 signatures (faster, uses a fixed benchmark key)

Client

ndn-iperf client
ndn-iperf client --prefix /iperf --duration 30 --window 128
ndn-iperf client --cc cubic --window 64 --duration 60

The client sends Interests in a sliding window and measures throughput, loss, and RTT. It prints periodic interval reports during the test and a final summary:

--- ndn-iperf results ---
  duration:    10.02s
  transferred: 78.45 MB (82247680 bytes)
  throughput:  62.58 Mbps
  packets:     10032 sent, 10030 received, 2 lost (0.0% loss)
  RTT:         avg=523us min=89us max=4201us
               p50=412us p95=1205us p99=2880us

Congestion control

ndn-iperf includes three congestion control algorithms, selectable via --cc:

Fine-tuning flags for advanced use:

ndn-iperf client --cc aimd --ai 2.0 --md 0.7 --min-window 4 --max-window 512
ndn-iperf client --cc cubic --cubic-c 0.2 --window 32

Note: The --window flag also sets the initial slow-start threshold (ssthresh). This prevents unbounded slow start from rocketing the window on low-RTT links. For high-BDP (bandwidth-delay product) paths, increase --window and --max-window together.

ndn-bench

A lightweight micro-benchmark for measuring the overhead of the forwarding pipeline’s internal channels. It spins up an embedded engine and drives Interests through InProcFace channel round-trips, reporting latency percentiles and aggregate throughput.

ndn-bench
ndn-bench --interests 50000 --concurrency 20 --name /bench/test

Sample output:

ndn-bench: 50000 interests, concurrency=20, prefix=/bench/test
ndn-bench: 1250000 interests/sec over 0.04s
rtt: n=50000 avg=3µs p50=2µs p95=5µs p99=8µs

Note: ndn-bench currently measures InProcFace channel overhead only (the Interest is not wired through the full pipeline). It is most useful for establishing a baseline cost for the IPC mechanism itself.

Common Workflows

The tools compose naturally. Here is a typical sequence for validating a new link and measuring its capacity.

1. Check reachability

First, verify that the remote prefix is reachable through the forwarding plane:

# On the remote node
ndn-ping server --prefix /ndn/remote

# On the local node
ndn-ping client --prefix /ndn/remote -c 10

If pings succeed, the FIB routes and faces are correctly configured. If they time out, use ndn-ctl to inspect the forwarding state:

ndn-ctl face list
ndn-ctl route list
ndn-ctl status

2. Measure throughput

Once reachability is confirmed, run a sustained bandwidth test:

# On the remote node
ndn-iperf server --prefix /ndn/remote/iperf --size 8192

# On the local node
ndn-iperf client --prefix /ndn/remote/iperf --duration 30 --window 128

Start with the default AIMD congestion control. If you see high loss or oscillating throughput, try CUBIC or a fixed window to isolate the issue:

ndn-iperf client --prefix /ndn/remote/iperf --cc fixed --window 32

3. Stress-test the local pipeline

For profiling the forwarder itself without network variables, use ndn-traffic with the embedded engine:

ndn-traffic --count 1000000 --concurrency 8 --size 4096

4. Monitor in real-time

While any of the above tests are running, use ndn-ctl in another terminal to watch the router state:

watch -n 1 ndn-ctl status
ndn-ctl cs info
ndn-ctl service browse

Dashboard

The NDN Dashboard is a full management UI for any NFD-spec forwarder, available as a desktop app (native window + system tray), a web app (pure Rust compiled to WASM), and — new — a browser-engine mode where the dashboard itself hosts the forwarder in-page.

All management commands speak the NFD-spec management protocol. The dashboard never reimplements protocol logic.

Forwarder interop

The dashboard manages any of the three production-grade NDN forwarders that speak NFD-spec management:

Selection is runtime: a single ndn-dashboard binary works against any of them. With no --forwarder flag, the dashboard auto-detects by probing each profile’s default socket in order. Override the socket with --socket=/custom/path. See docs/notes/dashboard-multi-forwarder-2026-05-10.md for the full design.

ndn-rs-specific UI panels (demo CA, SafeBag export, TokenChallenge invite tokens, IssuancePolicy gate) appear automatically when connected to ndn-fwd; against NFD or YaNFD the dashboard falls back to the spec-baseline UI.

Quick Start

Desktop

cargo build -p ndn-dashboard --release
./target/release/ndn-dashboard                          # auto-detect
./target/release/ndn-dashboard --forwarder=nfd          # force NFD
./target/release/ndn-dashboard --forwarder=ndn-fwd \
    --socket=/var/run/foo.sock                          # custom socket

Auto-detect probes /run/ndn-fwd/ndn-fwd.sock (ndn-fwd), /var/run/nfd.sock (NFD), then /run/nfd/nfd.sock (YaNFD); first existing path wins.

Web (WASM)

dx serve --features web --platform web

Connects to the router via WebSocket (ws://localhost:9696 by default). The router must have a WebSocket face listener enabled. Override via query string:

?forwarder=nfd&ws=ws://nfd.example:9696/ws/      # remote NFD via WS
?engine=local                                     # in-page engine (see below)

The web version uses the same TLV codec and packet types as the native build, demonstrating ndn-rs portability.

Browser-engine mode (Phase 7)

dx serve --features browser-engine --platform web
# then load http://localhost:8080/?engine=local

In this mode the dashboard hosts its own ndn_engine::ForwarderEngine inside the browser tab via WasmEngineBuilder — PIT, FIB, CS, dispatcher, expiry tasks all run in-page. No remote forwarder, no WebSocket. Useful for browser-only deployments, demos, and self-hosters who’d rather not run a separate ndn-fwd process.

What works today: engine startup, faces/FIB/CS introspection panels, mutations through the engine API directly. What’s deferred: NFD-spec wire mgmt parity (the wire-format mgmt server lives in the ndn-fwd binary and would need its own session to port) and upstream face dialing (WebTransport / WebRTC connect-out from the dashboard’s in-page engine — reference impl at crates/tooling/dioxus-demo/src/engine.rs).

Features

Architecture

flowchart LR
    subgraph Desktop
        DX["Dioxus Desktop"]
        TRAY["System Tray"]
        PROC["Subprocess Mgmt"]
        IPC["ndn-ipc\n(Unix socket)"]
    end

    subgraph Web["Web (WS)"]
        DW["Dioxus Web\n(WASM)"]
        WS["WsMgmtClient\n(WebSocket)"]
    end

    subgraph Browser["Web (?engine=local)"]
        DBE["Dioxus Web\n(WASM)"]
        ENG["ForwarderEngine\n(in-page)"]
    end

    subgraph Router["Forwarder\n(ndn-fwd | NFD | YaNFD)"]
        MGT["Management"]
    end

    DX --> IPC --> MGT
    DX --> TRAY
    DX --> PROC
    DW --> WS --> MGT
    DBE --> ENG

    style DW fill:#2d5a8c,color:#fff
    style WS fill:#2d5a8c,color:#fff
    style DBE fill:#3a7a3a,color:#fff
    style ENG fill:#3a7a3a,color:#fff

The desktop build includes system tray integration, subprocess management (start/stop ndn-fwd), and embedded tool servers. The web build omits these (no OS-level access in a browser) but retains full monitoring and management capability.

Feature Gates

Polling Model

The dashboard polls the router every 3 seconds via NDN management Interests on /localhost/nfd/. All responses are decoded using ndn-config types (FaceStatus, FibEntry, StrategyChoice, etc.) and converted to display-friendly Dioxus signals.

Configuration

Dashboard settings are persisted separately from router config:

• Desktop: ~/.config/ndn-dashboard/settings.json
• Web: Browser localStorage under key ndn-dashboard-settings

Settings include node prefix, tool server configuration, experimental feature toggles, and UI preferences.

Building for Web

The web target compiles the entire dashboard — including NDN packet encoding, management protocol, and reactive UI — to WebAssembly:

# Install Dioxus CLI
cargo install dioxus-cli

# Serve locally with hot reload
cd crates/tooling/ndn-dashboard
dx serve --features web --platform web

# Production build
dx build --features web --platform web --release

The output in dist/ is a static site that can be deployed anywhere. The live version is deployed to GitHub Pages alongside the wiki and explorer.

Docker Deployment

ndn-fwd is published as a minimal Docker image to the GitHub Container Registry. This page explains how to pull, configure, and run it.

Image tags

docker pull ghcr.io/quarmire/ndn-fwd:latest

Quick start

docker run --rm \
  -p 6363:6363/udp \
  -p 6363:6363/tcp \
  ghcr.io/quarmire/ndn-fwd:latest

This starts the forwarder with the built-in default configuration (UDP + TCP listeners on port 6363, no static routes).

Supplying a configuration file

The container reads its config from /etc/ndn-fwd/config.toml. Mount your own file over it:

docker run --rm \
  -p 6363:6363/udp \
  -p 6363:6363/tcp \
  -v /path/to/ndn-fwd.toml:/etc/ndn-fwd/config.toml:ro \
  ghcr.io/quarmire/ndn-fwd:latest

A minimal ndn-fwd.toml for a router with UDP and multicast faces:

[engine]
cs_capacity_mb = 64

[[face]]
kind = "udp"
bind = "0.0.0.0:6363"

[[face]]
kind = "multicast"
group = "224.0.23.170"
port  = 56363

[[route]]
prefix = "/ndn"
face   = 0
cost   = 10

See Running the Forwarder for the full configuration reference.

Supplying TLS certificates

When the WebSocket face is configured with TLS, mount the certificate and key files into /etc/ndn-fwd/certs/ (the directory is pre-created in the image):

docker run --rm \
  -p 6363:6363/udp \
  -p 6363:6363/tcp \
  -p 9696:9696/tcp \
  -v /path/to/ndn-fwd.toml:/etc/ndn-fwd/config.toml:ro \
  -v /path/to/cert.pem:/etc/ndn-fwd/certs/cert.pem:ro \
  -v /path/to/key.pem:/etc/ndn-fwd/certs/key.pem:ro \
  ghcr.io/quarmire/ndn-fwd:latest

Reference the mounted paths in ndn-fwd.toml:

[[face]]
kind     = "web-socket"
bind     = "0.0.0.0:9696"
tls_cert = "/etc/ndn-fwd/certs/cert.pem"
tls_key  = "/etc/ndn-fwd/certs/key.pem"

Obtaining a certificate

With Let’s Encrypt / Certbot:

certbot certonly --standalone -d router.example.com
# Certificates written to /etc/letsencrypt/live/router.example.com/

Then mount the live directory:

-v /etc/letsencrypt/live/router.example.com/fullchain.pem:/etc/ndn-fwd/certs/cert.pem:ro
-v /etc/letsencrypt/live/router.example.com/privkey.pem:/etc/ndn-fwd/certs/key.pem:ro

Accessing the management socket

The router’s Unix management socket is created inside the container at /run/ndn-fwd/mgmt.sock. Bind-mount the directory to reach it from the host:

mkdir -p /run/ndn-fwd

docker run --rm \
  -p 6363:6363/udp \
  -p 6363:6363/tcp \
  -v /path/to/ndn-fwd.toml:/etc/ndn-fwd/config.toml:ro \
  -v /run/ndn-fwd:/run/ndn-fwd \
  ghcr.io/quarmire/ndn-fwd:latest

Then use ndn-ctl from the host:

ndn-ctl --socket /run/ndn-fwd/mgmt.sock status
ndn-ctl --socket /run/ndn-fwd/mgmt.sock face list
ndn-ctl --socket /run/ndn-fwd/mgmt.sock route add /ndn --face 1 --cost 10

Docker Compose

A complete docker-compose.yml for a single-node testbed:

services:
  ndn-fwd:
    image: ghcr.io/quarmire/ndn-fwd:latest
    restart: unless-stopped
    ports:
      - "6363:6363/udp"
      - "6363:6363/tcp"
      - "9696:9696/tcp"
    volumes:
      - ./ndn-fwd.toml:/etc/ndn-fwd/config.toml:ro
      - ./certs/cert.pem:/etc/ndn-fwd/certs/cert.pem:ro
      - ./certs/key.pem:/etc/ndn-fwd/certs/key.pem:ro
      - ndn-mgmt:/run/ndn-fwd

volumes:
  ndn-mgmt:

Building the image locally

From the repository root:

docker build -f binaries/spec/ndn-fwd/Dockerfile -t ndn-fwd .
docker run --rm -p 6363:6363/udp ndn-fwd

Image details

The image uses a two-stage build: the builder stage compiles ndn-fwd from source using the official rust:1.85-slim image; the runtime stage copies only the compiled binary into a minimal debian:trixie-slim base with no Rust toolchain.

Self-hosting ndn-rs

This page walks an operator from “fresh VPS” to “running NDN forwarder with Let’s Encrypt TLS, WebRTC peer rendezvous, and auto-update on a stable release channel.” Audience is anyone who already self-hosts Mastodon, Matrix, Tailscale, or NextCloud — same shape: a docker-compose file, a config, an installer, and an upgrade story you can ignore.

What you need

• A domain you control (ndn.example.com).
• A small Linux VPS — 1 vCPU / 2 GB RAM is enough for a personal forwarder. Ports 443 (TCP, for WebTransport) and 6363 (UDP+TCP, for native NDN faces) reachable.
• Docker Engine + the compose v2 plugin (install instructions).
• An ACME-friendly DNS provider. Cloudflare is the smoothest path out of the box; any other DNS provider with an instant-acme registered impl works.

One-shot install

curl -fsSL https://raw.githubusercontent.com/named-data/ndn-rs/main/deploy/install.sh | bash

The installer asks four questions:

1. Your domain (FQDN).
2. Your email (for the Let’s Encrypt account).
3. DNS provider name (cloudflare, route53, manual).
4. Your NDN namespace prefix — defaults to the reverse-DNS of your domain.

For Cloudflare it also asks for an API token (DNS:Edit on the zone) and zone id. The installer writes ndn-fwd.toml and .env into the deploy directory and runs docker compose up -d.

Re-running the installer is safe — it refreshes config from your answers; existing volumes (PIB, ACME cache) are preserved.

What’s running

After the installer completes:

$ docker compose ps
NAME                       STATUS    PORTS
ndn-fwd                    Up        host networking (UDP/TCP 6363, TCP 443, TCP 9696)
ndn-signaling-relay        Up        0.0.0.0:8888->8888/tcp

• ndn-fwd — the NDN forwarder. Hosts WebTransport at https://<your-domain>/ndn (no ?cert= query string needed — the cert chains to a real CA). Hosts WebSocket at port 9696 and raw UDP/TCP NDN at 6363.
• ndn-signaling-relay — HTTP rendezvous for WebRTC peering. Browser tabs use this to bootstrap browser↔browser NDN sessions.
• watchtower (opt-in, see Upgrades below) — checks for new image tags hourly, restarts containers on update.

The first startup performs an ACME order via DNS-01 against your DNS provider. Watch the logs:

docker compose logs -f ndn-fwd

The cert is cached on the ndn-fwd-acme volume; subsequent restarts skip the order until ~30 days before expiry. Renewal happens in-place; no operator action.

Upgrades

ndn-rs ships three image tag aliases:

The compose file defaults to :v0-stable. A self-hoster who never edits anything gets safe rolling updates on the major-zero stable channel, which guarantees no schema-breaking config changes between patches.

To turn auto-update on:

docker compose --profile watchtower up -d

Watchtower polls Docker Hub hourly, pulls any tag changes for the labelled containers, and restarts them. It only acts on containers labelled com.centurylinklabs.watchtower.enable=true (both ndn-rs services in this compose file are).

To turn it off:

docker compose --profile watchtower stop watchtower
docker compose --profile watchtower rm watchtower

To pin a specific version, set the env in .env:

NDN_FWD_TAG=v0.1.3
NDN_RELAY_TAG=v0.1.3

…then docker compose up -d to roll forward.

Backup and restore

The state worth preserving lives in three docker volumes:

• ndn-fwd-config — your toml, trust-anchor pem, signing identity.
• ndn-fwd-pib — the personal information base (issued certs, key chain).
• ndn-fwd-acme — the ACME cert cache. Excluding this from a restore means the first restart will re-issue, which trips Let’s Encrypt’s rate limiter.

./backup.sh > ndn-fwd-$(date +%F).tar.gz

That captures all three volumes. Cron-friendly:

0 3 * * * cd /opt/ndn-rs-deploy && ./backup.sh > /var/backups/ndn-fwd/$(date +\%F).tar.gz

To restore:

docker compose down
tar -xzf ndn-fwd-2026-05-10.tar.gz -C /var/lib/docker/volumes/
docker compose up -d

Troubleshooting

ACME order fails: “DNS challenge propagation timeout”

Your DNS provider didn’t propagate the TXT record fast enough. Re-run docker compose restart ndn-fwd to retry; if it persists, check the provider’s API token has DNS:Edit on the zone. Cloudflare tokens are scoped at creation; the installer’s token must list the exact zone id.

Port 443 already in use

Another service (nginx, Caddy, …) is bound to 443. Either stop it or change [listeners.webtransport].listen in ndn-fwd.toml to a different port — but note browsers can only reach WebTransport on 443 by default; using a non-443 port forces clients to dial explicitly.

No NDN peers reachable

By default the forwarder doesn’t auto-join the global NDN testbed. Either configure NLSR neighbors in [routing.nlsr] (see NLSR setup) or uncomment the testbed multicast face in ndn-fwd.toml.

Browser can’t connect to WebTransport

Three things to check:

1. The cert is real (not self-signed). Run curl -v https://<your-domain>/ndn — the TLS section should show “Server certificate: subject=CN=…, issuer=CN=R3,O=Let’s Encrypt”.
2. Your domain resolves to the VPS. dig +short <your-domain> should return the VPS’s public IP.
3. The browser supports WebTransport. Recent Chromium (≥97) and Firefox (≥114) do; Safari is still partial. Open chrome://webtransport-internals/ to confirm sessions are being attempted.

What’s not yet automated

• Status page (/status) — a small dashboard showing face count, peer count, ACME expiry. Drafted but not yet shipped; meanwhile, docker compose logs ndn-fwd | grep -E 'ACME|face_up' is the manual surface.
• migrate-config.sh — schema migrations on the ndn-fwd.toml file. Not yet needed (we’re at v0.1; no cross-version schema breaks). Will land before any v0.2.x or v1.0.0 release that changes the toml shape.
• NDNCERT CA — the forwarder can run an NDNCERT CA at /<namespace>/CA (see [demo_ca] in the example toml), but the default config doesn’t enable it; namespaces that need to issue user certs should add an NDNCERT block per the NDNCERT setup guide.

Invite tokens — operator side

The forwarder’s embedded NDNCERT CA can run in two modes:

• Auto-approve (NopChallenge) — every NEW request is approved. This is what [demo_ca] defaulted to before invite tokens landed. Only safe behind a trusted local face; the moment the CA is reachable from the open internet, anyone can mint a cert under your namespace.
• Invite-token (TokenChallenge) — every NEW request must present a one-shot pre-provisioned token. Tokens are minted out-of-band (you control supply), shared with users via a URL or QR code, and consumed on first use. This is the production shape for any CA reachable beyond loopback.

This page is the operator-side surface.

Switching the demo CA to invite-token mode

In your ndn-fwd.toml:

[demo_ca]
enabled = true
prefix  = "/com/example/CA"
identity = "/com/example/CA"
# Pre-provisioned one-time tokens. An empty list (or omitting the
# field) keeps the CA in auto-approve mode.
tokens = [
    "8f3a7b2c91d04e6589a5e1d4c7f02a96",
    "4b1e8d3a92c75f068b1a4c9e7d63f102",
]

Restart ndn-fwd. The startup log will read:

demo_ca  TokenChallenge — invite-token gated enrollment  count=2

Each token in the list is consumed on first successful enrollment; once consumed, the CA rejects subsequent attempts to use it. Add new tokens by editing the toml and restarting (live management of the TokenStore via the /localhost/nfd/... socket is a follow-on).

Sharing an invite

Each token in tokens becomes a join URL of the form:

https://<your-domain>/?join=<token>

The user clicks (or scans a QR pointing at) the URL. The browser’s JoinClient (in dioxus-demo’s shared-engine bundle) pulls the token from the URL fragment, runs the NDNCERT NEW + CHALLENGE round-trip, and on success persists the issued cert to the per-origin IndexedDB so reloads short-circuit.

Token shape: any bytes / string the operator chooses. Recommended: 16-byte random (openssl rand -hex 16 or equivalent) — long enough to resist guessing, short enough to fit in a QR code without padding. The CA does not interpret the token; it just checks set membership.

Generating tokens

Use the ndn-fwd-tokens CLI:

# Mint one token + URL.
ndn-fwd-tokens new --domain ndn.example.com

# Five at once.
ndn-fwd-tokens new --domain ndn.example.com --count 5

# Render a QR code in the terminal (great for slacking a link).
ndn-fwd-tokens new --domain ndn.example.com --qr

# SVG QR file for printing / paper handoff.
ndn-fwd-tokens new --domain ndn.example.com --qr --qr-format png

Each invocation prints token = "..." and the matching URL. Paste the token into ndn-fwd.toml’s [demo_ca].tokens array and restart; share the URL with the user. The CLI doesn’t talk to a running CA — it’s a pure local mint + format helper, so it works offline.

(For low-tech bootstrapping without the CLI, openssl rand -hex 16 or head -c 16 /dev/urandom | xxd -p produces a token of the same shape; the URL is then just https://<domain>/#join=<hex>.)

Revoking an invite

Tokens are consumed on use, so most “revocation” is automatic. For an unsent or unclaimed token: remove it from tokens in the toml and restart. The token is gone before the first claim attempt.

For a claimed identity (revoking the cert, not the token): that’s a different flow — NDNCERT REVOKE, served by the same CA. See NDNCERT setup for the cert-side revocation surface.

Security notes

• The token list is shared secret material. The toml is bind- mounted into the container at /etc/ndn-fwd/config.toml:ro; on a multi-user host treat the file as 0600. The compose file uses a docker volume so unprivileged container users can’t read it.
• Tokens in the URL fragment are NOT sent to the server in HTTP request lines (browsers strip fragments before sending). The fragment goes only into the page’s wasm module and from there via NDN to the CA.
• A leaked token can be claimed by anyone who has it; the CA has no way to authenticate the human on the other end of the URL. If a token leaks before its intended user claims it, remove it from the list.

Follow-ups (not yet shipped)

• Live token management against a running CA (ndn-fwd-tokens add / list / remove over the management socket, no restart). Today’s new mints + formats only — operator must edit the toml + restart to enable a fresh batch.
• Out-of-band revocation channel (/localhost/nfd/... mgmt command) for revoking issued certs, separate from unclaimed-token cleanup.

Joining as a user

Someone gave you a link or a QR code. Here’s what’s actually happening when you click it.

The link

https://ndn.example.com/?join=8f3a7b2c91d04e6589a5e1d4c7f02a96

The bit after ?join= is your invite token — a one-shot pass the host minted just for you. Click the link (or point your phone’s camera at the QR), and the host’s web page does the rest:

1. Loads the JoinClient wasm bundle (~200 KB; cached after the first visit).
2. Pulls the token out of the URL.
3. Runs the NDNCERT enrollment round-trip with the host’s CA, submitting the token as the challenge response.
4. On success: persists your issued certificate to your browser’s IndexedDB so future visits skip straight to step 5.
5. Shows you your identity (the cert name) and unlocks the producer / consumer UI.

End-to-end target: under 30 seconds on LTE. If it’s slower, the WebRTC handshake is the most likely culprit; the host operator should check that ICE gathering is configured for non-trickle so the SDP is bundled in a single round trip.

What’s persisted

Your identity is stored in your browser’s IndexedDB as a SafeBag — the same canonical NDN container ndnsec export produces. One file (well, one IndexedDB row) carries:

• Your identity name (/com/example/users/<random-id>).
• Your signing key (16 bytes; never leaves your browser).
• The issued certificate (your proof to the network that the identity name is yours).

This data is per-origin — the host’s domain is the key. A different domain serving a different ndn-rs deployment gets its own IndexedDB; cross-origin reads are impossible.

It’s also per-browser — Chrome on your laptop and Chrome on your phone are different stores. If you join from one device, you don’t automatically appear on the other; you either re-join (each token is one-shot, so the operator gives you a second one) or future device-pairing UX (not yet shipped) bridges them via SVS.

What if I close all the tabs

The SharedWorker that hosts the engine dies when its last connected port closes (W3C rule). The next tab you open re-spawns the worker; the worker pulls your identity back from IndexedDB and you’re connected again — no re-join, no new token needed.

Both halves of your identity round-trip through IndexedDB: the issued cert AND the encrypted signing key, bundled as a SafeBag. Reload is a true zero-cost short-circuit — no NDNCERT round-trip, the restored signer is the same one you started with.

The SafeBag wire format is the spec-canonical container the rest of the NDN ecosystem speaks. In principle a future “Export identity” button on the host’s page will hand you the same bytes ndnsec export would produce; you can carry that file to a native machine and ndnsec import it to sign Data from the command-line as the same identity. (Today the export button isn’t shipped — but the bytes are already in the right shape, so when it lands the interop is free.)

Where the encryption key lives. The SafeBag encrypts your private key with a passphrase. Today that passphrase lives in your browser’s IndexedDB right next to the bag — meaning a hostile browser extension or an XSS bug at the host’s origin could lift both. This is the honest truth about the current threat model and matches what every “in-browser key” service ships before WebAuthn integration. The wire shape is forward- compatible: a future version derives the passphrase from a WebAuthn passkey or asks you to type it; only the passphrase source changes, the SafeBag bytes stay the same.

What if I clear my browser data

Same as never having joined. The operator can give you a fresh invite token; the join flow is identical to the first time.

Logging out

Hit the “forget identity” button on the page (or, equivalently, clear the host’s site data in your browser’s settings). The IndexedDB entries are dropped; subsequent visits show the landing page. The host’s CA can also revoke your cert out-of-band (NDNCERT REVOKE).

What the operator sees

From the operator’s perspective, an enrollment looks like:

demo_ca  NEW request  identity=/com/example/users/8f3a7b2c
demo_ca  CHALLENGE token  consumed=8f3a7b2c91d04e6589a5e1d4c7f02a96
demo_ca  cert issued  name=/com/example/users/8f3a7b2c/KEY/k1/CA/v=1

The operator gave out the token; you claimed it. The token is now spent — no one else can use it. Your cert chains back to the host’s CA, which is itself the local trust anchor for the session.

Troubleshooting

The page says “join failed: token already claimed” — the token has been used. Ask the operator for a fresh one. (Or, if you think someone else claimed your token: tell the operator immediately so they revoke that cert.)

The page says “join failed: timeout” — the browser couldn’t reach the host’s WebTransport endpoint within the lifetime window. Most often: a flaky network, or the host isn’t serving WebTransport on 443. Try again; if it persists, check with the operator.

The page says “no token in URL” — you visited the host without the ?join=... fragment, and there’s no cached identity in your browser. Get a fresh invite link from the operator.

Logging and Observability

ndn-rs uses the tracing crate for structured, target-routed logging. Every event carries a target: string drawn from a 26-entry taxonomy, which lets operators select exactly the subsystems they care about without wading through unrelated output.

Quick start

# Show only pipeline and PIT events at trace level.
RUST_LOG=fwd.pipeline=trace,fwd.pit=debug ndn-fwd -c router.toml

# Show all face-system events at debug, everything else at info.
RUST_LOG=info,face.system=debug ndn-fwd -c router.toml

The RUST_LOG syntax is the standard EnvFilter directive format: target=level[,target=level,...].

Log-target taxonomy

Print the full taxonomy at any time:

$ ndn-fwd --modules
fwd.pipeline
fwd.pit
fwd.cs
fwd.fib
fwd.strategy
face.tcp
face.udp
face.ws
face.lp
face.eth
face.system
mgmt.rib
mgmt.face
mgmt.fib
mgmt.cs
mgmt.strategy
mgmt.log
mgmt.security
mgmt.status
routing.dvr
routing.nlsr
sync.svs
sync.psync
security
engine
discovery

The same list is available at runtime via the management API:

$ ndn-tools interest /localhost/nfd/log/modules

Target reference

Changing the filter at runtime

The filter can be reloaded without restarting the forwarder:

ndn-tools command /localhost/nfd/log/set-filter \
  Uri fwd.pipeline=trace,mgmt.face=debug

Read the current filter:

ndn-tools interest /localhost/nfd/log/get-filter

Structured fields

Events include machine-readable fields alongside the human message, making them easy to parse with tools like jq when the formatter is set to JSON:

RUST_LOG=fwd.pipeline=trace RUST_LOG_FORMAT=json ndn-fwd -c router.toml \
  | jq 'select(.target == "fwd.pipeline")'

Typical pipeline event fields: name (NDN Name), face (FaceId), nonce, len (bytes).

Log file

Configure a persistent log file in router.toml:

[logging]
level = "info"
file  = "/var/log/ndn-fwd/ndn-fwd.log"

File writes are non-blocking — log events never stall the forwarding pipeline.

Debugging with tokio-console

tokio-console is an interactive task inspector for async Rust applications. It connects to a running ndn-fwd process over gRPC and shows every live tokio task by name, its poll count, idle time, and busy time. This is the right tool when a face is stalling and you want to see which task is hung, or when you want to understand where the forwarder is spending its time.

When to use it

• A face reader stops receiving packets but the process is running.
• The pipeline is slow and you need to identify the bottleneck task.
• An expiry worker appears to have stopped ticking.
• You want to verify that NLSR’s recompute loop is firing as expected.

Build

RUSTFLAGS="--cfg tokio_unstable" \
  cargo build -p ndn-fwd --features console --profile console

The --cfg tokio_unstable flag enables tokio’s internal task instrumentation hooks. This is not optional — without it, tokio does not expose task data to console-subscriber and the tool will show no tasks. The console Cargo profile inherits dev settings and keeps debug symbols.

The long-lived task spans shipped in phase 2 name every persistent task so tokio-console shows rows like engine_task, face_read, face_write, expiry, pipeline_dispatch, nlsr_sync, and nlsr_recompute rather than anonymous tokio::spawn[…] entries.

The console layer listens on 127.0.0.1:6669 by default. Override with:

TOKIO_CONSOLE_BIND=0.0.0.0:9999 \
  RUSTFLAGS="--cfg tokio_unstable" \
  cargo run -p ndn-fwd --features console --profile console

Install tokio-console

cargo install --locked tokio-console

Connect

tokio-console

With a custom bind address:

tokio-console http://127.0.0.1:9999

Expected output

After connecting, the task list pane shows one row per live task. The Name column will contain the span names set in phase 2:

 ID  Name                  State   Total  Busy    Idle    Polls
  1  engine_task           idle    1.2s   0.001s  1.199s      4
  2  expiry (pit)          idle    1.2s   0.000s  1.200s    120
  3  expiry (rib)          idle    1.2s   0.000s  1.200s      1
  4  expiry (idle_face)    idle    1.2s   0.000s  1.200s      0
  5  pipeline_dispatch     idle    1.2s   0.001s  1.199s     64
  6  face_read  (face_id=1) idle   1.2s   0.001s  1.199s      8
  7  face_write (face_id=1) idle   1.2s   0.000s  1.200s      2

If you see only tokio::spawn[…] rows, the binary was not built with --cfg tokio_unstable or the console feature was not enabled.

Production note

The --features console build is a debugging build, not for production use. The overhead of --cfg tokio_unstable is small (a few extra atomic operations per task poll) but measurable under high packet rates. The long-lived task spans (added unconditionally in phase 2) have no runtime cost beyond the tracing::Span the process already pays; only the console gRPC server is gated behind the feature flag.

NDNCERT Enrollment

ndn-rs supports certificate issuance via the NDNCERT 0.3 protocol against an upstream ndncert-ca-server (C++ reference implementation).

Protocol overview

A certificate request follows three steps:

1. NEW — client sends a self-signed NDN Certificate (CertRequest) plus an ephemeral P-256 ECDH public key. The CA generates a shared AES-128-GCM session key and returns the CA’s ECDH public key, a random salt, and the assigned RequestId (8 bytes).

2. CHALLENGE — client and CA exchange encrypted messages under the session key. The pin challenge requires two rounds:

   • Round 1 (trigger): client sends SelectedChallenge = "pin" with no parameters; CA generates a 6-digit PIN and responds with status = CHALLENGE, challenge_status = "need-code".
   • Round 2 (submit): client sends the PIN code; CA validates and responds with status = SUCCESS and IssuedCertName.

3. Cert fetch — client expresses a plain Interest for the IssuedCertName returned in the CHALLENGE success response.

Both NEW and CHALLENGE Interests are signed with the requester’s key.

Running enrollment in the testbed

The testbed ships an ndncert-ca service for interop testing.

# Start the testbed
docker compose -f testbed/docker-compose.yml up -d nfd-ndncert ndncert-ca

# Run the witness (proves the full round-trip)
bash testbed/tests/audit/c13_ndncert_live_interop.sh

The CA is configured with:

• prefix: /test/ndncert/CA
• challenge: pin (no SMTP infra required)

Using enroll-ndncert directly

enroll-ndncert is the enrollment helper binary built into the interop container. Run it from a shell in the interop container:

docker exec -it interop bash
enroll-ndncert \
    --face-socket /run/nfd-ndncert/nfd.sock \
    --ca-prefix /test/ndncert/CA \
    --name /test/ndncert/CA/my-identity \
    --pin 123456

If --pin is omitted, the binary waits on stdin. The PIN appears in the CA container logs when NDN_LOG=ndncert.challenge.pin=TRACE is set.

CA configuration

{
  "ca-prefix": "/test/ndncert/CA",
  "ca-info": "NDNCERT testbed CA (pin challenge)",
  "max-validity-period": "86400",
  "max-suffix-length": 5,
  "supported-challenges": [
    { "challenge": "pin" }
  ]
}

The CA generates an ephemeral identity via ndnsec key-gen on container start. For a persistent CA, mount a PIB volume and pre-populate it.

Spec references

• NDNCERT 0.3 protocol: github.com/named-data/ndncert/wiki/NDNCERT-Protocol-0.3
• C++ reference CA: named-data/ndncert (src/ca-module.cpp, src/challenge/challenge-pin.cpp)
• Audit finding C.13: docs/notes/spec-compliance-audit-2026-04-20.md § C.13

Performance Tuning

ndn-rs is fast out of the box. But if you’re pushing millions of packets per second or running on constrained hardware, here’s how to squeeze out more performance — and more importantly, how to decide which knobs to turn first.

The single most important principle in performance tuning is this: measure before you change anything. The sections below are organized around the bottleneck you actually have, not the one you think you have. If you skip straight to tweaking settings, you will waste time optimizing the wrong thing.

Find Your Bottleneck First

Not all tuning is equal. Doubling your Content Store size does nothing if your pipeline is CPU-bound. Adding Tokio workers is pointless if your CS lock is the contention point. Before turning any knob, ask: where is my bottleneck?

The following decision tree will guide you to the right section:

flowchart TD
    A["Observe poor performance"] --> B{"Run cargo flamegraph\nor tracing analysis"}
    B --> C{"CPU utilization\nhigh across cores?"}
    C -- Yes --> D{"All cores busy,\nor one core pinned?"}
    D -- "All cores busy" --> E["CPU-bound:\nPipeline parallelism\n& Tokio workers"]
    D -- "One core pinned" --> F["Single-thread bottleneck:\nShardedCs or\nruntime config"]
    C -- No --> G{"Memory pressure\nor OOM?"}
    G -- Yes --> H["Memory-bound:\nCS sizing &\nPIT expiry"]
    G -- No --> I{"Throughput plateaus\nbefore CPU/memory limit?"}
    I -- Yes --> J["Throughput-bound:\nFace buffers, batch size,\nShardedCs"]
    I -- No --> K["Latency-bound:\nCS capacity,\nsingle-thread mode,\nFIB depth"]

    style E fill:#e8f4e8,stroke:#2d7a2d
    style F fill:#e8f4e8,stroke:#2d7a2d
    style H fill:#fff3e0,stroke:#e65100
    style J fill:#e3f2fd,stroke:#1565c0
    style K fill:#fce4ec,stroke:#c62828

CPU-bound

Your cores are maxed out processing packets. The forwarding pipeline itself — TLV decode, CS lookup, PIT operations, FIB longest-prefix match — is consuming all available CPU.

What to do: Increase Tokio worker threads to spread pipeline work across cores. If contention on shared data structures (CS, PIT) is the issue, switch to ShardedCs and confirm PIT sharding via DashMap is effective. See Tokio Runtime Configuration and ShardedCs.

Memory-bound

You’re running out of RAM, or garbage collection / eviction overhead is dominating. This is common on constrained devices or when caching large Data packets.

What to do: Reduce CS capacity, tighten PIT expiry lifetimes, or switch to a no-op CS on embedded targets. See Content Store Sizing and PIT Expiry.

Throughput-bound

CPU and memory look fine, but packets per second plateaus. This usually means something is blocking the pipeline: face readers stalling on a full channel, CS lock contention serializing concurrent lookups, or insufficient buffering on high-speed links.

What to do: Increase pipeline_channel_capacity, enlarge face buffers for fast links, and adopt ShardedCs. See Pipeline Channel Capacity and Face Buffer Sizes.

Latency-bound

Individual packet latency is too high, even though aggregate throughput is acceptable. Packets sit in queues too long, or CS misses dominate when hits would be possible with a larger cache.

What to do: Consider a current-thread runtime to eliminate cross-thread scheduling jitter. Increase CS capacity so more lookups are hits (CS hits short-circuit the pipeline early). Keep FIB prefixes short to reduce trie traversal depth. See Content Store Sizing and FIB Lookup Optimization.

Profiling: How to Find the Actual Bottleneck

⚠️ Important: Always profile before tuning. The most common mistake is optimizing the wrong thing. Run cargo flamegraph or perf record on a realistic workload first — the actual bottleneck is often not where you expect. The Criterion benchmark suite measures individual components in isolation, but production bottlenecks emerge from the interaction between components under load.

Tracing spans

ndn-rs instruments the pipeline with tracing spans. To see where time is spent, attach a tracing subscriber that records span durations. The tracing-timing or tracing-chrome crates produce per-span histograms and Chrome trace files, respectively.

A practical approach: run your workload with RUST_LOG=ndn_engine=trace and a timing subscriber, then look for spans with unexpectedly high durations. Common culprits are cs_lookup, pit_insert, and fib_lpm.

🔍 Tip: The library never initializes a tracing subscriber — that’s your binary’s responsibility. This means you can swap between a lightweight production subscriber and a detailed profiling subscriber without recompiling the engine.

Flamegraphs

Flamegraphs give you a visual map of where CPU time goes:

# Install cargo-flamegraph if needed
cargo install flamegraph

# Generate a flamegraph from a benchmark or your router binary
cargo flamegraph --bin ndn-fwd -- --config my-config.toml

# Or from the benchmark suite
cargo flamegraph --bench pipeline -- --bench "interest_pipeline"

Look for wide bars (functions consuming a lot of time). Common findings:

• Wide bars in TlvDecode — your packets are large or complex; consider whether you need full decode on every path.
• Wide bars in RwLock::read or RwLock::write — lock contention; switch to ShardedCs or check PIT access patterns.
• Wide bars in HashMap::get — FIB or PIT hash collisions; check name distributions.

The benchmark suite

ndn-rs includes a Criterion-based benchmark suite in crates/spec/ndn-engine/benches/pipeline.rs. Use it to measure the impact of individual tuning changes in isolation before applying them to production:

# Run all benchmarks
cargo bench -p ndn-engine

# Run a specific benchmark group
cargo bench -p ndn-engine -- "cs/"

# Generate HTML reports (in target/criterion/)
cargo bench -p ndn-engine
open target/criterion/report/index.html

Key benchmarks to watch:

See Pipeline Benchmarks for detailed results and Methodology for how measurements are collected.

📊 Tip: Run benchmarks with --save-baseline before before a tuning change, then --baseline before after. Criterion will show you a statistical comparison so you know whether your change actually helped or just added noise.

Pipeline Channel Capacity

The engine uses a shared mpsc channel to funnel packets from all face reader tasks into the pipeline runner. This is one of the most impactful tuning knobs because it sits at the convergence point of all inbound traffic.

#![allow(unused)]
fn main() {
let config = EngineConfig {
    pipeline_channel_capacity: 4096, // default: 1024
    ..Default::default()
};
}

The tradeoff: Increasing pipeline_channel_capacity from 1024 to 4096 absorbs traffic bursts — a face reader can dump a batch of received packets without blocking, keeping the network stack moving. But a larger channel uses more memory and, more subtly, can hide backpressure problems. If your pipeline is slow, a deep queue lets packets pile up, increasing latency for all of them. You want the queue deep enough that face readers rarely block, but shallow enough that packets do not age in the queue.

When to increase: If tracing shows face reader tasks spending significant time blocked on channel sends, your channel is too small. This manifests as throughput drops that correlate with high face counts or bursty traffic patterns.

When to decrease: If you care about tail latency more than peak throughput (e.g., real-time applications), a smaller channel ensures packets are processed promptly or dropped, rather than delivered late.

🎯 Tip: The three highest-impact tuning knobs are, in order: (1) ShardedCs on multi-threaded runtimes (eliminates CS lock contention), (2) pipeline channel capacity (prevents face reader stalls), and (3) Tokio worker threads (scales forwarding across cores). Start with these before touching anything else.

Content Store Sizing

The LruCs is sized in bytes, not entry count. This is a deliberate design choice: a Content Store holding 1 KiB Data packets behaves very differently from one holding 100-byte packets, and byte-based sizing adapts automatically.

#![allow(unused)]
fn main() {
let cs = LruCs::new(256 * 1024 * 1024); // 256 MiB
}

The tradeoff: A larger CS means more cache hits, which short-circuit the Interest pipeline early (before PIT insertion, FIB lookup, or outbound forwarding). Each CS hit saves significant work. But memory is finite, and on constrained devices, an oversized CS starves the OS page cache or other processes.

Rules of thumb:

• Router with diverse traffic: 256 MiB – 1 GiB depending on available RAM. The CS stores wire-format Bytes, so the overhead per entry is minimal beyond the packet data itself.
• Edge device / IoT gateway: 16 – 64 MiB. Enough to cache frequently-requested sensor data or configuration objects.
• Embedded (no CS): Use a no-op CS implementation. Zero memory overhead, zero lookup cost.

When the byte limit is exceeded, the least-recently-used entries are evicted. This happens inline during insertion, so eviction cost is amortized across inserts rather than appearing as periodic GC pauses.

ShardedCs for Concurrent Access

Under high concurrency (many pipeline tasks hitting the CS simultaneously), lock contention on a single LruCs becomes the bottleneck. You will see this in flamegraphs as wide bars on RwLock::read or RwLock::write inside CS operations. ShardedCs distributes entries across multiple independent shards, each with its own lock:

#![allow(unused)]
fn main() {
use ndn_store::ShardedCs;

// 16 shards, 256 MiB total (16 MiB per shard).
let cs = ShardedCs::<LruCs>::new(16, 256 * 1024 * 1024);
}

The tradeoff: Sharding eliminates contention but sacrifices global LRU accuracy. Each shard maintains its own LRU list, so an entry that is “least recently used” globally might survive if its shard has capacity, while a more recently used entry in a full shard gets evicted. In practice, with reasonable shard counts (8–32), the hit rate impact is negligible and the throughput gain is substantial.

When to use ShardedCs:

• You are running a multi-threaded Tokio runtime (multi_thread)
• Benchmark or profiling shows CS lock contention
• Pipeline throughput plateaus despite available CPU

When plain LruCs is fine:

• Single-threaded runtimes or low-throughput scenarios
• CS hit rate is low (most Interests miss the cache anyway, so CS access is not the bottleneck)

📊 Performance: In benchmarks, ShardedCs with 16 shards on an 8-core machine shows 3-5x throughput improvement over plain LruCs when the CS hit rate is high. The tradeoff is slightly less optimal LRU ordering (each shard maintains its own LRU list), which can marginally reduce hit rates. For most workloads, the concurrency gain far outweighs the eviction accuracy loss.

FIB Lookup Optimization

The FIB is a name trie with HashMap<Component, Arc<RwLock<TrieNode>>> per level. Longest-prefix match traverses from the root to the deepest matching node, locking each level independently (so concurrent lookups on disjoint branches do not contend).

The key insight: lookup cost is proportional to name depth, not route count. A lookup for /a/b touches 2 trie levels; /a/b/c/d/e/f touches 6. The trie fans out at each level via hash maps, so 1,000 routes under /app with 2-component names is fast, while 10 routes with 10-component names is slower per lookup.

What you can control:

• Keep prefixes short. If your application can use shorter prefixes without ambiguity, do so. This is the single most effective FIB optimization.
• Minimize deep nesting. Hierarchical naming is powerful, but deeply nested names (8+ components) incur measurable per-lookup cost under high Interest rates.

For FIB sizes above ~10,000 routes, monitor LPM latency via the benchmark suite (see Pipeline Benchmarks). At that scale, hash collision rates in per-level HashMaps can start to matter; the benchmark will tell you if they do in your name distribution.

PIT Expiry Interval

PIT entries are expired using a hierarchical timing wheel with O(1) insert and cancel. Entries expire based on their Interest Lifetime (typically 4 seconds), and the timing wheel granularity is 1 ms.

The tradeoff: The timing wheel is efficient by design, so under normal loads you do not need to tune it. However, at extremely high Interest rates (>1M/s), the expiry tick task competes with pipeline work for Tokio worker time. If expiry falls behind, stale PIT entries accumulate, consuming memory and potentially causing false aggregation (a new Interest matches a stale PIT entry instead of being forwarded).

What to do if PIT memory grows: Check whether the timing wheel tick task is being starved. If it is, either dedicate a Tokio worker thread to it or use spawn_blocking for the expiry sweep. On memory-constrained devices, consider reducing the default Interest Lifetime at the application level to keep PIT entries short-lived.

⚠️ Warning: Reducing Interest Lifetime aggressively (below 1 second) can cause legitimate Interests to expire before Data returns, leading to retransmissions that increase load rather than reducing it. Only shorten lifetimes if your RTT budget genuinely supports it.

Face Buffer Sizes

Each face uses bounded mpsc channels for inbound and outbound packet buffering. The buffer size determines the tradeoff between burst absorption and memory usage.

#![allow(unused)]
fn main() {
// In your face constructor:
let (tx, rx) = mpsc::channel(256); // 256 packets
}

The tradeoff: Larger buffers absorb traffic bursts without dropping packets, which is critical on high-speed links where a momentary pipeline stall could cause packet loss. But each buffer slot holds a Bytes handle (~32 bytes plus the packet data), so over-buffering across many faces adds up. On a router with 100 active faces, the difference between 128 and 2048 per face is significant.

🔍 Tip: If you see packet drops on a face but the pipeline has spare capacity, the face buffer is too small. If you see high memory usage but low throughput, the face buffers may be too large across too many idle faces. Consider dynamically sizing buffers based on link speed if you have heterogeneous faces.

Tokio Runtime Configuration

ndn-rs is built on Tokio throughout. The runtime configuration is one of the highest-leverage tuning decisions because it determines how pipeline work is scheduled across cores.

Multi-threaded runtime (recommended for routers)

#![allow(unused)]
fn main() {
let rt = tokio::runtime::Builder::new_multi_thread()
    .worker_threads(4)       // match available cores
    .max_blocking_threads(2) // for CS persistence, crypto
    .enable_all()
    .build()?;
}

worker_threads controls how many OS threads run the Tokio executor. Set this to the number of cores you want dedicated to forwarding. On a 4-core router, use 4. On a shared system where other services need CPU, use fewer. More workers means more parallelism, but also more contention on shared data structures (CS, PIT, FIB locks) — which is why ShardedCs matters on multi-threaded runtimes.

max_blocking_threads caps the thread pool used for blocking operations: PersistentCs (RocksDB/redb) disk I/O and signature validation. 2 is usually enough. Increasing this only helps if profiling shows blocking tasks queueing up.

Current-thread runtime (embedded / latency-sensitive)

#![allow(unused)]
fn main() {
let rt = tokio::runtime::Builder::new_current_thread()
    .enable_all()
    .build()?;
}

All tasks run cooperatively on one thread — no synchronization overhead, no cross-thread scheduling jitter, but no parallelism. This is the right choice for:

• Embedded deployments where only one core is available
• Latency-sensitive applications where predictable per-packet timing matters more than aggregate throughput
• Testing and debugging where deterministic execution simplifies reasoning

🔍 Tip: A single-threaded runtime with plain LruCs often has lower per-packet latency than a multi-threaded runtime with ShardedCs, because there is no lock contention or cross-thread wake-up cost. If your bottleneck is latency rather than throughput, try single-threaded first.

Thread pinning on NUMA systems

For maximum throughput on NUMA systems, pin Tokio workers to specific cores to avoid cross-socket memory access:

#![allow(unused)]
fn main() {
let rt = tokio::runtime::Builder::new_multi_thread()
    .worker_threads(4)
    .on_thread_start(|| {
        // Pin to core using core_affinity or similar crate.
    })
    .build()?;
}

This is an advanced optimization that only matters on multi-socket servers. If you are running on a single-socket machine or a VM, thread pinning provides no benefit.

Putting It All Together

The tuning process should follow this cycle:

1. Profile your workload with tracing and flamegraphs. Identify the actual bottleneck.
2. Change one thing. Adjust the knob that addresses your identified bottleneck.
3. Benchmark. Run the Criterion suite or your production workload and compare before/after.
4. Repeat. If performance is still insufficient, profile again — the bottleneck may have shifted.

⚠️ Important: Resist the urge to change multiple settings at once. If you increase channel capacity, switch to ShardedCs, and add worker threads simultaneously, you will not know which change helped (or hurt). Methodical, one-change-at-a-time tuning converges faster than shotgun optimization.

Quick reference: which knob for which bottleneck

Setting Up an NDNCERT CA

This guide walks through standing up an NDNCERT certificate authority from scratch. By the end you will have a running CA that accepts enrollment requests, issues 24-hour certificates, and handles both factory token provisioning and renewal via possession proof.

If you are deploying a fleet of devices and want the full architectural context, read Fleet and Swarm Security first. This guide focuses on the mechanics.

Prerequisites

• A running NDN router (ndn-fwd on the same host, or reachable via UDP/Ethernet)
• Rust toolchain and the ndn-rs workspace checked out
• An identity for the CA (either self-signed or issued by a higher-level CA)

The CA uses ndn-identity, ndn-cert, and ndn-app. Add them to your Cargo.toml:

[dependencies]
ndn-identity = { path = "crates/spec/ndn-identity" }
ndn-cert     = { path = "crates/spec/ndn-cert" }
ndn-app      = { path = "crates/spec/ndn-app" }
tokio        = { version = "1", features = ["full"] }
anyhow       = "1"

Step 1: Create the CA Identity

The CA needs its own NDN identity — a key pair and a self-signed certificate (for a root CA) or a certificate issued by a higher authority (for a sub-CA). Use NdnIdentity::open_or_create so the identity persists across restarts.

#![allow(unused)]
fn main() {
use std::path::PathBuf;
use ndn_identity::NdnIdentity;

// Create (or load from disk) the CA's identity
let ca_identity = NdnIdentity::open_or_create(
    &PathBuf::from("/var/lib/ndn/ca-identity"),
    "/example/ca",
).await?;

println!("CA identity: {}", ca_identity.name());
println!("CA DID:      {}", ca_identity.did());
}

If /var/lib/ndn/ca-identity is empty, open_or_create generates a new Ed25519 key pair and creates a self-signed certificate. On subsequent runs, it loads the existing key and certificate from disk. The identity directory should be on a persistent, access-controlled volume — it contains the CA’s private key.

For a sub-CA whose certificate was issued by a root CA, you would provision it with NdnIdentity::provision (see Step 5 of the Fleet Security guide) and then load it with open_or_create for subsequent CA operations.

Step 2: Configure Challenge Handlers

Challenges are how the CA verifies that an applicant is authorized to receive a certificate. You can configure multiple challenge types on a single CA; the CA advertises them all in its INFO response and the applicant picks the one it supports.

Token Challenge

Best for factory provisioning (ZTP). Pre-generate tokens and burn them into firmware.

#![allow(unused)]
fn main() {
use ndn_cert::{TokenStore, TokenChallenge};

let mut store = TokenStore::new();

// Add individual tokens
store.add("tok-a3f9b2e1d4c5".to_string());
store.add("tok-7e8f1a2b3c4d".to_string());

// Or add a batch
let tokens: Vec<String> = generate_tokens(1000);
store.add_many(tokens);

let token_challenge = TokenChallenge::new(store);
}

Tokens are single-use and permanently consumed when presented. There is no way to “reset” a token — generate new ones if needed.

Possession Challenge

Best for renewal and sub-namespace enrollment. The applicant proves it holds a certificate that the CA already trusts.

#![allow(unused)]
fn main() {
use ndn_cert::PossessionChallenge;
use ndn_security::Certificate;

// Trust anything signed by our own CA cert (for renewals)
let ca_cert = ca_identity.security_manager().get_certificate()?;
let possession_challenge = PossessionChallenge::new(vec![ca_cert]);

// Or trust a set of root-of-trust certificates (for ECU enrollment)
let ecu_roots: Vec<Certificate> = load_hardware_root_certs()?;
let ecu_challenge = PossessionChallenge::new(ecu_roots);
}

Step 3: Configure Namespace Policy

The namespace policy controls which certificate requests the CA will accept. The two main options are HierarchicalPolicy (default, recommended for most deployments) and DelegationPolicy (for custom rules).

#![allow(unused)]
fn main() {
use ndn_cert::HierarchicalPolicy;

// HierarchicalPolicy: only accept namespaces that are suffixes of the CA's own name.
// CA name: /example/ca
// Accepted: /example/ca/devices/sensor-001
//           /example/ca/users/alice
// Rejected: /other-org/device/001  (different prefix)
//           /example               (CA's own name — not issued to applicants)
let policy = HierarchicalPolicy;
}

For a CA named /fleet/ca, this means it only issues certificates under /fleet/ca/.... If you want the CA to issue for /fleet/... (dropping the ca component), use a DelegationPolicy with explicit rules.

Step 4: Build and Start the CA

#![allow(unused)]
fn main() {
use std::time::Duration;
use ndn_cert::NdncertCa;
use ndn_app::Producer;

let ca = NdncertCa::builder()
    .name("/example/ca")
    .signing_identity(&ca_identity)
    .challenge(token_challenge)
    .challenge(possession_challenge)
    .policy(HierarchicalPolicy)
    .cert_lifetime(Duration::from_secs(24 * 3600)) // 24 hours
    .build()?;

// Register the CA prefix with the router and start serving
let producer = Producer::connect("/run/nfd/nfd.sock", "/example/ca").await?;

println!("NDNCERT CA running on /example/ca");
ca.serve(producer).await?;
}

ca.serve(producer) drives the CA’s event loop — it processes incoming INFO, NEW, and CHALLENGE Interests until the producer is shut down. This call does not return until the producer is dropped or the router disconnects.

Step 5: Provision a Device

On the device side, NdnIdentity::provision handles the full NDNCERT client exchange:

#![allow(unused)]
fn main() {
use std::path::PathBuf;
use ndn_identity::{NdnIdentity, DeviceConfig, FactoryCredential, RenewalPolicy};

let config = DeviceConfig {
    namespace: "/example/ca/devices/sensor-001".to_string(),
    storage: PathBuf::from("/var/lib/ndn/sensor-identity"),
    factory_credential: FactoryCredential::Token("tok-a3f9b2e1d4c5".to_string()),
    ca_prefix: "/example/ca".parse()?,
    renewal: RenewalPolicy::WhenPercentRemaining(20),
    delegate: None,
};

let identity = NdnIdentity::provision(config).await?;
println!("Provisioned: {}", identity.did());
// → did:ndn:example:ca:devices:sensor-001
}

Step 6: Verify the Certificate Chain

After provisioning, verify the full chain from the device cert back to the trust anchor:

#![allow(unused)]
fn main() {
use ndn_security::{Validator, TrustSchema};

// Load the CA's certificate as a trust anchor
let ca_cert = ca_identity.security_manager().get_certificate()?;

// Build a validator that trusts the CA cert
let validator = Validator::builder()
    .trust_anchor(ca_cert)
    .schema(TrustSchema::hierarchical())
    .build();

// Fetch a Data packet signed by the device
let data: Data = /* ... */;

match validator.validate_chain(&data).await {
    ValidationResult::Valid(safe_data) => println!("valid: chain verified"),
    ValidationResult::Invalid(e) => eprintln!("invalid: {e}"),
    ValidationResult::Pending => println!("cert not yet fetched"),
}
}

Generating Provisioning Tokens

For factory-scale deployments, generate tokens programmatically and hand them to the manufacturing system:

#![allow(unused)]
fn main() {
use ndn_cert::TokenStore;

fn generate_tokens(count: usize) -> Vec<String> {
    use rand::Rng;
    let mut rng = rand::thread_rng();
    (0..count)
        .map(|_| {
            let bytes: [u8; 16] = rng.gen();
            format!("tok-{}", hex::encode(bytes))
        })
        .collect()
}

// Generate 10,000 tokens for a production run
let tokens = generate_tokens(10_000);

// Write them to a file for the manufacturing system
let csv = tokens.join("\n");
std::fs::write("factory-tokens.csv", csv)?;

// Load them into the CA's token store
let mut store = TokenStore::new();
store.add_many(tokens);
}

Keep the token list in a secure location. A leaked token list allows unauthorized enrollment under your CA’s namespace.

Running Multiple CA Replicas

To run a second CA replica for high availability, point it at the same identity storage (read-only — the key material is the same on all replicas) and the same distributed token store. Register all replicas under the same prefix in the FIB.

FIB entry:  /example/ca → face-1 (CA replica A)
                          face-2 (CA replica B)
                          face-3 (CA replica C)

The forwarder distributes Interests across all registered faces. If one replica is unreachable, Interests naturally route to the others (with a brief delay for the forwarder’s dead face detection).

For possession challenges, there is no shared state — each replica independently verifies the proof. For token challenges, the TokenStore backend must be shared (e.g., backed by Redis or etcd) so a token consumed at one replica is not reusable at another.

#![allow(unused)]
fn main() {
// Replica A and Replica B both use the same distributed token store
let store = TokenStore::from_redis("redis://ca-token-store:6379")?;
}

Rotating the CA Certificate

CA certificate rotation is a planned operation. The procedure:

1. Offline ceremony: On the machine holding the root (or parent) CA, issue a new sub-CA certificate with a later validity period. This is done with the same NDNCERT exchange, with the root CA as the issuer.

2. Update trust anchors: Distribute the new CA certificate to all validators in your fleet. This can be done via NDN sync (SVS) — validators subscribe to a trust anchor sync group and pick up the new cert automatically.

3. Transition period: Run the old and new CA certificates simultaneously. Devices renewing during the transition may receive either. Both are valid because both chain to the same root.

4. Retire old cert: Once the old CA cert’s validity period expires, it is automatically invalid. No explicit retirement step needed — short-lived certs handle this naturally.

The root CA offline ceremony is the most sensitive step. Use an air-gapped machine, record the ceremony, and rotate root CA certs infrequently (once every few years is typical).

Full Working Example

Here is a complete, self-contained CA and client example you can run directly:

use std::path::PathBuf;
use std::time::Duration;
use ndn_identity::{NdnIdentity, DeviceConfig, FactoryCredential, RenewalPolicy};
use ndn_cert::{NdncertCa, TokenStore, TokenChallenge, PossessionChallenge, HierarchicalPolicy};
use ndn_app::Producer;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // --- CA setup ---

    let ca_identity = NdnIdentity::open_or_create(
        &PathBuf::from("/tmp/demo-ca-identity"),
        "/demo/ca",
    ).await?;

    let mut token_store = TokenStore::new();
    token_store.add("demo-token-abc123".to_string());

    let ca_cert = ca_identity.security_manager().get_certificate()?;
    let possession = PossessionChallenge::new(vec![ca_cert]);

    let ca = NdncertCa::builder()
        .name("/demo/ca")
        .signing_identity(&ca_identity)
        .challenge(TokenChallenge::new(token_store))
        .challenge(possession)
        .policy(HierarchicalPolicy)
        .cert_lifetime(Duration::from_secs(24 * 3600))
        .build()?;

    let producer = Producer::connect("/run/nfd/nfd.sock", "/demo/ca").await?;

    // Spawn the CA in the background
    tokio::spawn(async move {
        ca.serve(producer).await.expect("CA failed");
    });

    // --- Device provisioning ---

    let device_config = DeviceConfig {
        namespace: "/demo/ca/device/001".to_string(),
        storage: PathBuf::from("/tmp/demo-device-identity"),
        factory_credential: FactoryCredential::Token("demo-token-abc123".to_string()),
        ca_prefix: "/demo/ca".parse()?,
        renewal: RenewalPolicy::WhenPercentRemaining(20),
        delegate: None,
    };

    let device_identity = NdnIdentity::provision(device_config).await?;

    println!("Device enrolled!");
    println!("  Name: {}", device_identity.name());
    println!("  DID:  {}", device_identity.did());

    // Use the device signer to sign Data packets
    let signer = device_identity.signer()?;
    println!("  Key name: {}", signer.key_name());

    Ok(())
}

See Also

• NDNCERT Protocol Deep Dive — how the protocol works internally
• Fleet and Swarm Security — large-scale deployment patterns
• Identity and DIDs — how NDNCERT-issued certs map to W3C DIDs
• Building NDN Applications — using NdnIdentity in your application

Fleet and Swarm Security

The Scene

It is 3 AM in a logistics hub. Somewhere on a production line, vehicle number 7,432 rolls off the assembly and is loaded onto a transport truck before sunrise. By noon it will be in a distribution center three states away. By next week it will be making autonomous deliveries in a city it has never visited.

That vehicle needs a cryptographic identity. Every sensor reading it produces, every route update it broadcasts, every command it receives — all of it needs to be signed and verifiable. Not because of a compliance checkbox, but because in an autonomous vehicle network, an unsigned packet is an unsigned check: you have no idea who wrote it or whether it has been tampered with.

You have 10,000 vehicles. Managing 10,000 keys manually is not an option. Neither is shipping them all to a central server for enrollment — that server becomes a single point of failure for your entire fleet. You need a system that:

• Provisions each vehicle automatically, with no human steps per vehicle
• Works even when individual vehicles are temporarily offline
• Allows each vehicle to bootstrap its own sub-systems without internet access
• Makes “revoke this vehicle” as simple as pressing a button, with no CRL distribution
• Scales to sub-systems: a vehicle has 40+ ECUs, each of which also needs a verifiable identity

This guide walks through exactly that system, built on NDNCERT and ndn-security.

The Trust Hierarchy

Before touching any code, it helps to visualize the chain of trust you are building:

Manufacturer root CA
(offline, air-gapped, ceremony once per year)
    │
    └── Fleet operations CA    ← online, runs NDNCERT, issues 24h vehicle certs
    │   /fleet/ca
    │       │
    │       └── Vehicle identity    ← auto-renewed every ~19h
    │           /fleet/vehicle/<vin>
    │               │
    │               └── ECU certs    ← issued by the vehicle itself, offline
    │                   /fleet/vehicle/<vin>/ecu/brake
    │                   /fleet/vehicle/<vin>/ecu/lidar
    │                   /fleet/vehicle/<vin>/ecu/camera-front
    │                   /fleet/vehicle/<vin>/ecu/gps
    │                   ...

Each arrow represents a certificate signature. The root CA signs the fleet operations CA cert. The fleet CA signs each vehicle cert. Each vehicle signs its ECU certs. A remote verifier who holds the root CA cert as a trust anchor can walk this chain and verify the authenticity of a sensor reading from a front camera three levels deep — without contacting any CA at verification time.

The offline root CA is critical. If the fleet operations CA is compromised, you can revoke it from the offline root and reissue a new operations CA cert without changing the trust anchor burned into your systems. The blast radius of a CA compromise is bounded by the namespace scope of that CA.

Factory Provisioning: Zero Human Steps

At manufacture time, the factory generates a unique one-time token for each vehicle and burns it into the firmware alongside the fleet CA prefix. This is the only provisioning step that requires access to the factory system. Everything else happens automatically.

On first boot, the vehicle calls NdnIdentity::provision. This is a single async call that handles the entire NDNCERT exchange:

#![allow(unused)]
fn main() {
use std::path::PathBuf;
use ndn_identity::{NdnIdentity, DeviceConfig, FactoryCredential, RenewalPolicy};

let vin = read_vin_from_hardware(); // e.g. "1HGBH41JXMN109186"
let token = read_factory_token_from_firmware(); // burned in at manufacture

let config = DeviceConfig {
    // The namespace this vehicle will own
    namespace: format!("/fleet/vehicle/{vin}"),
    // Where to persist the identity (survives reboots)
    storage: PathBuf::from("/var/lib/ndn/identity"),
    // The pre-provisioned token from the factory
    factory_credential: FactoryCredential::Token(token),
    // Where to find the fleet CA
    ca_prefix: "/fleet/ca".parse()?,
    // Renew when 20% lifetime remains (~19h for 24h certs)
    renewal: RenewalPolicy::WhenPercentRemaining(20),
    // No additional delegation needed
    delegate: None,
};

let identity = NdnIdentity::provision(config).await?;

println!("enrolled as: {}", identity.did());
// → did:ndn:fleet:vehicle:1HGBH41JXMN109186
}

Under the hood, provision does the following:

1. Generates an Ed25519 key pair (or loads an existing one from storage if this is a restart after partial provisioning)
2. Sends an INFO Interest to /fleet/ca/INFO to get the CA’s certificate and challenge type
3. Sends a NEW Interest with the vehicle’s public key and desired namespace
4. Responds to the token challenge with the factory token
5. Receives the signed certificate from the CA
6. Saves the certificate and private key to storage
7. Starts the background renewal task

From this point on, NdnIdentity::open_or_create will load the existing identity without re-enrolling:

#![allow(unused)]
fn main() {
// Subsequent boots: loads from disk, no NDNCERT exchange needed
let identity = NdnIdentity::open_or_create(
    &PathBuf::from("/var/lib/ndn/identity"),
    &format!("/fleet/vehicle/{vin}")
).await?;
}

The provisioning token is single-use. If someone intercepts the provisioning exchange and tries to replay the token, the CA rejects it — the token is already marked consumed. An attacker would need to intercept the token before the vehicle uses it, which requires access to the firmware at manufacture time.

ECU Delegation: The Vehicle as a Mini-CA

After the vehicle is enrolled, it starts its own NDNCERT CA for its sub-systems. This happens before any internet-facing communication — the ECU enrollment runs over the vehicle’s internal network (CAN bus, automotive Ethernet, or internal WiFi).

#![allow(unused)]
fn main() {
use ndn_cert::{NdncertCa, PossessionChallenge, HierarchicalPolicy};
use ndn_app::Producer;

// The vehicle's identity (just enrolled above)
let vehicle_identity = NdnIdentity::open_or_create(/* ... */).await?;

// Start a CA that issues certs under the vehicle's namespace
let ca = NdncertCa::builder()
    .name(format!("/fleet/vehicle/{vin}/ca"))
    .signing_identity(&vehicle_identity)
    // ECUs prove ownership by signing with a hardware root-of-trust key
    // (burned into the ECU at manufacture and stored in the vehicle's manifest)
    .challenge(PossessionChallenge::new(load_ecu_root_certs()?))
    // Only allow namespaces under /fleet/vehicle/<vin>/ecu/
    .policy(HierarchicalPolicy)
    .cert_lifetime(Duration::from_secs(7 * 24 * 3600)) // 1 week for ECUs
    .build()?;

// Serve over the internal network face
let producer = Producer::connect("/var/run/ndn-internal.sock", "/fleet/vehicle").await?;
ca.serve(producer).await?;
}

Each ECU’s firmware knows its own role name (e.g., brake, lidar, camera-front) and runs a matching provisioning sequence using FactoryCredential::Existing, which presents the ECU’s hardware-bound root-of-trust certificate as a possession proof:

#![allow(unused)]
fn main() {
// On the brake ECU:
let ecu_config = DeviceConfig {
    namespace: format!("/fleet/vehicle/{vin}/ecu/brake"),
    storage: PathBuf::from("/var/lib/ndn/ecu-identity"),
    factory_credential: FactoryCredential::Existing {
        cert_name: load_hardware_cert_name()?,
        key_seed: load_hardware_key_seed()?,
    },
    ca_prefix: format!("/fleet/vehicle/{vin}/ca").parse()?,
    renewal: RenewalPolicy::WhenPercentRemaining(10),
    delegate: None,
};

let ecu_identity = NdnIdentity::provision(ecu_config).await?;
}

This entire ECU enrollment happens on the vehicle’s internal bus. The vehicle does not need internet connectivity. The fleet CA does not need to know that ECUs exist. The vehicle is the trust authority for its own sub-systems.

Renewal: 24 Hours Without Drama

Vehicle certs have a 24-hour lifetime. Renewal is fully automatic. The background renewal task in NdnIdentity watches the certificate’s validity period and, when the remaining lifetime falls below the configured threshold (20% by default, i.e., about 19h into a 24h cert), initiates a new NDNCERT exchange using the possession challenge — the vehicle’s current valid certificate is the proof of identity.

Time 0h:    Vehicle enrolls, receives 24h cert
Time 19h:   Renewal threshold reached (80% used)
            Background task sends CHALLENGE Interest to /fleet/ca
            using possession of current cert as proof
            Fleet CA issues new 24h cert
Time 24h:   Old cert expires (renewal already done at 19h)

If the fleet CA is unreachable when renewal is attempted, the background task retries with exponential backoff. The vehicle continues operating on its current certificate. As long as the vehicle reconnects to the CA within the remaining 5 hours of validity, renewal succeeds before expiry.

For a vehicle that is completely offline for more than 24 hours — say, in an underground facility with no network coverage — the cert expires. When the vehicle reconnects, it re-enrolls using the possession challenge with its recently-expired cert. The CA can be configured to accept certs that expired within a grace period (configurable per CA policy), or it can require a new token (which the fleet operator provisions through the management interface). Either way, the human burden is minimal.

Revocation Without CRL

Short-lived certs make revocation simple enough that it barely deserves the word “revocation”. Here is the entire process for decommissioning a compromised vehicle:

1. An operator opens the fleet management console and marks VIN-1234 as revoked.
2. The console calls the CA’s management API: ca.policy().block_namespace("/fleet/vehicle/vin-1234").
3. The next time VIN-1234 tries to renew (within 5 hours), the CA rejects the renewal request.
4. The vehicle’s certificate expires within 24 hours of the compromise being detected.

No CRL file to publish. No OCSP responder to query. No list of revoked serials to distribute to 10,000 other vehicles. The network does not need to know anything. Each vehicle’s cert either renews successfully or it does not, and within 24 hours of a failed renewal, the cert is gone.

For emergency situations where you cannot wait 24 hours, push a trust schema update that explicitly rejects the compromised namespace. This update propagates through NDN sync (SVS) to all validators in the fleet within seconds. But in practice, operators rarely need this — 24 hours is a small window for most threat scenarios.

Drone Swarms: The Same Model, No Infrastructure

The same architecture applies to a swarm of 500 drones. The key difference: there may be no internet connection at all. The swarm operates as an ad-hoc NDN mesh.

The swarm includes one or more CA nodes — designated drones (or a ground station) that run the fleet CA. The CA nodes run NDNCERT. Other drones in the swarm enroll by sending Interests that route through the mesh to the nearest CA node.

Because NDN routing is name-based, a drone doesn’t need to know which CA node handles its request. It just sends an Interest for /swarm/ca/INFO, and the forwarder routes it to whichever CA node has a FIB entry for that prefix. If one CA node crashes or flies out of range, the FIB re-converges and requests route to the next nearest CA.

#![allow(unused)]
fn main() {
// A drone in the swarm — same provisioning code as a vehicle
let drone_config = DeviceConfig {
    namespace: format!("/swarm/drone/{serial}"),
    storage: PathBuf::from("/data/ndn-identity"),
    factory_credential: FactoryCredential::Token(firmware_token),
    ca_prefix: "/swarm/ca".parse()?,
    renewal: RenewalPolicy::WhenPercentRemaining(20),
    delegate: None,
};

// This Interest routes through the ad-hoc mesh to the nearest CA node
// No IP, no DNS, no internet required
let identity = NdnIdentity::provision(drone_config).await?;
}

A nearby drone can relay the enrollment Interest through NDN’s normal forwarding. If the direct link to the CA is down, the Interest travels through intermediate nodes. This works because NDN routing is hop-by-hop and content-centric: any node with a FIB route to /swarm/ca will forward the Interest toward the CA.

Setting Up the Fleet CA

The fleet operations CA runs on a server (or a cluster of servers for high availability). Here is its complete setup:

use std::path::PathBuf;
use std::time::Duration;
use ndn_identity::{NdnIdentity, DeviceConfig, FactoryCredential, RenewalPolicy};
use ndn_cert::{NdncertCa, TokenStore, TokenChallenge, PossessionChallenge, HierarchicalPolicy};
use ndn_app::Producer;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // The fleet CA's own identity — issued by the root CA during an offline ceremony
    // Stored on disk; load it (or create it if this is the first run)
    let ca_identity = NdnIdentity::open_or_create(
        &PathBuf::from("/var/lib/ndn/fleet-ca-identity"),
        "/fleet/ca",
    ).await?;

    println!("Fleet CA running as: {}", ca_identity.did());

    // Token store: pre-loaded with factory tokens for all vehicles
    // (this list comes from the manufacturing system)
    let mut token_store = TokenStore::new();
    for token in load_factory_tokens_from_manufacturing_db()? {
        token_store.add(token);
    }

    // Possession challenge: allows renewal using an existing /fleet cert
    let fleet_root_cert = ca_identity.security_manager().get_certificate()?;
    let possession = PossessionChallenge::new(vec![fleet_root_cert]);

    // Build the CA
    let ca = NdncertCa::builder()
        .name("/fleet/ca")
        .signing_identity(&ca_identity)
        // Support both challenges: token for first enrollment, possession for renewal
        .challenge(TokenChallenge::new(token_store))
        .challenge(possession)
        // Only issue for /fleet/ namespace
        .policy(HierarchicalPolicy)
        // 24-hour certs
        .cert_lifetime(Duration::from_secs(24 * 3600))
        .build()?;

    // Connect to the router and register the CA prefix
    let producer = Producer::connect("/run/nfd/nfd.sock", "/fleet/ca").await?;

    println!("Fleet CA accepting enrollment requests...");
    ca.serve(producer).await?;

    Ok(())
}

For high availability, run two or three instances of this process, all pointing to the same (distributed) token store. Register all of them under the /fleet/ca prefix in the FIB. The forwarder load-balances across them.

What You Have Built

At the end of this setup:

• 10,000 vehicles each have a cryptographically verifiable identity, issued automatically with no human steps per vehicle.
• Each vehicle’s sub-systems have their own identities, issued by the vehicle without internet access.
• Every packet in the fleet is signed. Every signature can be traced back to the root CA that you control.
• Compromised vehicles are effectively decommissioned within 24 hours of detection, with no infrastructure changes.
• The entire trust infrastructure runs over NDN — it works on UDP, Ethernet, internal CAN bus, or a drone swarm mesh network with no internet connection.

See Also

• NDNCERT: Automated Certificate Issuance — the protocol details behind NdnIdentity::provision
• Identity and Decentralized Identifiers — how vehicle identities map to W3C DIDs
• Setting Up an NDNCERT CA — step-by-step CA configuration reference
• Security Model — the certificate chain validation that makes all of this work

Management Command Security

ndn-fwd requires key-backed signed Interests for privileged management commands by default. This page explains how to configure trust anchors, sign commands with ndn-ctl, and opt out for local dev setups.

Background

NFD’s command authenticator (Developer Guide §7) accepts only key-backed signatures (Ed25519, ECDSA, RSA, BLAKE3) on command Interests. DigestSha256 verifies integrity but does not establish key identity and is treated as unsigned for authorization purposes.

ndn-fwd mirrors this behavior via the [security.mgmt] config section.

Quick start

1. Generate an identity rig

cargo build -p ndn-tools --bins
./testbed/configs/identities/gen_identities.sh --pib /etc/ndn/pib

This creates two keys in /etc/ndn/pib:

2. Configure ndn-fwd

[security.mgmt]
require_signed_commands = true
trust_anchor_pib        = "/etc/ndn/pib"

Startup aborts if trust_anchor_pib is set but the PIB is missing or contains no trust anchors. Fix by running gen_identities.sh or adding require_signed_commands = false to opt out (see below).

3. Sign commands with ndn-ctl

# With key-backed signature — accepted when anchors are configured:
ndn-ctl --identity /test/admin --pib /etc/ndn/pib route add /ndn --face 1

# Without --identity — DigestSha256 only, rejected when require_signed_commands=true:
ndn-ctl route add /ndn --face 1

Dev / single-host mode

For local testing without a provisioned identity, disable signing enforcement:

[security.mgmt]
require_signed_commands = false

Unsigned and DigestSha256-signed commands are then accepted with a warning logged at each dispatch.

Trust anchor PIB layout

The PIB is a directory with two subdirectories:

pib/
  keys/
    <hash>/          # keyed by sha256(name)
      private.key    # 32-byte Ed25519 seed
      cert.ndnc      # NDNC-format certificate
      name.uri       # NDN name URI
  anchors/
    <hash>/          # same hash scheme
      cert.ndnc
      name.uri

ndn-fwd loads only the anchors/ entries at startup; the keys/ entries are for ndn-ctl --identity signing.

Add or remove trust anchors

# Mark an existing key as a trust anchor:
ndn-sec --pib /etc/ndn/pib anchor add /test/admin

# Remove a trust anchor (does not delete the key):
ndn-sec --pib /etc/ndn/pib anchor remove /test/old-key

# List all trust anchors:
ndn-sec --pib /etc/ndn/pib anchor list

Restart ndn-fwd after changing the PIB — trust anchors are loaded once at startup.

Default behavior and upgrades

As of 2026-05-07 the default for require_signed_commands is true. Deployments that upgrade without adding [security.mgmt] will reject all management commands. The options are:

• Production: add trust_anchor_pib pointing to a prepared PIB.
• Dev / local: add require_signed_commands = false explicitly.

See docs/notes/spec-compliance-audit-2026-04-20.md § E.01 for full audit history and the live witness at testbed/tests/audit/e01_signed_mgmt_ndn_fwd.sh.

Design Philosophy

NDN as Composable Data Pipelines

ndn-rs models NDN packet processing as composable data pipelines with trait-based polymorphism.

A packet enters the system as a Bytes buffer from a face, flows through a sequence of PipelineStage trait objects by value, and exits as a Bytes buffer sent to one or more faces. Each stage receives ownership of the PacketContext, processes it, and either passes it forward or consumes it (short-circuiting). The compiler enforces that no stage can use a packet after handing it off.

Extension points are flat traits composed by wrapping types (e.g., StrategyFilter wraps a Strategy, ShardedCs wraps a ContentStore). This makes the extension points orthogonal – any strategy can be combined with any filter.

flowchart LR
    subgraph "Interest Pipeline"
        A["FaceCheck"] -->|"Continue"| B["TlvDecode"]
        B -->|"Continue"| C["CsLookup"]
        C -->|"Continue\n(miss)"| D["PitCheck"]
        C -->|"Send\n(hit)"| OUT["Dispatch"]
        D -->|"Continue"| E["Strategy"]
        E -->|"Forward / Nack\n/ Suppress"| OUT
    end

    style A fill:#e8f4fd,stroke:#2196F3
    style B fill:#e8f4fd,stroke:#2196F3
    style C fill:#fff3e0,stroke:#FF9800
    style D fill:#e8f4fd,stroke:#2196F3
    style E fill:#f3e5f5,stroke:#9C27B0
    style OUT fill:#e8f5e9,stroke:#4CAF50

Each stage receives PacketContext by value and returns an Action enum. The dispatcher inspects the action and either passes PacketContext to the next stage or terminates the pipeline.

Library, Not Daemon

ndn-rs is a library. There is no daemon/client split. The forwarding engine (ndn-engine) is a Rust library that any application can embed directly. The standalone router (ndn-fwd) is just one binary that links against this library; applications can equally embed the engine in-process and get a thin InProcFace backed by a shared memory ring buffer.

This means the same codebase runs as a full router, an embedded forwarder on a microcontroller (via ndn-embedded with no_std), or an in-process forwarder inside an application. No rewrite required.

Note: Applications can embed the forwarding engine directly and communicate via in-process InProcFace channels. The standalone ndn-fwd binary is one consumer of this library, not a privileged component.

Key Design Decisions

Trait-Based Polymorphism

Every extension point in ndn-rs is a trait:

• Face – async send/recv over any transport (UDP, TCP, Ethernet, serial, shared memory, Bluetooth, Wifibroadcast)
• PipelineStage – a single processing step that takes a PacketContext by value and returns an Action
• Strategy – a forwarding decision function that reads StrategyContext and returns ForwardingAction values
• ContentStore – pluggable cache backend (LruCs, ShardedCs, FjallCs)
• Signer / Verifier – cryptographic operations decoupled from packet types
• DiscoveryProtocol – neighbor and service discovery (NeighborProbeProtocol, AutoConfigDiscovery, etc.)

This trait-based approach means new transports, strategies, and cache backends can be added without modifying the core pipeline. The built-in pipeline is monomorphised at compile time for zero-cost dispatch; only plugin stages use dynamic dispatch via ErasedPipelineStage.

🔧 Implementation note: The built-in pipeline stages are monomorphised (generic, not dyn) so the compiler can inline and optimize the hot path. Only user-provided plugin stages go through dyn PipelineStage (via ErasedPipelineStage). This means the common case pays zero dynamic dispatch cost while still allowing runtime extensibility.

graph TB
    STrait["trait Strategy"]
    STrait -->|"impl"| BR2["BestRouteStrategy"]
    STrait -->|"impl"| MC2["MulticastStrategy"]
    STrait -->|"impl"| ASF2["AsfStrategy"]
    STrait -.->|"impl for any type"| NEW2["MyStrategy"]
    FTrait["trait StrategyFilter"] -->|"compose"| BR2
    FTrait -->|"compose"| MC2

    style STrait fill:#c8e6c9,stroke:#4CAF50
    style FTrait fill:#c8e6c9,stroke:#4CAF50

Concurrency Model

ndn-rs is built on Tokio. Each face runs its own async task, pushing RawPacket values into a shared mpsc channel. A single pipeline runner drains the channel and processes packets inline through the stage sequence. A separate expiry task drains expired PIT entries on a 1 ms tick using a hierarchical timing wheel.

%%{init: {"layout": "elk"}}%%
graph TD
    subgraph Faces
        F1["UdpFace task"]
        F2["TcpFace task"]
        F3["InProcFace task"]
        F4["EtherFace task"]
    end

    F1 -->|"RawPacket"| CH["mpsc channel"]
    F2 -->|"RawPacket"| CH
    F3 -->|"RawPacket"| CH
    F4 -->|"RawPacket"| CH

    CH --> PR["Pipeline Runner<br/>(drains channel)"]

    PR -->|"spawn"| T1["per-packet task"]
    PR -->|"spawn"| T2["per-packet task"]
    PR -->|"spawn"| T3["per-packet task"]

    T1 --> D["Dispatch<br/>(send to outgoing faces)"]
    T2 --> D
    T3 --> D

    EX["Expiry task<br/>(1 ms tick, timing wheel)"] -.->|"evict expired<br/>PIT entries"| PIT["PIT"]

    style CH fill:#fff3e0,stroke:#FF9800
    style PR fill:#e8f4fd,stroke:#2196F3
    style D fill:#e8f5e9,stroke:#4CAF50
    style EX fill:#fce4ec,stroke:#E91E63

Tracing uses the tracing crate with structured spans per packet. The library never initializes a tracing subscriber – that is the binary’s responsibility, following the principle that libraries should not make policy decisions about logging output.

NDN TLV Encoding

From Bytes on the Wire to Structured Packets

Every NDN packet – Interest, Data, Nack – is just a sequence of bytes when it arrives at a network interface. Before the forwarder can look up a name in the FIB, check the PIT, or consult a strategy, those raw bytes need to become structured data. The question is: how do you parse them efficiently, without copying memory you don’t need to, and without breaking on malformed input?

This is the job of the ndn-tlv crate, the lowest layer in the ndn-rs stack. It implements NDN’s Type-Length-Value wire format: a recursive encoding where every element starts with a type number, followed by a length, followed by that many bytes of value. The value itself can contain more TLV elements, nesting arbitrarily deep. An Interest packet is a TLV element whose value contains the Name (another TLV element, whose value contains name components, each of which is yet another TLV element), plus optional fields like Nonce and Lifetime.

The entire crate is built around one principle: parse without copying. Every slice of decoded data points back into the original byte buffer. When the Content Store serves a cache hit, the bytes that go out on the wire are the same bytes that came in – no serialization round-trip, no intermediate allocations.

📊 Performance: Zero-copy parsing means a Content Store hit can serve cached data by incrementing a reference count and handing out a Bytes slice. No memcpy, no allocation. On a forwarder handling millions of packets per second, this is the difference between keeping up and falling behind.

The VarNumber Trick: Compact Headers for a Wide Range

Before we can parse TLV elements, we need to understand how NDN encodes the Type and Length fields themselves. Both are variable-width unsigned integers called VarNumbers, and the encoding is surprisingly elegant.

The problem: NDN type numbers range from small values like 0x05 (Interest) and 0x06 (Data) up to application-defined types that could be any 64-bit value. Fixed-width fields would waste space – most types and lengths fit in a single byte, but the encoding needs to handle the rare large values too.

NDN’s solution is a compact variable-width encoding. If the value fits in one byte (0 through 252), it’s encoded as-is. For larger values, a marker byte announces the width, followed by the value in big-endian:

#![allow(unused)]
fn main() {
/// Read a VarNumber, returning (value, bytes_consumed).
pub fn read_varu64(buf: &[u8]) -> Result<(u64, usize), TlvError>;

/// Write a VarNumber, returning bytes written.
pub fn write_varu64(buf: &mut [u8], value: u64) -> usize;

/// Compute encoded size without allocating.
pub fn varu64_size(value: u64) -> usize;
}

#![allow(unused)]
fn main() {
let raw: Bytes = receive_from_network();
let mut reader = TlvReader::new(raw);

// Read a complete TLV element: (type, value_bytes)
let (typ, value) = reader.read_tlv()?;

// value is a Bytes slice into the original allocation
// -- zero copy, reference counted

// Peek without advancing
let next_type = reader.peek_type()?;

// Scoped sub-reader for nested TLV parsing
let mut inner = reader.scoped(value.len())?;
}

graph LR
    subgraph "Original Bytes buffer (single allocation, ref-counted)"
        B0["T"] ~~~ B1["L"] ~~~ B2["V₁ V₂ V₃ V₄ V₅ V₆ ..."]
    end

    subgraph "After read_tlv()"
        S1["typ = T"]
        S2["value: Bytes slice → V₁ V₂ V₃ ..."]
    end

    subgraph "After scoped()"
        S3["inner TlvReader → V₁ V₂ ..."]
    end

    B2 -. "zero-copy slice\n(same Arc'd allocation)" .-> S2
    B2 -. "bounded sub-reader\n(no copy)" .-> S3

    style B0 fill:#c44,color:#fff
    style B1 fill:#c90,color:#fff
    style B2 fill:#2d5a8c,color:#fff
    style S2 fill:#2d5a8c,color:#fff
    style S3 fill:#3a7ca5,color:#fff

graph TD
    A["Interest (0x05)"] --> B["Name (0x07)"]
    A --> C["CanBePrefix (0x21)"]
    A --> D["MustBeFresh (0x12)"]
    A --> E["Nonce (0x0A, 4 bytes)"]
    A --> F["InterestLifetime (0x0C)"]
    A --> G["HopLimit (0x22, 1 byte)"]
    A --> H["ForwardingHint (0x1E)"]
    A --> I["ApplicationParameters (0x24)"]

    B --> B1["GenericNameComponent (0x08)\n'ndn'"]
    B --> B2["GenericNameComponent (0x08)\n'test'"]
    B --> B3["GenericNameComponent (0x08)\n'data'"]

    H --> H1["Name (0x07)\nDelegation 1"]

    style A fill:#2d5a8c,color:#fff
    style B fill:#3a7ca5,color:#fff
    style B1 fill:#5ba3c9,color:#fff
    style B2 fill:#5ba3c9,color:#fff
    style B3 fill:#5ba3c9,color:#fff
    style E fill:#3a7ca5,color:#fff
    style F fill:#3a7ca5,color:#fff

graph TD
    D["Data (0x06)"] --> N["Name (0x07)"]
    D --> MI["MetaInfo (0x14)"]
    D --> CO["Content (0x15)"]
    D --> SI["SignatureInfo (0x16)"]
    D --> SV["SignatureValue (0x17)"]

    N --> N1["GenericNameComponent (0x08)\n'ndn'"]
    N --> N2["GenericNameComponent (0x08)\n'test'"]
    N --> N3["GenericNameComponent (0x08)\n'data'"]

    MI --> CT["ContentType (0x18)"]
    MI --> FP["FreshnessPeriod (0x19)"]

    CO --> PL["<application payload>"]

    SI --> ST["SignatureType (0x1B)"]
    SI --> KL["KeyLocator (0x1C)"]

    SV --> SB["<signature bytes>"]

    style D fill:#2d5a8c,color:#fff
    style N fill:#3a7ca5,color:#fff
    style N1 fill:#5ba3c9,color:#fff
    style N2 fill:#5ba3c9,color:#fff
    style N3 fill:#5ba3c9,color:#fff
    style MI fill:#3a7ca5,color:#fff
    style CO fill:#3a7ca5,color:#fff
    style SI fill:#8c5a2d,color:#fff
    style ST fill:#a5793a,color:#fff
    style KL fill:#a5793a,color:#fff
    style SV fill:#8c2d2d,color:#fff
    style SB fill:#a53a3a,color:#fff

Data (0x06)
+-- Name (0x07)
|   +-- NameComponent (0x08) ...
+-- MetaInfo (0x14)
|   +-- ContentType (0x18)
|   +-- FreshnessPeriod (0x19)
+-- Content (0x15)
|   +-- <application payload>
+-- SignatureInfo (0x16)        --|
|   +-- SignatureType (0x1B)      |  signed region
|   +-- KeyLocator (0x1C)         |
+-- SignatureValue (0x17)       --|  covers above

#![allow(unused)]
fn main() {
let mut w = TlvWriter::new();

// Flat TLV element
w.write_tlv(0x08, b"component");

// Nested TLV -- closure writes inner content,
// write_nested wraps it with the correct outer type + length
w.write_nested(0x07, |inner| {
    inner.write_tlv(0x08, b"ndn");
    inner.write_tlv(0x08, b"test");
});

// Raw bytes (pre-encoded content, e.g. signed regions)
w.write_raw(&pre_encoded);

// Snapshot for signing: capture bytes from offset
let signed_region = w.snapshot(start_offset);

let wire_bytes: Bytes = w.finish();
}

#![allow(unused)]
fn main() {
// Used internally by TcpFace and other stream-based faces
let framed = Framed::new(tcp_stream, TlvCodec);

// Decoder yields complete Bytes frames (one NDN packet each)
while let Some(frame) = framed.next().await {
    let pkt: Bytes = frame?;
    // pkt is a complete TLV element: type + length + value
}
}

graph TD
    subgraph "Underlying Allocation"
        BUF["Memory buffer<br/>[TLV type | name TLV | nonce | lifetime | content ... ]"]
    end

    H1["Bytes handle: raw_bytes<br/>(full packet)"] -->|"refcount +1"| BUF
    H2["Bytes handle: name_bytes<br/>slice(4..38)"] -->|"refcount +1"| BUF
    H3["Bytes handle: content_bytes<br/>slice(52..152)"] -->|"refcount +1"| BUF
    H4["Bytes handle: CS entry<br/>clone() of raw_bytes"] -->|"refcount +1"| BUF

    style BUF fill:#e8f4fd,stroke:#2196F3
    style H1 fill:#fff3e0,stroke:#FF9800
    style H2 fill:#fff3e0,stroke:#FF9800
    style H3 fill:#fff3e0,stroke:#FF9800
    style H4 fill:#fff3e0,stroke:#FF9800

graph TD
    A["Face recv()"] -->|"Bytes (wire format)"| B["PacketContext::new()"]
    B -->|"raw_bytes: Bytes"| C["TlvDecodeStage"]
    C -->|"Bytes::slice() for each field"| D{"CS Lookup"}
    D -->|"Cache miss"| E["PitCheck / Strategy / Dispatch"]
    D -->|"Cache hit: Bytes::clone()"| F["Face send()"]
    E -->|"Forward: raw_bytes"| F
    E -->|"CsInsert: Bytes::clone()"| G["Content Store"]
    G -->|"Future hit: Bytes::clone()"| F

    style A fill:#e8f4fd,stroke:#2196F3
    style F fill:#e8f4fd,stroke:#2196F3
    style G fill:#fff3e0,stroke:#FF9800

#![allow(unused)]
fn main() {
pub struct PacketContext {
    /// Wire-format bytes of the original packet.
    pub raw_bytes: Bytes,
    /// Face the packet arrived on.
    pub face_id: FaceId,
    /// Decoded name -- hoisted because every stage needs it.
    pub name: Option<Arc<Name>>,
    /// Decoded packet -- starts as Raw, transitions after TlvDecodeStage.
    pub packet: DecodedPacket,
    // ... other fields
}
}

#![allow(unused)]
fn main() {
// TlvReader holds a Bytes and a cursor position.
// Reading a TLV value returns a Bytes::slice() -- same allocation, no copy.
let value: Bytes = reader.read_value(length)?;  // Bytes::slice(), not memcpy
}

CsInsert: store raw_bytes.clone() keyed by name
CsLookup: if hit, return stored Bytes -- this IS the wire packet, ready to send

graph TD
    NAME["Arc&lt;Name&gt;<br/>/ndn/app/video/frame/1<br/>(single heap allocation)"]

    PC["PacketContext<br/>.name"] -->|"Arc::clone()"| NAME
    PIT["PIT entry<br/>.name"] -->|"Arc::clone()"| NAME
    FIB["FIB lookup result<br/>.prefix"] -->|"Arc::clone()"| NAME
    CS["CS entry<br/>.key"] -->|"Arc::clone()"| NAME
    SC["StrategyContext<br/>.name"] -->|"&Arc (borrow)"| NAME
    MT["MeasurementsTable<br/>.key"] -->|"Arc::clone()"| NAME

    style NAME fill:#c8e6c9,stroke:#4CAF50
    style PC fill:#e8f4fd,stroke:#2196F3
    style PIT fill:#fff3e0,stroke:#FF9800
    style FIB fill:#f3e5f5,stroke:#9C27B0
    style CS fill:#fff3e0,stroke:#FF9800
    style SC fill:#fce4ec,stroke:#E91E63
    style MT fill:#e8f4fd,stroke:#2196F3

#![allow(unused)]
fn main() {
// In PacketContext:
pub name: Option<Arc<Name>>,

// In StrategyContext:
pub name: &'a Arc<Name>,

// In PIT entry, CS key, measurements key: Arc<Name>
}

#![allow(unused)]
fn main() {
// Conceptual: field is decoded on first access, never before
let nonce: &u32 = interest.nonce(); // decodes from raw_bytes on first call, cached thereafter
}

graph LR
    subgraph "Interest (OnceLock lazy decode)"
        direction TB
        N["name: Arc&lt;Name&gt;<br/>--- DECODED ---"]
        NO["nonce: OnceLock&lt;u32&gt;<br/>--- not yet accessed ---"]
        LT["lifetime: OnceLock&lt;Duration&gt;<br/>--- not yet accessed ---"]
        CBP["can_be_prefix: OnceLock&lt;bool&gt;<br/>--- DECODED ---"]
        MBF["must_be_fresh: OnceLock&lt;bool&gt;<br/>--- not yet accessed ---"]
        FH["forwarding_hint: OnceLock&lt;...&gt;<br/>--- not yet accessed ---"]
    end

    RAW["raw_bytes: Bytes<br/>(wire format)"] -->|"decode on<br/>first access"| N
    RAW -->|"decode on<br/>first access"| CBP

    style N fill:#c8e6c9,stroke:#4CAF50
    style CBP fill:#c8e6c9,stroke:#4CAF50
    style NO fill:#eeeeee,stroke:#9E9E9E
    style LT fill:#eeeeee,stroke:#9E9E9E
    style MBF fill:#eeeeee,stroke:#9E9E9E
    style FH fill:#eeeeee,stroke:#9E9E9E
    style RAW fill:#e8f4fd,stroke:#2196F3

sequenceDiagram
    participant App as Consumer App
    participant FaceA as UdpFace (in)
    participant Pipeline as Pipeline Runner
    participant Decode as TlvDecodeStage
    participant CS as CsLookupStage
    participant PIT as PitCheckStage
    participant Strategy as StrategyStage
    participant FIB as FIB
    participant FaceB as UdpFace (out)
    participant Producer as Producer App

    App->>FaceA: Interest (wire bytes)
    FaceA->>Pipeline: InboundPacket { raw, face_id, arrival }
    Pipeline->>Decode: process(ctx)
    Note over Decode: LP-unwrap + TLV parse<br/>Set ctx.name, ctx.packet

    Pipeline->>CS: process(ctx)
    Note over CS: Lookup by name<br/>(miss path)

    Pipeline->>PIT: process(ctx)
    Note over PIT: Create PIT entry<br/>Record in-face, nonce<br/>Check for duplicate nonce

    Pipeline->>Strategy: process(ctx)
    Strategy->>FIB: lpm(name)
    FIB-->>Strategy: nexthops
    Note over Strategy: BestRoute selects<br/>lowest-cost nexthop

    Strategy->>FaceB: send(Interest bytes)
    FaceB->>Producer: Interest

    Producer->>FaceB: Data (wire bytes)
    FaceB->>Pipeline: InboundPacket { raw, face_id, arrival }
    Pipeline->>Decode: process(ctx)
    Note over Decode: Parse Data, set ctx.name

    Pipeline->>PIT: PitMatchStage::process(ctx)
    Note over PIT: Match by name<br/>Collect in-record faces<br/>Remove PIT entry

    Pipeline->>Strategy: Validation
    Note over Strategy: Signature/chain validation<br/>(optional)

    Pipeline->>CS: CsInsertStage::process(ctx)
    Note over CS: Insert Data into cache<br/>Fan-out to in-record faces

    CS->>FaceA: send(Data bytes)
    FaceA->>App: Data

#![allow(unused)]
fn main() {
pub struct InboundPacket {
    pub raw: Bytes,           // Raw wire bytes (zero-copy from socket)
    pub face_id: FaceId,      // Which face received this
    pub arrival: Instant,     // Arrival timestamp
    pub meta: InboundMeta,    // Link-layer metadata (source MAC, etc.)
}
}

#![allow(unused)]
fn main() {
const BATCH_SIZE: usize = 64;

let first = tokio::select! {
    _ = cancel.cancelled() => break,
    pkt = rx.recv() => match pkt { ... },
};
batch.push(first);

while batch.len() < BATCH_SIZE {
    match rx.try_recv() {
        Ok(p) => batch.push(p),
        Err(_) => break,
    }
}
}

%%{init: {"layout": "elk"}}%%
flowchart LR
    subgraph Face Reader Tasks
        F1["UdpFace\nrecv loop"]
        F2["TcpFace\nrecv loop"]
        F3["EtherFace\nrecv loop"]
        Fn["..."]
    end

    CH[/"mpsc channel\n(InboundPacket queue)"/]

    F1 --> CH
    F2 --> CH
    F3 --> CH
    Fn --> CH

    subgraph Pipeline Runner
        PR["run_pipeline\n(batch drain up to 64)"]
    end

    CH --> PR

    subgraph Per-Packet Processing
        PP1["spawn: process_packet"]
        PP2["spawn: process_packet"]
        PP3["spawn: process_packet"]
    end

    PR --> PP1
    PR --> PP2
    PR --> PP3

    subgraph Face Send Tasks
        S1["FaceA.send()"]
        S2["FaceB.send()"]
        S3["FaceC.send()"]
    end

    PP1 --> S1
    PP2 --> S2
    PP3 --> S3

    style CH fill:#c90,color:#000
    style PR fill:#2d5a8c,color:#fff
    style PP1 fill:#5a2d8c,color:#fff
    style PP2 fill:#5a2d8c,color:#fff
    style PP3 fill:#5a2d8c,color:#fff

#![allow(unused)]
fn main() {
if parallel {
    let d = Arc::clone(self);
    tokio::spawn(async move { d.process_packet(pkt).await });
} else {
    self.process_packet(pkt).await;
}
}

#![allow(unused)]
fn main() {
let ctx = match self.decode.process(ctx) {
    Action::Continue(ctx) => ctx,
    Action::Drop(DropReason::FragmentCollect) => return,
    Action::Drop(r) => { debug!(reason=?r, "drop at decode"); return; }
    other => { self.dispatch_action(other); return; }
};
}

#![allow(unused)]
fn main() {
if self.discovery.on_inbound(&ctx.raw_bytes, ctx.face_id, &meta, &*self.discovery_ctx) {
    return; // Consumed by discovery — e.g., /localhop/_discovery/hello
}
}

stateDiagram-v2
    [*] --> Received: Raw bytes arrive on face
    Received --> Decoded: TlvDecodeStage\n(LP unwrap + TLV parse)
    Decoded --> Discovery: Discovery hook check

    Discovery --> Consumed: Discovery packet\n(hello/probe/service)
    Consumed --> [*]

    Discovery --> Checked: Forwarding packet

    state Checked {
        [*] --> CSLookup
        CSLookup --> CacheHit: Name match found
        CSLookup --> PITCheck: Cache miss
        PITCheck --> Duplicate: Same nonce detected
        PITCheck --> Aggregated: Existing PIT out-record
        PITCheck --> StrategyStage: New Interest
        StrategyStage --> Forwarded: Forward to nexthop(s)
        StrategyStage --> Nacked: No route / suppressed
    }

    CacheHit --> Satisfied: Data sent to in-face
    Forwarded --> WaitingForData: PIT entry active
    Duplicate --> Dropped
    Nacked --> Dropped

    WaitingForData --> Cached: Data arrives, CS insert
    Cached --> Satisfied: Fan-out to in-record faces
    WaitingForData --> Expired: PIT timeout

    Satisfied --> [*]
    Dropped --> [*]
    Expired --> [*]
    Aggregated --> [*]

#![allow(unused)]
fn main() {
pub trait Strategy: Send + Sync + 'static {
    /// Canonical name identifying this strategy (e.g., /localhost/nfd/strategy/best-route).
    fn name(&self) -> &Name;

    /// Synchronous fast path. Returns Some(actions) if the decision can be made
    /// without async work, avoiding the Box::pin heap allocation. Returns None
    /// to fall through to the async path.
    fn decide(&self, ctx: &StrategyContext) -> Option<SmallVec<[ForwardingAction; 2]>>;

    /// Called when an Interest arrives and needs a forwarding decision.
    async fn after_receive_interest(&self, ctx: &StrategyContext) -> SmallVec<[ForwardingAction; 2]>;

    /// Called when Data arrives.
    async fn after_receive_data(&self, ctx: &StrategyContext) -> SmallVec<[ForwardingAction; 2]>;

    /// Called when a PIT entry times out. Default: suppress.
    async fn on_interest_timeout(&self, ctx: &StrategyContext) -> ForwardingAction;

    /// Called when a Nack arrives. Default: suppress.
    async fn on_nack(&self, ctx: &StrategyContext, reason: NackReason) -> ForwardingAction;
}
}

#![allow(unused)]
fn main() {
pub struct StrategyContext<'a> {
    /// The name being forwarded.
    pub name: &'a Arc<Name>,
    /// The face the Interest arrived on.
    pub in_face: FaceId,
    /// FIB entry for the longest matching prefix.
    pub fib_entry: Option<&'a FibEntry>,
    /// PIT token for the current Interest.
    pub pit_token: Option<PitToken>,
    /// Read-only access to EWMA measurements per (prefix, face).
    pub measurements: &'a MeasurementsTable,
    /// Cross-layer enrichment data (radio metrics, flow stats, etc.).
    pub extensions: &'a AnyMap,
}
}

#![allow(unused)]
fn main() {
pub enum ForwardingAction {
    /// Forward to these faces immediately.
    Forward(SmallVec<[FaceId; 4]>),
    /// Forward after a delay (enables probe-and-fallback patterns).
    ForwardAfter { faces: SmallVec<[FaceId; 4]>, delay: Duration },
    /// Send a Nack back to the incoming face.
    Nack(NackReason),
    /// Suppress -- do not forward (loop detected or policy decision).
    Suppress,
}
}

#![allow(unused)]
fn main() {
pub struct StrategyTable<S: Send + Sync + 'static + ?Sized>(NameTrie<Arc<S>>);
}

#![allow(unused)]
fn main() {
pub struct MeasurementsTable {
    entries: DashMap<Arc<Name>, MeasurementsEntry>,
}

pub struct MeasurementsEntry {
    /// Per-face EWMA RTT measurements.
    pub rtt_per_face: HashMap<FaceId, EwmaRtt>,
    /// EWMA satisfaction rate (0.0 to 1.0).
    pub satisfaction_rate: f32,
    /// Last update timestamp (ns since Unix epoch).
    pub last_updated: u64,
}
}

#![allow(unused)]
fn main() {
pub trait StrategyFilter: Send + Sync + 'static {
    fn name(&self) -> &str;
    fn filter(&self, actions: SmallVec<[ForwardingAction; 2]>, ctx: &StrategyContext)
        -> SmallVec<[ForwardingAction; 2]>;
}
}

graph TD
    A["Interest arrives"] --> B["Pipeline: Strategy stage"]
    B --> C["StrategyTable.lpm(name)"]
    C --> D{"Strategy found?"}
    D -->|"No"| E["Nack: NoRoute"]
    D -->|"Yes"| F["strategy.decide(ctx)"]
    F --> G{"Sync result?"}
    G -->|"Some(actions)"| H["Use actions directly"]
    G -->|"None"| I["strategy.after_receive_interest(ctx)"]
    I --> H
    H --> J{"ForwardingAction type?"}
    J -->|"Forward(faces)"| K["Set ctx.out_faces, continue pipeline"]
    J -->|"ForwardAfter"| L["Schedule delayed forward"]
    J -->|"Nack(reason)"| M["Send Nack to in_face"]
    J -->|"Suppress"| N["Drop silently"]
    K --> O["Dispatch to out faces"]

    style A fill:#e8f4fd,stroke:#2196F3
    style O fill:#e8f4fd,stroke:#2196F3
    style E fill:#ffebee,stroke:#f44336
    style M fill:#ffebee,stroke:#f44336
    style N fill:#fff3e0,stroke:#FF9800

flowchart LR
    subgraph Tier1["Tier 1: Unix Socket"]
        A1["Application"] -->|"serialize"| K1["Kernel Buffer"]
        K1 -->|"deserialize"| F1["Forwarder"]
    end

    subgraph Tier2["Tier 2: Shared Memory"]
        A2["Application"] -->|"memcpy into slot"| SHM["SPSC Ring Buffer<br/>(POSIX shm)"]
        SHM -->|"read slot"| F2["Forwarder"]
    end

    subgraph Tier3["Tier 3: In-Process"]
        A3["Application"] -->|"Arc pointer"| CH["mpsc Channel"]
        CH -->|"Arc pointer"| F3["Forwarder"]
    end

    style Tier1 fill:#f9f0e8,stroke:#d4a574
    style Tier2 fill:#e8f4e8,stroke:#74d474
    style Tier3 fill:#e8e8f9,stroke:#7474d4

flowchart TB
    subgraph HDR["Header — 7 cache lines · 448 bytes"]
        direction LR
        h0["Magic\nCapacity\nSlot Size"] ~~~ h1["a2e Tail\napp writes →"] ~~~ h2["a2e Head\n← engine reads"] ~~~ h3["e2a Tail\nengine writes →"] ~~~ h4["e2a Head\n← app reads"] ~~~ h5["a2e Parked\nengine flag"] ~~~ h6["e2a Parked\napp flag"]
    end
    subgraph A2E["App → Engine Ring  (capacity × slot_stride)"]
        direction LR
        a0["Slot 0\nlen · payload"] ~~~ a1["Slot 1\nlen · payload"] ~~~ a2["  ···  "] ~~~ aN["Slot N-1\nlen · payload"]
    end
    subgraph E2A["Engine → App Ring  (capacity × slot_stride)"]
        direction LR
        e0["Slot 0\nlen · payload"] ~~~ e1["Slot 1\nlen · payload"] ~~~ e2["  ···  "] ~~~ eN["Slot N-1\nlen · payload"]
    end

    HDR ~~~ A2E
    HDR ~~~ E2A

    style HDR fill:#f0f4ff,stroke:#4a74c9
    style A2E fill:#fff0f0,stroke:#c94a4a
    style E2A fill:#f0fff0,stroke:#4ac94a

#![allow(unused)]
fn main() {
// Create a linked face pair with 64-slot buffers
let (face, handle) = InProcFace::new(FaceId(1), 64);

// Application sends an Interest to the forwarder
handle.send(interest_bytes).await?;

// Forwarder receives it (in the pipeline runner)
let pkt = face.recv().await?;
}

sequenceDiagram
    participant App as Application
    participant RC as ForwarderClient
    participant Sock as Unix Socket
    participant Router as ndn-fwd

    App->>RC: ForwarderClient::connect("/run/nfd/nfd.sock")
    RC->>Sock: Connect to face socket
    Sock->>Router: New IPC connection

    Note over RC: Try SHM data plane
    RC->>Router: faces/create {Uri: "shm://app-<pid>-0"}
    Router-->>RC: {FaceId: 5}
    RC->>RC: SpscHandle::connect("app-<pid>-0")

    Note over RC: SHM ready -- Unix socket becomes control-only

    App->>RC: register_prefix("/myapp")
    RC->>Router: rib/register {Name: "/myapp", FaceId: 5}
    Router-->>RC: OK

    App->>RC: send(interest_bytes)
    RC->>Router: [via SHM ring buffer]
    Router-->>RC: [Data via SHM ring buffer]
    RC-->>App: data_bytes

#![allow(unused)]
fn main() {
// Automatic SHM negotiation (preferred)
let client = ForwarderClient::connect("/run/nfd/nfd.sock").await?;

// Explicit Unix-only mode (skip SHM attempt)
let client = ForwarderClient::connect_unix_only("/run/nfd/nfd.sock").await?;

// Check which transport was negotiated
if client.is_shm() {
    println!("Using shared memory data plane");
}
}

#![allow(unused)]
fn main() {
let payload = Bytes::from(large_buffer);
let producer = ChunkedProducer::new(prefix, payload, NDN_DEFAULT_SEGMENT_SIZE);

// Serve segments in response to Interests
for i in 0..producer.segment_count() {
    let segment_data: &Bytes = producer.segment(i).unwrap();
    // Build Data packet with name: /<prefix>/seg=<i>
}
}

#![allow(unused)]
fn main() {
let mut consumer = ChunkedConsumer::new(prefix, segment_count);

// Segments can arrive in any order
consumer.receive_segment(2, seg2_bytes);
consumer.receive_segment(0, seg0_bytes);
consumer.receive_segment(1, seg1_bytes);

if consumer.is_complete() {
    let original: Bytes = consumer.reassemble().unwrap();
}
}

#![allow(unused)]
fn main() {
let mut registry = ServiceRegistry::new();

// Advertise a service
registry.register("video-encoder", capabilities_bytes);

// Discover a service
if let Some(entry) = registry.lookup("video-encoder") {
    // entry.capabilities contains the service's descriptor
}
}

#![allow(unused)]
fn main() {
let mgmt = MgmtClient::connect("/run/nfd/nfd.sock").await?;

// Announce a service prefix
mgmt.service_announce(&"/myapp/service".parse()?).await?;

// Browse all known services (local and from peers)
let services = mgmt.service_browse(None).await?;

// Withdraw when shutting down
mgmt.service_withdraw(&"/myapp/service".parse()?).await?;
}

#![allow(unused)]
fn main() {
trait DiscoveryProtocol: Send + Sync {
    fn protocol_id(&self) -> ProtocolId;
    fn claimed_prefixes(&self) -> &[Name];
    fn tick_interval(&self) -> Duration;

    fn on_face_up(&self, face_id: FaceId, ctx: &dyn DiscoveryContext);
    fn on_face_down(&self, face_id: FaceId, ctx: &dyn DiscoveryContext);
    fn on_inbound(&self, raw: &Bytes, incoming_face: FaceId, meta: &InboundMeta,
                  ctx: &dyn DiscoveryContext) -> bool;
    fn on_tick(&self, now: Instant, ctx: &dyn DiscoveryContext);
}
}

#![allow(unused)]
fn main() {
// Create hub-discovery protocol, optionally with NDN-FCH fallback.
let autoconfig = AutoConfigDiscovery::with_fch(Some("http://ndn-fch.named-data.net/".into()));
let hub_rx = autoconfig.hub_uri_rx(); // watch::Receiver<Option<String>>

// Add to the composite and start the engine.
// When a hub replies, hub_rx fires with Some("udp://hub.example.com:6363").
}

sequenceDiagram
    participant A as ndn-rs node
    participant H as NDN Hub

    A->>H: Interest /localhop/ndn-autoconf/hub\n(CanBePrefix, MustBeFresh, lifetime=4s)
    H->>A: Data /localhop/ndn-autoconf/hub/<version>\n(content: TLV{0x72, "udp://hub:6363"})
    Note over A: parse nfd::Uri TLV (0x72)\npublish hub URI to watch channel

sequenceDiagram
    participant A as Node A (prober)
    participant B as Node B (target)

    A->>B: Interest /ndn/local/nd/probe/ping/<B>/<nonce>
    B->>A: Data /ndn/local/nd/probe/ping/<B>/<nonce>
    Note over A: miss_count = 0, state = Active
    Note over A,B: (repeat every probe_interval)

    Note over A,B: Link failure
    A--xB: Interest (no reply, timeout)
    A--xB: Interest (no reply, timeout)
    A--xB: Interest (no reply, timeout)
    Note over A: miss_count >= miss_limit\nstate = Stale

#![allow(unused)]
fn main() {
let composite = CompositeDiscovery::new(vec![
    Arc::new(AutoConfigDiscovery::new()),
    Arc::new(NeighborProbeProtocol::new(
        local_name.clone(),
        Duration::from_secs(10), // probe_interval
        3,                        // miss_limit
    )),
    Arc::new(SvsServiceDiscovery::new(...)),
]).unwrap();
}

stateDiagram-v2
    [*] --> Probing : Entry added (static config or AutoConfig)
    Probing --> Established : Probe Data reply received
    Established --> Stale : miss_count reaches limit
    Stale --> Established : Probe Data reply received
    Stale --> Absent : face removed
    Absent --> [*] : Entry removed

#![allow(unused)]
fn main() {
pub struct NeighborEntry {
    pub node_name: Name,
    pub state: NeighborState,
    /// (face_id, source_mac, interface_name) — peer may be multi-homed.
    pub faces: Vec<(FaceId, MacAddr, String)>,
    pub rtt_us: Option<u32>,
    pub pending_nonce: Option<u32>,
}
}

Producer publishes /app/video
→ Browse Data reaches Router
→ FIB: /app/video → face_to_producer
→ Consumer's Interest for /app/video/frame/1 is forwarded automatically

  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
  │  Static      │   │  DVR         │   │  NLSR        │
  │  Protocol    │   │  Protocol    │   │  Protocol    │
  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘
         │ origin=255        │ origin=127        │ origin=128
         └──────────────────┴──────────────────►│
                                                 ▼
                                          ┌──────────────┐
                                          │     RIB      │  per-prefix,
                                          │  (ndn-engine)│  per-face, best-cost
                                          └──────┬───────┘
                                                 │ apply_to_fib()
                                                 ▼
                                          ┌──────────────┐
                                          │     FIB      │  longest-prefix match
                                          └──────────────┘

#![allow(unused)]
fn main() {
use ndn_routing::{StaticProtocol, StaticRoute};
use ndn_transport::FaceId;

let proto = StaticProtocol::new(vec![
    StaticRoute {
        prefix: "/ndn/edu/ucla".parse()?,
        face_id: FaceId(3),
        cost: 10,
    },
]);
// register with EngineBuilder::routing_protocol(proto)
}

#![allow(unused)]
fn main() {
use ndn_routing::DvrProtocol;
use ndn_discovery::DiscoveryProtocol;
use std::sync::Arc;

let dvr = DvrProtocol::new(my_node_name.clone());

let engine = EngineBuilder::new()
    .discovery(Arc::clone(&dvr) as Arc<dyn DiscoveryProtocol>)
    .routing_protocol(Arc::clone(&dvr))
    .build()
    .await?;
}

Interest name:  /ndn/local/dvr/adv
AppParams TLV:
  DVR-UPDATE  (0xD0)
    NODE-NAME (0xD1)  — sender's NDN node name
    ROUTE*    (0xD2)  — zero or more routes
      PREFIX  (0xD3)  — Name TLV
      DVR-COST(0xD4)  — big-endian u32

[routing.nlsr]
enabled      = true
network      = "/ndn"
router       = "/ndn/site/router1"
name_prefixes = ["/ndn/site/data"]

[[routing.nlsr.neighbor]]
name      = "/ndn/site/router2"
face_uri  = "udp4://10.0.0.2:6363"
link_cost = 10.0

#![allow(unused)]
fn main() {
// Start a protocol
engine.routing().enable(Arc::new(my_protocol));

// Stop and flush its routes
engine.routing().disable(origin_value);

// Inspect running protocols
let origins: Vec<u64> = engine.routing().running_origins();
}

# Read current values
/localhost/nfd/routing/dvr-status   (status dataset)

# Apply new values (URL query string in ControlParameters.Uri)
/localhost/nfd/routing/dvr-config   (command)
# e.g. Uri = "update_interval_ms=15000&route_ttl_ms=45000"

State Vector for station-north:
  /weather/station-north  -> seq 42   (that's us)
  /weather/station-east   -> seq 17   (last we heard)
  /weather/station-south  -> seq 31   (last we heard)

sequenceDiagram
    participant A as Station North
    participant B as Station East
    participant C as Station South

    Note over A: State: {N:42, E:15, S:31}
    Note over B: State: {N:40, E:17, S:31}
    Note over C: State: {N:42, E:17, S:33}

    A->>B: Sync Interest {N:42, E:15, S:31}
    A->>C: Sync Interest {N:42, E:15, S:31}

    Note over B: N:42 > 40 → gap (41..42)<br/>E:15 < 17 → no gap<br/>S:31 = 31 → no gap
    B->>B: Fetch /weather/station-north/seq/41
    B->>B: Fetch /weather/station-north/seq/42

    Note over C: N:42 = 42 → no gap<br/>E:15 < 17 → no gap<br/>S:31 < 33 → no gap

    B->>A: Sync Interest {N:42, E:17, S:31}
    Note over A: E:17 > 15 → gap (16..17)
    A->>A: Fetch /weather/station-east/seq/16
    A->>A: Fetch /weather/station-east/seq/17

sequenceDiagram
    participant A as Node A
    participant B as Node B

    Note over A: Local set: {h1, h2, h3}<br/>Build IBF_A
    Note over B: Local set: {h1, h3, h4, h5}<br/>Build IBF_B

    A->>B: Sync Interest with IBF_A

    Note over B: diff = IBF_B - IBF_A<br/>decode → A missing: {h4, h5}<br/>         B missing: {h2}
    B->>A: Sync Data: [h4, h5]

    Note over A: SyncUpdate for h4<br/>SyncUpdate for h5
    A->>A: Fetch data for h4, h5

flowchart LR
    App["Application"]
    SH["SyncHandle"]
    BG["Background Task<br/>(svs_task / psync_task)"]
    Net["Network<br/>(send/recv channels)"]

    App -- "publish(name)" --> SH
    SH -- "publish_tx" --> BG
    BG -- "Sync Interests/Data" --> Net
    Net -- "incoming packets" --> BG
    BG -- "update_tx" --> SH
    SH -- "recv() → SyncUpdate" --> App

#![allow(unused)]
fn main() {
use ndn_sync::{SvsConfig, join_svs_group};

let handle = join_svs_group(
    "/ndn/svs/chat".parse().unwrap(),   // group prefix
    "/ndn/svs/chat/alice".parse().unwrap(), // local name
    send_tx,  // mpsc::Sender<Bytes> for outgoing packets
    recv_rx,  // mpsc::Receiver<Bytes> for incoming packets
    SvsConfig::default(),
);
}

#![allow(unused)]
fn main() {
use ndn_sync::{PSyncConfig, join_psync_group};

let handle = join_psync_group(
    "/ndn/psync/catalog".parse().unwrap(),
    send_tx,
    recv_rx,
    PSyncConfig::default(),
);
}

#![allow(unused)]
fn main() {
// Announce a new publication
handle.publish("/ndn/svs/chat/alice/msg/42".parse().unwrap()).await?;

// Receive notifications about remote publications
while let Some(update) = handle.recv().await {
    println!("New data from {}: {} (seq {}..{})",
        update.publisher, update.name, update.low_seq, update.high_seq);
    // Fetch the actual data using ordinary Interests...
}
}

flowchart LR
    subgraph Producer
        App["Application"] --> Sign["Sign with<br/>Ed25519 / HMAC"]
        Sign --> Data["Signed Data Packet<br/>(signature is part of the wire format)"]
    end

    Data --> Network

    subgraph Network["Network (routers, caches)"]
        R1["Router"] -->|"forward + cache"| R2["Router"]
    end

    Network --> Validate

    subgraph Consumer["Consumer / Forwarder"]
        Validate["Validate signature"] --> Schema["Check trust schema"]
        Schema --> Chain["Walk certificate chain"]
        Chain --> Safe["SafeData"]
    end

    style Safe fill:#2d7a3a,color:#fff

flowchart LR
    Data["Data Packet\n/sensor/node1/temp\nSigned by /sensor/node1/KEY/k1"]
    --> SchemaCheck{"Trust schema\nallows\n(data, key)?"}

    SchemaCheck -->|No| Reject["REJECT\nSchemaMismatch"]
    SchemaCheck -->|Yes| CacheHit{"In\nCertCache?"}

    CacheHit -->|Yes| VerifySig1["Verify signature\nwith cert pubkey"]
    CacheHit -->|No| Fetch["Fetch cert\nvia Interest"]
    Fetch -->|"Not found"| Pending["PENDING\n(retry later)"]
    Fetch -->|Found| VerifySig1

    VerifySig1 -->|Invalid| RejectSig["REJECT\nBadSignature"]
    VerifySig1 -->|Valid| IsAnchor{"Issuer is\ntrust anchor?"}

    IsAnchor -->|Yes| VerifyAnchor["Verify cert\nwith anchor key"]
    IsAnchor -->|No| DepthCheck{"depth <\nmax_chain?"}

    DepthCheck -->|No| RejectDeep["REJECT\nChainTooDeep"]
    DepthCheck -->|Yes| CacheHit2{"Fetch issuer\ncert (cached?)"}
    CacheHit2 -->|Yes| VerifySig1
    CacheHit2 -->|No| FetchIssuer["Fetch issuer\nvia Interest"]
    FetchIssuer --> VerifySig1

    VerifyAnchor -->|Valid| Accept["ACCEPT\nSafeData ✓"]
    VerifyAnchor -->|Invalid| RejectAnchor["REJECT\nBadSignature"]

    style Accept fill:#2d7a3a,color:#fff
    style Reject fill:#8c2d2d,color:#fff
    style RejectSig fill:#8c2d2d,color:#fff
    style RejectDeep fill:#8c2d2d,color:#fff
    style RejectAnchor fill:#8c2d2d,color:#fff
    style Pending fill:#8c6d2d,color:#fff

#![allow(unused)]
fn main() {
pub enum ValidationResult {
    /// Signature valid, chain terminates at a trust anchor.
    Valid(Box<SafeData>),
    /// Signature invalid or trust schema violated.
    Invalid(TrustError),
    /// Missing certificate -- needs fetching.
    Pending,
}
}

#![allow(unused)]
fn main() {
use ndn_security::KeyChain;

// Ephemeral identity (tests, short-lived producers) — in-memory only
let keychain = KeyChain::ephemeral("/sensor/node1")?;
let signer = keychain.signer()?;

// Persistent identity — generates on first run, reloads on subsequent runs
let keychain = KeyChain::open_or_create(
    std::path::Path::new("/var/lib/ndn/sensor-id"),
    "/sensor/node1",
)?;
let signer = keychain.signer()?;
}

#![allow(unused)]
fn main() {
use ndn_security::SignWith;
use ndn_packet::encode::DataBuilder;

let wire = DataBuilder::new("/sensor/node1/temp".parse()?, b"23.5°C")
    .sign_with_sync(&*signer)?;  // returns Bytes directly
}

#![allow(unused)]
fn main() {
pub trait Signer: Send + Sync + 'static {
    fn sig_type(&self) -> SignatureType;
    fn key_name(&self) -> &Name;
    fn cert_name(&self) -> Option<&Name> { None }
    fn public_key(&self) -> Option<Bytes> { None }

    fn sign<'a>(&'a self, region: &'a [u8])
        -> BoxFuture<'a, Result<Bytes, TrustError>>;

    /// CPU-only signers (Ed25519, HMAC) override this to
    /// avoid async overhead.
    fn sign_sync(&self, region: &[u8]) -> Result<Bytes, TrustError>;
}
}

1 BytesMut::with_capacity(total_size)
  ├─ Data TLV header
  ├─ Name TLV           ┐
  ├─ MetaInfo TLV       │  signed region — hashed in-place, no copy
  ├─ Content TLV        │
  ├─ SignatureInfo (5B) ─┘
  └─ SignatureValue (34B = type+len+SHA256)

#![allow(unused)]
fn main() {
pub enum PatternComponent {
    Literal(NameComponent),   // must match exactly
    Capture(Arc<str>),        // binds one component to a named variable
    MultiCapture(Arc<str>),   // binds one or more trailing components
}
}

#![allow(unused)]
fn main() {
SchemaRule {
    data_pattern: NamePattern(vec![
        Literal(comp("sensor")),
        Capture("node"),
        Capture("type"),
    ]),
    key_pattern: NamePattern(vec![
        Literal(comp("sensor")),
        Capture("node"),    // must match the same value as above
        Literal(comp("KEY")),
        Capture("id"),
    ]),
}
}

/sensor/<node>/<type> => /sensor/<node>/KEY/<id>

#![allow(unused)]
fn main() {
use ndn_security::SchemaRule;

let rule = SchemaRule::parse("/sensor/<node>/<type> => /sensor/<node>/KEY/<id>")?;
println!("{}", rule.to_string());
}

[security]
# "disabled" is the default — no validation, matching NFD's forwarder behaviour.
# Switch to "default" or "accept-signed" once trust anchors and keys are ready.
profile = "disabled"
trust_anchor = "/etc/ndn/ta.cert"

# Rules are appended on top of whatever the profile implies.
[[security.rule]]
data = "/sensor/<node>/<type>"
key  = "/sensor/<node>/KEY/<id>"

[[security.rule]]
data = "/admin/<**rest>"
key  = "/admin/KEY/<id>"

# List the current rules
ndn-ctl security schema-list

# Add a new rule
ndn-ctl security schema-rule-add "/dept/<team>/<**rest> => /dept/<team>/KEY/<id>"

# Remove rule at index 0
ndn-ctl security schema-rule-remove 0

# Replace the whole schema (empty string rejects everything)
ndn-ctl security schema-set "/org/<**rest> => /org/KEY/<id>"

#![allow(unused)]
fn main() {
use ndn_ipc::MgmtClient;

let client = MgmtClient::connect("/run/nfd/nfd.sock").await?;

// List rules
let resp = client.security_schema_list().await?;
println!("{}", resp.status_text);

// Add a rule
client.security_schema_rule_add("/sensor/<node>/<type> => /sensor/<node>/KEY/<id>").await?;

// Remove rule at index 0
client.security_schema_rule_remove(0).await?;

// Replace all rules at once
client.security_schema_set(
    "/sensor/<node>/<type> => /sensor/<node>/KEY/<id>\n\
     /admin/<**rest> => /admin/KEY/<id>"
).await?;
}

#![allow(unused)]
fn main() {
SafeData::from_local_trusted(data, uid)
}

flowchart LR
    D["Data\n(unverified)"]

    D -->|"Validator::validate_chain()"| Chain["CertChain\nvalidation"]
    D -->|"SafeData::from_local_trusted()"| Local["Local face\n(SO_PEERCRED)"]

    Chain -->|"valid"| SD["SafeData ✓\npub(crate) fields"]
    Chain -->|"invalid"| Drop["Drop"]
    Local --> SD

    SD -->|"CS insert"| CS["ContentStore\n(only caches verified)"]
    SD -->|"fan-out"| Faces["Send to\nin-record faces"]
    D -.->|"❌ won't compile"| CS

    style SD fill:#2d7a3a,color:#fff
    style Drop fill:#8c2d2d,color:#fff

#![allow(unused)]
fn main() {
pub struct SafeData {
    pub(crate) inner: Data,
    pub(crate) trust_path: TrustPath,
    pub(crate) verified_at: u64,    // nanoseconds since epoch
}

pub enum TrustPath {
    /// Validated via full certificate chain.
    CertChain(Vec<Name>),
    /// Trusted because it arrived on a local face.
    LocalFace { uid: u32 },
}
}

#![allow(unused)]
fn main() {
let identity = NdnIdentity::open_or_create(path, "/sensor/node1").await?;

// These call KeyChain methods via Deref — no indirection required
let signer  = identity.signer()?;
let anchor  = Certificate::decode(anchor_bytes)?;
identity.add_trust_anchor(anchor);
let validator = identity.validator();
}