nerve-ipc-core

Core IPC layer for the NERVE protocol.

What is NERVE?

NERVE is a binary framing protocol for local AI daemon communication. It defines the wire format, message types, codec, and request semantics used between a browser extension, local tools, and an AI daemon.

What does nerve-ipc-core provide?

nerve-ipc-core is the runtime/core layer of NERVE. It provides:

• Authentication — per-install token generation and persistence (~/.anvesha/token)
• Transport servers — Unix Domain Socket (UDS) server for local tool integrations; WebSocket server for browser extension connections
• Transport-agnostic dispatch — a single dispatch_frame() function shared by both transports, performing no I/O
• Request lifecycle and cancellation — per-connection RequestTable tracking active and cancelled requests
• WebSocket handshake authentication — Origin check and per-install token verification at the HTTP upgrade step

nerve-ipc-core has no knowledge of search relevance, AI reasoning, or crawling. That belongs to the layers above.

Relationship to nerve-ipc

nerve-ipc-core depends on nerve-ipc for all protocol types. It does not redefine any wire-format types.

Installation

[dependencies]
nerve-ipc-core = "0.1"

To also build the daemon binary:

[dependencies]
nerve-ipc-core = { version = "0.1", features = ["daemon"] }

Architecture

Browser Extension
      │
      │  NERVE frames over WebSocket (ws://127.0.0.1:9001)
      │  Sec-WebSocket-Protocol: anvesha-v1.<token>
      │  Origin: chrome-extension://<extension_id>
      ▼
┌─────────────────────────────────────────┐
│             nerve-ipc-core              │
│                                         │
│  ws_server          server              │
│  (WebSocket)        (UDS)               │
│       │               │                 │
│       └───────┬───────┘                 │
│               ▼                         │
│          dispatch_frame()               │  ← transport-agnostic
│               │                         │  ← Ping handled inline
│               │                         │  ← Cancel marks request
│               ▼                         │  ← SearchQuery → AI boundary
│         RequestTable                    │  ← per-connection, isolated
│                                         │
└─────────────────────────────────────────┘
      │
      │  (future)
      ▼
  AI Daemon
  ├── query understanding
  ├── search client (HTTPS → hosted API)
  ├── context builder
  └── inference / token streaming

Each accepted connection runs in its own OS thread with an independent RequestTable. A misbehaving client cannot affect other connections.

API Overview

config::Config

Runtime configuration: bind address, WebSocket port, extension ID for origin checking, token path, UDS socket path.

use nerve_ipc_core::config::Config;

let config = Config::default(); // 127.0.0.1:9001, ~/.anvesha/token

auth

Token generation and persistence. The token is 32 bytes of OS randomness stored as 64 hex characters.

use nerve_ipc_core::auth::{generate_token, load_or_create_token};
use std::path::Path;

let token = generate_token(); // fresh 64-char hex token
let token = load_or_create_token(Path::new("/path/to/token"))?; // load or create

dispatch::dispatch_frame

Transport-agnostic frame handler. Returns a DispatchAction that the caller translates into I/O.

use nerve_ipc_core::dispatch::{dispatch_frame, DispatchAction};
use nerve_ipc_core::request_table::RequestTable;
// (frame comes from nerve-ipc's codec::decode)

request_table::RequestTable

Per-connection in-flight request tracking with cancellation support.

use nerve_ipc_core::request_table::RequestTable;
use nerve_protocol::types::RequestId;

let mut table = RequestTable::new();
table.insert(RequestId(1));
table.cancel(RequestId(1));
assert!(table.is_cancelled(RequestId(1)));
table.remove(RequestId(1));

server::run / server::handle_connection

UDS server: binds to a path, accepts connections, spawns threads.

ws_server::run_ws / ws_server::run_ws_on_listener

WebSocket server: binds to 127.0.0.1:<port>, performs auth handshake, dispatches frames.

Protocol / Frame Concepts

One WebSocket binary message = one NERVE frame. The 20-byte NERVE frame header contains magic, version, message type, flags, request ID, and payload length. Payload is arbitrary bytes (typically JSON for message types that carry structured data).

Frame types handled by nerve-ipc-core:

Security

nerve-ipc-core is only accessible to the browser extension and local tools:

Design Goals

• Protocol correctness first
• Deterministic, non-blocking dispatch
• Connection isolation: one bad client does not crash the daemon
• Real IPC in tests — no mocks, no fake transports
• Clean boundary between transport and AI daemon
• Minimal surface area

Non-Goals

• AI reasoning, search ranking, or crawler logic
• Async runtime
• TLS (localhost-only)
• Browser-specific code

Running the Daemon Binary

cargo run --features daemon

On first run:

• Generates a random token and writes it to ~/.anvesha/token (mode 0600)
• Starts the WebSocket server on 127.0.0.1:9001
• Starts the UDS server on /tmp/nerve.sock

On subsequent runs the existing token is reloaded and validated.

Testing

cargo test --all-features

65 tests. No mocks — every test exercises real server code over real sockets.

WebSocket tests (25 tests)

UDS and unit tests (40 tests)

• Ping round-trip (single and multiple)
• Concurrent connections (2 and 6+ simultaneous clients)
• Connection isolation (malformed client does not affect concurrent good client)
• Cancel semantics (unknown, duplicate, cross-connection)
• SearchQuery dispatch to AI boundary
• Interleaved SearchQuery and Ping on same connection
• Cancel of pending SearchQuery
• Request lifecycle and cleanup
• Malformed frames, partial frames, rapid connect/disconnect
• RequestTable unit tests
• read_frame unit tests
• generate_token unit tests

Repository Structure

nerve-core/
├── src/
│   ├── main.rs           # daemon entry point — starts WS + UDS servers
│   ├── lib.rs
│   ├── config.rs         # Config struct; bind address, ports, token path
│   ├── auth.rs           # per-install token generation and persistence
│   ├── server.rs         # UDS accept loop, thread-per-connection, read_frame
│   ├── ws_server.rs      # WebSocket accept loop + auth handshake
│   ├── dispatch.rs       # transport-agnostic dispatch, AI daemon boundary
│   └── request_table.rs  # per-connection request lifecycle and cancellation
│
└── tests/
    ├── helpers/mod.rs    # shared WebSocket test helpers
    ├── ws_basic.rs       # WebSocket: startup, auth, ping
    ├── ws_security.rs    # WebSocket: auth rejection, malformed frames
    ├── ws_connections.rs # WebSocket: concurrent clients, isolation
    ├── ws_protocol.rs    # WebSocket: NERVE semantics
    ├── ping.rs / ping_roundtrip.rs
    ├── cancel.rs / cancel_edge_cases.rs / cancel_marks_requests.rs
    ├── concurrent_connections.rs
    ├── lifecycle.rs
    ├── search_roundtrip.rs / search_streaming.rs / search_cancel_mid_stream.rs
    ├── search_worker_routing.rs
    ├── agent_task_lifecycle.rs
    ├── error_handling.rs
    ├── request_table.rs
    └── socket_read_frame.rs

Dependencies

[dependencies]
nerve-ipc-core = "0.1"

# nerve-ipc provides wire format, codec, and protocol types
# (pulled in transitively via nerve-ipc-core)

Direct dependencies of nerve-ipc-core:

Status

v0.1.0 — WebSocket transport complete.

• ✅ Multiple simultaneous connections (UDS + WebSocket)
• ✅ Connection isolation (per-connection RequestTable)
• ✅ Request lifecycle and cancellation
• ✅ Clean AI daemon boundary (ForwardToAiDaemon)
• ✅ Transport-agnostic dispatch (dispatch_frame shared by UDS and WebSocket)
• ✅ WebSocket server on 127.0.0.1:9001
• ✅ Origin + token authentication at the WebSocket handshake
• ✅ Per-install token at ~/.anvesha/token (mode 0600, getrandom)
• ✅ Oversized payload rejected before allocation
• ⏳ AI daemon integration
• ⏳ Browser extension

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Copyright 2026 Shreyas BK