ndn-rs Wiki

Pre-release. ndn-rs is working toward its first stable tag (v0.1.0). The workspace version reads 0.1.0, but no git tag or GitHub Release has been published yet — this wiki documents main. Pull ghcr.io/quarmire/ndn-fwd:latest or build from source to try the current state. See the draft 0.1.0 release notes for the planned scope.

ndn-rs is a Named Data Networking (NDN) forwarder stack written in Rust. It models NDN as composable data pipelines with trait-based polymorphism, departing from the class hierarchy approach of NFD/ndn-cxx.

What is NDN?

Named Data Networking is a network architecture where communication is driven by named data rather than host addresses. Consumers request data by name (Interest packets), and the network locates and returns the data (Data packets). Every Data packet is cryptographically signed by its producer, enabling in-network caching and security that travels with the data.

Why ndn-rs?

• Library, not daemon – ForwarderEngine embeds in any Rust application
• Zero-copy pipeline – wire-format Bytes flow from recv to send without re-encoding
• Compile-time safety – packet ownership through the pipeline prevents use-after-short-circuit; SafeData typestate enforces verification
• Concurrent data structures – DashMap PIT, RwLock-per-node FIB trie, sharded CS
• Pluggable everything – faces, strategies, CS backends, and pipeline stages via traits
• Embedded to server – no_std TLV and packet crates run on Cortex-M; same code scales to multi-core routers

Navigating This Wiki

Crate Map

Binaries        ndn-fwd  ndn-tools  ndn-bench
                     |          |          |
Engine/App      ndn-engine  ndn-app  ndn-ipc  ndn-config  ndn-discovery
                     |          |        |
Pipeline        ndn-engine  ndn-strategy  ndn-security
                     |             |
Faces           ndn-faces  ndn-faces  ndn-faces  ndn-faces
                     |              |
Foundation      ndn-store  ndn-transport  ndn-packet  ndn-tlv
                                                         |
Embedded                                           ndn-embedded

Research        ndn-sim  ndn-compute  ndn-sync  ndn-research  ndn-strategy-wasm

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

