NERVE

A binary, local-only, low-latency IPC protocol for browser-internal intelligence.

Overview

NERVE is a specialized protocol designed to connect browser components (search, local LLMs, system services) as if they were part of a single nervous system. It prioritizes deterministic latency, minimal allocations, streaming-first semantics, and immediate cancellation over a Unix Domain Socket.

Status: v0.2.0 (active development — v0.x allows breaking changes between releases)

Key Characteristics

• Binary Protocol: Fixed-size frame headers with little-endian encoding
• Local IPC Only: Designed for Unix Domain Sockets (UDS), single-machine communication
• Low Latency: Fixed-size frame headers, single-pass parsing, minimal allocation path
• Streaming First: Supports multi-frame responses with ordered delivery guarantees
• Immediate Cancellation: Best-effort request termination
• Predictable: Single-pass parsing, fixed limits, clear error semantics

What NERVE is NOT

• A general-purpose RPC protocol
• Suitable for remote/network transport
• Backward compatible (v0.x allows breaking changes)
• Including authentication or encryption (assumes local trust boundary)

Installation

Add to your Cargo.toml:

[dependencies]
nerve-ipc = "0.2"

Or via cargo add:

cargo add nerve-ipc

Project Structure

nerve/
├── Cargo.toml              # Rust project manifest
├── src/
│   ├── lib.rs             # Library root
│   ├── codec.rs           # Frame encoding/decoding
│   ├── constants.rs       # Protocol constants
│   ├── error.rs           # Error types
│   ├── frame.rs           # Frame format & layout
│   ├── io.rs              # I/O operations
│   ├── message.rs         # Message type definitions
│   ├── request.rs         # Request lifecycle
│   └── types.rs           # Shared type definitions
├── examples/
│   └── ping.rs            # Encode/decode roundtrip example
├── benches/
│   └── ping.rs            # Performance benchmarks
├── tests/
│   ├── frame_roundtrip.rs # Frame encoding tests
│   └── malformed.rs       # Malformed input handling
└── docs/
    └── protocol.md        # Full protocol specification

Protocol Basics

Frame Format

Every message is wrapped in a binary frame:

Header (20 bytes fixed):
  magic (u32)        → 0x4E455256 ("NERV")
  version (u16)      → 1
  type (u8)          → Message type
  flags (u8)         → Bitflags (STREAM, FINAL)
  request_id (u64)   → Unique per request
  payload_len (u32)  → Payload size in bytes

Payload (0 to 1 MiB):
  implementation-defined binary data

Message Types

Limits

Frames exceeding limits trigger immediate connection termination.

Quick Start

use nerve_ipc::{
    codec::{encode, decode},
    types::{FrameFlags, MessageType, RequestId},
};

let encoded = encode(
    MessageType::Ping,
    FrameFlags::empty(),
    RequestId(1),
    &[],
)?;

let frame = decode(&encoded)?;
println!("msg_type=0x{:02X}", frame.header.msg_type);

Run the included example:

cargo run --example ping

Benchmarks

NERVE protocol framing is designed for low-latency local IPC.

Ping Roundtrip (Encode + Decode)

Environment:

• Rust --release
• Single-threaded
• In-memory buffer
• No I/O

Benchmark:

nerve_ping_roundtrip
time: [19.419 ns 19.511 ns 19.603 ns]

This measures the full frame encode + zero-copy decode path.

Prerequisites

• Rust 1.85+ (required for edition 2024)
• Unix-like OS (Linux, macOS) for UDS support

Build

cargo build

Run Tests

cargo test

Run Benchmarks

cargo bench

Protocol Compliance

An implementation is NERVE v0.2.0 compliant if it:

• Implements the frame format exactly
• Enforces all hard limits
• Supports all message types
• Handles malformed input safely (close connection)
• Does not deadlock on cancellation

Error Handling

Protocol violations result in local error handling; no error frames are transmitted in v0.1.0.

Error Classes:

• ProtocolViolation: Invalid frame or state transition
• UnsupportedVersion: Version mismatch
• MalformedFrame: Unparseable header or payload
• PayloadTooLarge: Exceeds MAX_PAYLOAD_SIZE
• InternalError: Implementation-specific failure

Response to Errors:

• Malformed frames → immediate connection close
• Unsupported version → immediate connection close
• Protocol violations → log + close connection

Documentation

Full protocol specification: docs/protocol.md File-level overview: docs/files.md

Security Model

• Trust Boundary: Local user on the same machine
• Transport: Unix Domain Sockets (implicit local-only)
• Authentication: None in v0.1.0 (socket file permissions enforce access)
• Encryption: None in v0.1.0 (can be added at application layer)

Contributing

Issues and pull requests are welcome via the repository.

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.