{
  "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/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

This tutorial shows how to run a complete Interest/Data exchange using the ndn-rs library in a single Rust program. No external router is needed – everything runs in-process via InProcFace channel pairs.

How it works

In NDN, communication follows a pull-based model: a consumer sends an Interest packet naming the data it wants, and a producer responds with a matching Data packet. The forwarding engine sits between them, matching Interests to Data via the PIT (Pending Interest Table) and FIB (Forwarding Information Base).

💡 Key insight: No external router is needed for this example. The InProcFace creates an in-process channel pair – one side for the application, one side for the engine. Packets flow through the full forwarding pipeline (PIT, FIB, CS, strategy) but never touch the network. This is the same mechanism used for production in-process applications.

sequenceDiagram
    participant C as Consumer
    participant E as Engine (PIT + FIB)
    participant P as Producer

    C->>E: Interest /ndn/hello
    Note over E: PIT entry created<br/>FIB lookup -> Producer face
    E->>P: Interest /ndn/hello
    P->>E: Data /ndn/hello "hello, NDN!"
    Note over E: PIT entry satisfied<br/>Forward Data to Consumer face
    E->>C: Data /ndn/hello "hello, NDN!"

graph LR
    subgraph "Application Process"
        APP["Application code<br/>(Consumer / Producer)"]
    end

    subgraph "InProcFace Channel Pair"
        direction TB
        TX1["app_handle.send()"] -->|"mpsc"| RX1["engine face.recv()"]
        TX2["engine face.send()"] -->|"mpsc"| RX2["app_handle.recv()"]
    end

    subgraph "ForwarderEngine"
        PIPE["Pipeline<br/>(FIB + PIT + CS + Strategy)"]
    end

    APP -->|"Interest"| TX1
    RX1 -->|"Interest"| PIPE
    PIPE -->|"Data"| TX2
    RX2 -->|"Data"| APP

    style APP fill:#e8f4fd,stroke:#2196F3
    style PIPE fill:#fff3e0,stroke:#FF9800

Dependencies

Add these to your Cargo.toml:

[dependencies]
ndn-app        = { path = "crates/engine/ndn-app" }
ndn-engine     = { path = "crates/engine/ndn-engine" }
ndn-faces = { path = "crates/faces/ndn-faces" }
ndn-packet     = { path = "crates/foundation/ndn-packet", features = ["std"] }
ndn-transport  = { path = "crates/foundation/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

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 sit at the heart of every NDN forwarder. Together they answer three questions: “Do I already have this data?” (CS), “Is someone already looking for it?” (PIT), and “Where should I look?” (FIB).

In ndn-rs, these three structures are not just containers – they are active participants in every packet’s lifecycle, tightly cooperating to move Interests upstream and Data downstream. Understanding how they work individually is important, but understanding how they work together is what makes the forwarding plane click.

The Cooperation

Before diving into each structure’s internals, let’s see how they collaborate. 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 it:

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

An Interest for /a/b/c first asks the CS: “Do you have it?” On a miss, the PIT records who is asking and checks for loops. Then the FIB answers: “Try face 3.” When Data comes back on face 3, the PIT reveals who to deliver it to, the CS caches a copy for next time, and the PIT entry is consumed. Three structures, one fluid motion.

Let’s now examine each structure in depth, keeping in mind how each one’s design decisions ripple through to the others.

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.

💡 Key insight: Storing wire-format bytes instead of decoded structs is a deliberate tradeoff. It means the CS cannot patch fields (e.g., decrementing a hop count) on cache hits. But NDN Data packets are immutable and cryptographically signed – modifying them would invalidate the signature anyway. So wire-format storage is both the fastest and the most correct approach.

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
    Aggregated --> Satisfied: Matching Data arrives
    Satisfied --> [*]: Data sent to all\nin-record faces,\nentry removed
    Pending --> Expired: Interest lifetime\nelapsed, no Data
    Aggregated --> Expired: Interest lifetime\nelapsed, no Data
    Expired --> [*]: Entry cleaned up\nby timing wheel
    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. Instead, a hierarchical timing wheel provides O(1) insertion and expiry notification. When a PIT entry is created, it is registered with the wheel at its expires_at time. The wheel fires a callback when that time passes, and the entry is removed – no periodic sweeps, no wasted CPU.

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.

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/engine/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/engine/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.

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

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/platform/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/platform/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.

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.

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

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/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.

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/engine/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/protocols/ndn-identity" }
ndn-cert     = { path = "crates/protocols/ndn-cert" }
ndn-app      = { path = "crates/engine/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

Design Philosophy

NDN as Composable Data Pipelines

The central insight behind ndn-rs: Rust’s ownership model and trait system map naturally onto NDN’s packet processing as composable data pipelines with trait-based polymorphism. This stands in deliberate contrast to the class hierarchies used by NFD/ndn-cxx (C++) and the convention-based approach of ndnd (Go).

In ndn-rs, 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 accidentally use a packet after handing it off – a guarantee that NFD achieves only through runtime checks and careful documentation.

💡 Key insight: The central design principle is trait composition over class hierarchy. NFD and ndn-cxx model NDN with deep inheritance trees (Strategy, Face, Transport, LinkService). ndn-rs replaces each hierarchy with a flat trait and composes behaviors by wrapping types (e.g., StrategyFilter wraps a Strategy, ShardedCs wraps a ContentStore). This makes the extension points orthogonal – you can combine any strategy with any filter without writing a new subclass.

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.

⚠️ Important: ndn-rs is a library, not a daemon. There is no daemon/client split. Applications embed the forwarding engine directly and communicate via in-process InProcFace channels – no IPC serialization, no Unix socket round-trips. The standalone ndn-fwd binary is just one consumer of this library, not a privileged component. This is a fundamental departure from NFD’s architecture.

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 (SWIM, mDNS, 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
    subgraph "NFD / ndn-cxx: Class Hierarchy"
        direction TB
        SBase["class Strategy (virtual)"]
        SBase --> BR["class BestRouteStrategy"]
        SBase --> MC["class MulticastStrategy"]
        SBase --> ASF["class AsfStrategy"]
        SBase -.->|"Extend via<br/>virtual override"| NEW1["class MyStrategy"]
    end

    subgraph "ndn-rs: Trait Composition"
        direction 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 Filter"] -->|"compose"| BR2
        FTrait -->|"compose"| MC2
    end

    style SBase fill:#ffcdd2,stroke:#F44336
    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.

vs. NFD (C++)

📝 Note: This is not a “ndn-rs is better” page. NFD is the reference implementation with over a decade of production deployment, a large research community, and de facto spec authority. This comparison explains the architectural differences and the tradeoffs each design makes, so you can choose the right tool for your deployment.

This page compares ndn-rs with NFD (NDN Forwarding Daemon) and its companion library ndn-cxx. NFD is the reference implementation of an NDN forwarder, written in C++ and developed by the NDN project team since 2014. Understanding the differences explains why ndn-rs exists and the tradeoffs it makes.

Comparison Table

Where NFD Has the Advantage

NFD is the reference implementation with over a decade of production deployment and research use. Its advantages include:

• Maturity: NFD has been tested in large-scale testbeds (NDN testbed, 30+ nodes worldwide) for years. ndn-rs is newer and less battle-tested.
• Spec conformance: NFD defines the de facto standard for NDN forwarding behaviour. When the spec is ambiguous, NFD’s behaviour is the answer.
• Ecosystem: Tools like ndnping, ndnpeek, ndncatchunks, and the NFD management protocol are widely used and well-documented. ndn-rs implements compatible tools (ndn-tools) and follows the NFD management protocol, but coverage is still growing.
• Community: A larger developer and research community means more strategies, more faces, and more real-world deployment experience.

Migration Considerations

ndn-rs follows the NFD management protocol for router administration, so existing tooling (nfd-status, nlsrc) can interact with an ndn-rs router. The wire format is identical (NDN TLV), so ndn-rs nodes interoperate with NFD nodes on the same network. The main differences are in the internal API: applications using ndn-cxx’s C++ API need to be rewritten in Rust using ndn-app.

vs. ndnd (Go)

📝 Note: ndnd and ndn-rs share a goal of being simpler and more modern than NFD, but they make fundamentally different language-level tradeoffs. This comparison focuses on how Go’s garbage collector and goroutine model differ from Rust’s ownership and async model for the specific workload of NDN packet forwarding.

This page compares ndn-rs with ndnd, an NDN forwarder written in Go. ndnd was created as a simpler, more modern alternative to NFD, leveraging Go’s concurrency primitives and garbage collector. Understanding the differences clarifies what ndn-rs gains from Rust’s ownership model and what tradeoffs that entails.

Comparison Table

Go’s GC vs. Rust’s Ownership for NDN

The choice between garbage collection and ownership-based memory management has particular implications for NDN packet processing:

PIT entry lifetime. A PIT entry must live exactly as long as the Interest is pending – typically milliseconds to seconds. In Go, the GC will eventually reclaim expired entries, but “eventually” may mean the entry lingers in memory for multiple GC cycles after expiry. In ndn-rs, dropping a PIT entry frees its memory immediately, and the hierarchical timing wheel ensures expired entries are drained on a 1 ms tick.

Content Store pressure. The CS is the largest memory consumer in a forwarder. In Go, cached Data packets are opaque to the GC – it must trace through them to determine liveness, adding GC overhead proportional to CS size. In ndn-rs, the CS stores Bytes (reference-counted buffers). Eviction drops the reference count; if no pipeline is currently sending that data, the buffer is freed instantly. The GC never needs to scan cached data because there is no GC.

Name sharing. An NDN name may appear simultaneously in the PIT, FIB, CS, and multiple pipeline contexts. In Go, the GC handles this transparently – all references are equal. In ndn-rs, Arc<Name> makes sharing explicit: cloning an Arc is a reference count increment (one atomic operation), and the name is freed when the last Arc is dropped. The cost is identical to Go’s approach at runtime, but the programmer can see exactly where names are shared.

Zero-copy forwarding. When a Data packet satisfies multiple PIT entries, ndnd typically copies the packet for each downstream face. In ndn-rs, Bytes::clone() creates a new handle to the same underlying buffer (one atomic increment). Multiple faces receive the same data without any copy – a pattern that is natural with reference counting but requires careful manual management in GC’d languages where “sharing” and “copying” look the same.

Where ndnd Has the Advantage

• Simplicity. ndnd’s codebase is smaller and easier for newcomers to read. Go’s lack of generics complexity (traits, lifetimes, associated types) means less to learn.
• Compilation speed. Go compiles significantly faster than Rust, improving developer iteration time.
• Goroutine ergonomics. Go’s goroutines and channels make concurrent code straightforward to write. Rust’s async model requires more explicit annotation (async, .await, Send bounds) and familiarity with pinning.
• Community overlap. ndnd is actively maintained by NDN project contributors, ensuring close alignment with evolving NDN specifications.

vs. NDN-DPDK (C/Go, DPDK)

📝 Note: NDN-DPDK and ndn-rs are not direct competitors — they target fundamentally different deployment tiers. NDN-DPDK is purpose-built for carrier-grade, multi-Tbps line-rate forwarding on dedicated hardware. ndn-rs is designed to be embedded anywhere: in an application, on a microcontroller, or on a commodity server. This comparison explains the tradeoffs so you can choose the right tool for your throughput and deployment requirements.

This page compares ndn-rs with NDN-DPDK, a high-performance NDN forwarder that uses the DPDK (Data Plane Development Kit) kernel-bypass framework. NDN-DPDK is developed at the University of Memphis and is the reference implementation for high-throughput NDN forwarding research. It achieves multi-Tbps forwarding rates by bypassing the OS kernel entirely and dedicating CPU cores and NICs to packet processing.

Comparison Table

Where NDN-DPDK Has the Advantage

NDN-DPDK is the right choice when your requirement is maximum forwarding throughput on dedicated hardware:

• Line-rate forwarding. NDN-DPDK can saturate 100 GbE links (and beyond with multi-port configurations) with real NDN traffic. ndn-rs does not approach these rates on the same hardware because it does not bypass the kernel.
• NUMA-aware memory. DPDK mempools are NUMA-local by construction. On multi-socket servers, packet buffers are always allocated from the same NUMA node as the CPU processing them, eliminating cross-socket memory traffic.
• Polling model. NDN-DPDK’s data plane spins on RX queues without interrupts, trading CPU utilization for minimal and predictable latency at high packet rates.
• Research pedigree. NDN-DPDK is widely used in high-throughput NDN research and has published throughput results that serve as the community’s performance upper bound.

Interoperability

Both NDN-DPDK and ndn-rs use the standard NDN TLV wire format, so they interoperate on the same network. A typical deployment might use NDN-DPDK on core infrastructure routers and ndn-rs on edge nodes, producer applications, and embedded devices — the two layers communicate over standard NDN Faces (UDP multicast, TCP unicast) without any special configuration.

vs. NDNph / NDN-Lite (Embedded C/C++)

📝 Note: NDNph and NDN-Lite are the right answer for resource-constrained targets where ndn-rs cannot run: microcontrollers with under 8 KB RAM and no heap. This comparison is not about which project is better overall — it explains the design tradeoffs so you can pick the right implementation for your hardware target.

This page compares ndn-rs with two embedded NDN implementations: NDNph (a header-only C++ library targeting Arduino, ESP8266, and ESP32) and NDN-Lite (a C library targeting RIOT OS and bare-metal embedded systems). Both projects solve the same problem — running NDN on extremely resource-constrained devices — but from different starting points and with different design philosophies.

Comparison Table

Where NDNph and NDN-Lite Have the Advantage

• Ultra-low RAM targets. On ATmega328 (2 KB SRAM), ATmega2560, or early ESP8266 modules with under 40 KB RAM, NDNph is the only practical option. ndn-rs’s no_std build currently requires more RAM than NDNph for an equivalent feature set.
• Arduino ecosystem integration. NDNph works out of the box with Arduino libraries (Ethernet, WiFi, BLE). Mapping ndn-rs faces to Arduino network APIs requires custom glue code.
• Synchronous simplicity. For a device that does one thing (sense and produce data), NDNph’s synchronous main loop is far simpler to reason about than an async executor.
• NDN-Lite’s security framework. NDN-Lite’s key management and certificate scheduling primitives are more mature and better documented than ndn-rs’s embedded security story.

Code Sharing Benefit in Practice

The shared-codebase advantage becomes concrete when extending the NDN wire format. Adding a new TLV type to ndn-packet automatically makes it available on embedded targets without any additional porting work. A packet encoded by an ndn-embedded node and forwarded by an ndn-fwd server is parsed by the same ndn-packet::Data::from_wire() function — the same code path, the same validation logic, and the same test coverage on both platforms.

vs. NDNts (TypeScript) and mw-nfd (Multi-worker NFD)

📝 Note: NDNts and mw-nfd serve different audiences than ndn-rs. NDNts targets browser and Node.js applications where JavaScript is the only option. mw-nfd targets existing NFD deployments that need higher throughput without a full rewrite. This comparison explains each project’s niche and where ndn-rs overlaps or differs.

This page compares ndn-rs with two further implementations: NDNts, a full NDN stack written in TypeScript that runs in browsers and Node.js, and mw-nfd, a modified NFD that adds a multi-threaded worker model to the reference C++ forwarder. They occupy distinct niches — browser applications and high-throughput C++ deployments, respectively — but both are common points of comparison when evaluating NDN implementations.

NDNts (TypeScript / Browser)

mw-nfd (Multi-worker NFD, C++)

Where NDNts and mw-nfd Have the Advantage

NDNts:

• Browser-native. No other NDN implementation runs in a web browser. If your application is a web app, NDNts is the answer.
• npm ecosystem. One npm install and it works with any JavaScript build pipeline. No Rust toolchain required.
• Web Crypto integration. Hardware-backed key storage via browser credentials is accessible only to browser-native code.
• Community. NDNts is actively maintained and has the widest adoption among JavaScript NDN developers.

mw-nfd:

• Drop-in for NFD. Existing NFD deployments gain multi-core throughput with minimal configuration changes.
• Spec authority. mw-nfd inherits NFD’s status as the reference implementation, so its forwarding behaviour is de facto correct by definition.
• Production history. mw-nfd runs in real testbed deployments; ndn-rs’s multi-core forwarding is newer and less battle-tested at scale.

Complementary Deployment Pattern

A common pattern that uses all three projects together: NDNts runs in a browser application (consumer and producer), connecting over WebSocket to an ndn-fwd instance (ndn-rs) acting as an edge forwarder, which peers upstream with mw-nfd or NDN-DPDK nodes on the testbed backbone. Each implementation operates in the tier where it has the clearest advantage.

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
}
}

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() {
let action = self.cs_insert.process(ctx).await;
self.dispatch_action(action);
}

#![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);
}
}

sequenceDiagram
    participant A as Node A
    participant B as Node B

    Note over A,B: Initial Discovery
    A->>B: Hello Interest\n/ndn/local/nd/hello/<nonce1>
    B->>A: Hello Data\n(node name, prefixes, neighbor diffs)
    Note over A: Measure RTT, update EWMA\nState: Probing → Established

    Note over A,B: Periodic Probing
    loop Every tick interval
        A->>B: Probe Interest\n/ndn/local/nd/probe/direct/<B>/<nonce>
        B->>A: Probe Data (ACK)
        Note over A: Update last_seen, RTT
    end

    Note over A,B: Liveness Timeout
    A->>B: Probe Interest (no reply)
    Note over A: timeout exceeded\nState: Established → Stale
    A->>B: Unicast Hello (retry)
    B->>A: Hello Data
    Note over A: State: Stale → Established

    Note over A,B: Peer Failure
    A--xB: Probe Interest (no reply)
    Note over A: miss_count >= threshold\nState: Stale → Absent
    Note over A: Remove faces, withdraw FIB entries\nGossip removal to other peers

pub type UdpNeighborDiscovery  = HelloProtocol<UdpMedium>;
pub type EtherNeighborDiscovery = HelloProtocol<EtherMedium>;

sequenceDiagram
    participant A as Node A
    participant C as Node C (intermediary)
    participant B as Node B (suspect)

    Note over A,B: Direct probe fails
    A->>B: Probe /ndn/local/nd/probe/direct/<B>/<nonce>
    Note over A: Timeout — no reply from B

    Note over A,C: SWIM indirect probe
    A->>C: Indirect Probe\n/ndn/local/nd/probe/via/<C>/<B>/<nonce>
    C->>B: Probe /ndn/local/nd/probe/direct/<B>/<nonce2>

    alt B is alive
        B->>C: Probe Data (ACK)
        C->>A: Indirect Probe Data (alive)
        Note over A: B is reachable via C\nKeep Established state
    else B is truly dead
        Note over C: Timeout — no reply from B
        C->>A: Indirect Probe Nack (unreachable)
        Note over A: Confirmed failure\nState → Stale / Absent
    end

stateDiagram-v2
    [*] --> Probing : First hello sent
    Probing --> Established : Hello Data reply received\n(RTT measured, FIB populated)
    Established --> Stale : Liveness timeout exceeded\n(unicast hello + gossip sent)
    Stale --> Established : Hello Data reply received
    Stale --> Absent : miss_count ≥ liveness_miss_count\n(faces removed, FIB withdrawn)
    Absent --> [*] : Entry removed

#![allow(unused)]
fn main() {
pub struct NeighborEntry {
    pub node_name: Name,
    pub state: NeighborState,
    /// Per-link face bindings: (face_id, source_mac, interface_name)
    /// A peer may be reachable over multiple interfaces simultaneously.
    pub faces: Vec<(FaceId, MacAddr, String)>,
    pub rtt_us: Option<u32>,    // EWMA RTT
    pub pending_nonce: Option<u32>,
}
}

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

    Note over P,R: Service Announcement
    P->>P: publish ServiceRecord\nprefix=/app/video, owner=face3

    Note over R,P: Browse Phase
    R->>P: Browse Interest\n/ndn/local/sd/services/ (CanBePrefix)
    P->>R: Browse Data\n(ServiceRecord: /app/video)
    Note over R: Auto-populate FIB:\n/app/video → face to P

    Note over C,R: Consumer discovers via Router
    C->>R: Browse Interest\n/ndn/local/sd/services/ (CanBePrefix)
    R->>C: Browse Data\n(relayed ServiceRecord: /app/video)
    Note over C: Auto-populate FIB:\n/app/video → face to R

    Note over C,P: Normal forwarding now works
    C->>R: Interest /app/video/frame/1
    R->>P: Interest /app/video/frame/1
    P->>R: Data /app/video/frame/1
    R->>C: Data /app/video/frame/1

PeerList ::= (PEER-ENTRY TLV)*
PEER-ENTRY  ::= 0xE0 length Name

#![allow(unused)]
fn main() {
struct AutoFibEntry {
    prefix: Name,
    face_id: FaceId,
    expires_at: Instant,
    node_name: Name,
}
}

# Read current values
/localhost/nfd/discovery/status    (status dataset)

# Apply new values (URL query string in ControlParameters.Uri)
/localhost/nfd/discovery/config    (command)
# e.g. Uri = "hello_interval_base_ms=3000&gossip_fanout=3"

  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
  │  Static      │   │  DVR         │   │  (future)    │
  │  Protocol    │   │  Protocol    │   │  NLSR / …    │
  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘
         │ 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

#![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)
}

#![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();
}

{
  "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1"],
  "id": "did:ndn:com:acme:alice",
  "verificationMethod": [{
    "id": "did:ndn:com:acme:alice#key-0",
    "type": "JsonWebKey2020",
    "controller": "did:ndn:com:acme:alice",
    "publicKeyJwk": {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
    }
  }],
  "authentication": ["did:ndn:com:acme:alice#key-0"],
  "assertionMethod": ["did:ndn:com:acme:alice#key-0"]
}

did:ndn:<base64url(Name TLV)>

NDN name:   /com/acme/alice
Name TLV:   07 11 08 03 "com" 08 04 "acme" 08 05 "alice"
did:ndn:    did:ndn:<base64url of the 20-byte TLV above>

NDN name (zone root, BLAKE3_DIGEST component):   /<32 bytes>
Name TLV:   07 22 03 20 <32 bytes>
did:ndn:    did:ndn:<base64url of the 36-byte TLV above>

#![allow(unused)]
fn main() {
use ndn_security::did::{name_to_did, did_to_name};

let name: Name = "/com/acme/alice".parse()?;

// Name → DID (always binary encoding)
let did = name_to_did(&name);
// result is "did:ndn:<base64url(Name TLV)>", no colons in the method-specific-id
assert!(did.starts_with("did:ndn:"));
assert!(!did["did:ndn:".len()..].contains(':'));

// DID → Name (round-trips correctly)
let recovered = did_to_name(&did)?;
assert_eq!(recovered, name);

// Zone root name (BLAKE3_DIGEST component) — same encoding, no special case
let zone_name: Name = /* from ZoneKey::zone_root_name() */;
let zone_did = name_to_did(&zone_name);
// still "did:ndn:<base64url>", no v1: prefix
}

#![allow(unused)]
fn main() {
use ndn_security::did::{UniversalResolver, cert_to_did_document};
use ndn_security::Certificate;

// High-level: resolve a did:ndn directly
let resolver = UniversalResolver::new();
let doc: DidDocument = resolver.resolve("did:ndn:com:acme:alice").await?;

// Low-level: convert an already-fetched certificate
let cert: Certificate = /* fetched from network or cache */;
let doc = cert_to_did_document(&cert);
}

Alice controls:
  did:ndn:com:acme:alice     (resolves via NDN Interest)
  did:web:alice.acme.com     (resolves via HTTPS + well-known URL)

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

#![allow(unused)]
fn main() {
use ndn_security::did::UniversalResolver;

let resolver = UniversalResolver::new();

// Resolves instantly — the key is encoded in the DID itself
let doc = resolver.resolve(
    "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
).await?;

// Extract the verification method (the public key)
let vm = &doc.verification_method[0];
println!("key type: {}", vm.type_);
}

#![allow(unused)]
fn main() {
use ndn_security::did::{cert_to_did_document, name_to_did};
use ndn_identity::NdnIdentity;

let identity = NdnIdentity::open_or_create(path, "/com/acme/alice").await?;

// NdnIdentity implements Deref<Target = KeyChain>, so manager_arc() is available directly
let mgr = identity.manager_arc();
let cert: Certificate = mgr.get_certificate()?;
let doc = cert_to_did_document(&cert);

// The DID in the document matches what name_to_did() would produce
assert_eq!(doc.id, name_to_did(cert.identity_name()));
}

#![allow(unused)]
fn main() {
use ndn_security::did::UniversalResolver;
use ndn_security::Validator;

let resolver = UniversalResolver::new();
let doc = resolver.resolve("did:ndn:com:acme:sensor-ca").await?;

// Build a Validator that trusts this DID's key as a trust anchor
let validator = Validator::builder()
    .trust_anchor_from_did_document(&doc)?
    .hierarchical_schema()
    .build();
}

Applicant                                    CA
    |                                        |
    |--- Interest /ca-prefix/INFO ---------->|
    |<-- Data: CA name, challenges, policy --|
    |                                        |
    |--- Interest /ca-prefix/NEW  ---------->|
    |    (public key, desired namespace)     |
    |<-- Data: request-id, challenge type ---|
    |                                        |
    |--- Interest /ca-prefix/CHALLENGE ----->|
    |    (request-id, challenge response)    |
    |<-- Data: status (pending/challenge) ---|
    |                                        |
    |   ... (may repeat for multi-round) ... |
    |                                        |
    |<-- Data: status=success, certificate --|

#![allow(unused)]
fn main() {
use ndn_cert::{TokenStore, TokenChallenge};

// At CA setup time, pre-generate tokens for 100 devices
let mut store = TokenStore::new();
store.add_many((0..100).map(|_| random_token()));

// Wire the challenge handler into the CA
let challenge = TokenChallenge::new(store);
}

#![allow(unused)]
fn main() {
// On the device, at first boot:
let config = DeviceConfig {
    namespace: "/fleet/vehicle/vin-1234".to_string(),
    factory_credential: FactoryCredential::Token("a3f9...".to_string()),
    ca_prefix: "/fleet/ca".parse()?,
    // ...
};
let identity = NdnIdentity::provision(config).await?;
}

#![allow(unused)]
fn main() {
use ndn_cert::PossessionChallenge;
use ndn_security::Certificate;

// The CA trusts anything signed by the fleet root
let fleet_root: Certificate = load_fleet_root_cert()?;
let challenge = PossessionChallenge::new(vec![fleet_root]);
}

CA name:        /com/acme/fleet
Allowed:        /com/acme/fleet/vehicle/vin-1234
                /com/acme/fleet/drone/unit-7
Not allowed:    /com/acme/hr/employee/alice   (different subtree)
                /com/rival/vehicle/vin-9999   (different org)

graph TD
    Root["Root CA\n/com/acme\n(offline, air-gapped)"]
    Fleet["Fleet sub-CA\n/com/acme/fleet\n(online, NDNCERT)"]
    HR["HR sub-CA\n/com/acme/hr\n(online, NDNCERT)"]
    V1["Vehicle cert\n/com/acme/fleet/vehicle/vin-1234"]
    V2["Vehicle cert\n/com/acme/fleet/drone/unit-7"]
    E1["Employee cert\n/com/acme/hr/alice"]

    Root -->|"issues cert for"| Fleet
    Root -->|"issues cert for"| HR
    Fleet -->|"issues cert for"| V1
    Fleet -->|"issues cert for"| V2
    HR -->|"issues cert for"| E1

#![allow(unused)]
fn main() {
// Renew when less than 20% of the cert lifetime remains
// (i.e., renew every ~19h if the cert is 24h)
DeviceConfig {
    renewal: RenewalPolicy::WhenPercentRemaining(20),
    // ...
}
}

graph TB
    subgraph "Traditional NDN over IP"
        A1[NDN TLV Packet] --> A2[UDP Header - 8 B]
        A2 --> A3[IP Header - 20 B]
        A3 --> A4[Ethernet Frame]
    end

    subgraph "ndn-rs Link-Layer Face"
        B1[NDN TLV Packet] --> B2["Ethernet Frame<br/>Ethertype 0x8624"]
    end

    style A2 fill:#f96,stroke:#333
    style A3 fill:#f96,stroke:#333
    style B2 fill:#6b6,stroke:#333

#![allow(unused)]
fn main() {
pub struct NamedEtherFace {
    id: FaceId,
    node_name: Name,      // NDN identity -- stable across channels
    peer_mac: MacAddr,     // resolved once at hello exchange
    iface: String,
    ifindex: i32,
    radio: RadioFaceMetadata,
    socket: AsyncFd<OwnedFd>,
    ring: PacketRing,     // TPACKET_V2 mmap'd RX + TX rings
}
}

#![allow(unused)]
fn main() {
pub struct WfbFace {
    id: FaceId,
    direction: WfbDirection,
}

pub enum WfbDirection {
    Rx,  // receive-only (e.g., downlink from air unit)
    Tx,  // transmit-only (e.g., uplink from ground station)
}
}

#![allow(unused)]
fn main() {
// In the dispatch stage, before sending Data:
let send_face_id = self.face_pairs
    .get_tx_for_rx(ctx.pit_token.in_face)
    .unwrap_or(ctx.pit_token.in_face);  // normal faces unaffected
}

#![allow(unused)]
fn main() {
pub type SerialFace = StreamFace<
    ReadHalf<SerialStream>,
    WriteHalf<SerialStream>,
    CobsCodec,
>;
}

#![allow(unused)]
fn main() {
let face = serial_face_open(FaceId(1), "/dev/ttyUSB0", 115200)?;
}

[ COBS-encoded payload ] [ 0x00 ]

graph LR
    subgraph "Multi-Radio NDN Node"
        Engine[NDN Engine<br/>FIB + PIT + CS]
        Strategy[MultiRadioStrategy]
        RT[RadioTable<br/>DashMap of FaceId to LinkMetrics]
        CM[ChannelManager<br/>nl80211 Netlink]

        Engine --> Strategy
        Strategy --> RT
        CM --> RT
    end

    subgraph "Radio 0 -- 2.4 GHz (Access)"
        wlan0[wlan0 ch 6]
        EF0a[NamedEtherFace peer=A]
        EF0b[NamedEtherFace peer=B]
    end

    subgraph "Radio 1 -- 5 GHz (Backhaul)"
        wlan1[wlan1 ch 36]
        EF1[NamedEtherFace peer=relay2]
    end

    Engine --> EF0a
    Engine --> EF0b
    Engine --> EF1
    EF0a --- wlan0
    EF0b --- wlan0
    EF1 --- wlan1

#![allow(unused)]
fn main() {
pub struct RadioFaceMetadata {
    pub radio_id: u8,   // physical radio index (0-based)
    pub channel: u8,    // current 802.11 channel number
    pub band: u8,       // 2 = 2.4 GHz, 5 = 5 GHz, 6 = 6 GHz
}

pub struct LinkMetrics {
    pub rssi_dbm: i8,            // received signal strength
    pub retransmit_rate: f32,    // MAC-layer retransmission rate (0.0-1.0)
    pub last_updated: u64,       // ns since Unix epoch
}
}

%%{init: {"layout": "elk"}}%%
graph TD
    subgraph "Face Type Hierarchy"
        Face["trait Face<br/>recv() + send()"]

        Face --> IP["IP-based"]
        Face --> L2["Link-layer"]
        Face --> Local["In-process"]

        IP --> UDP[UdpFace]
        IP --> TCP[TcpFace]
        IP --> MUDP[MulticastUdpFace]

        L2 --> Ether["NamedEtherFace<br/>AF_PACKET / PF_NDRV / Npcap"]
        L2 --> MEther["MulticastEtherFace<br/>01:00:5e:00:17:aa"]
        L2 --> Wfb["WfbFace<br/>monitor mode injection"]
        L2 --> BT["BluetoothFace<br/>RFCOMM / L2CAP CoC"]
        L2 --> Serial["SerialFace<br/>COBS framing"]

        Local --> App[InProcFace]
        Local --> Compute[ComputeFace]
    end

    style L2 fill:#6b6,stroke:#333
    style Ether fill:#6b6,stroke:#333
    style MEther fill:#6b6,stroke:#333
    style Wfb fill:#6b6,stroke:#333
    style BT fill:#6b6,stroke:#333
    style Serial fill:#6b6,stroke:#333