plugin-ipc

Cross-language IPC library for Netdata plugins and helper services.

This repository contains the C library, Rust crate, and Go package for the same wire contracts and typed APIs. The goal is simple:

• one specification
• one interoperable protocol stack
• one typed service model
• one local snapshot/cache helper layer
• three implementations: C, Rust, Go

This README is a summary of the current verified state of the repository. The authoritative specifications live under docs/.

Non-Negotiable Contract

• These rules apply to every implementation language and every service unless a future spec explicitly changes the global contract.
• C, Rust, and Go must implement the same wire contract and typed behavior.
• NetIPC does not do backward-compatible, forward-compatible, or best-effort decoding across method, layout, status, echoed-key, or generation drift.
• Netdata plugins and NetIPC providers/clients must match the documented contract exactly. Any mismatch is rejected.
• Mixed-generation stitched lookup responses are not supported.
• Level 2 lookup callers pass typed semantic keys; they do not split requests around transport payload budgets and do not stitch responses manually.
• Lookup PAYLOAD_EXCEEDED is an internal Level 2 retry signal. The client retries only the affected suffix and returns one logical response.
• Lookup OVERSIZED_ITEM is a final per-item outcome. One oversized valid item must not invalidate the rest of the logical lookup batch.
• Payload budgets and logical lookup ceilings are initialization policy. Zero-valued fields use documented defaults; consumers can override them for small IoT systems or large-memory HPC deployments.
• Named defaults are defaults, not protocol hard limits. Explicit client/server initialization config is the deployment authority.

Service Model

The public contract is service-oriented, not plugin-oriented:

• clients connect to a specific service kind
• clients do not care which plugin/process serves that service
• one service endpoint serves exactly one request kind
• sessions are long-lived and reused for many requests

Examples of service kinds:

• cgroups-snapshot
• cgroups-lookup
• apps-lookup
• ip-to-asn
• pid-traffic

Operational implications:

• startup order is not guaranteed
• a client may start before its provider exists
• services may disappear and reappear during runtime
• enrichments are optional by design
• clients refresh / reconnect from their normal loop and must tolerate service absence

What This Repository Implements

• Level 1 transport
  • connection lifecycle
  • handshake and profile negotiation
  • framing, chunking, batching, pipelining
  • baseline and shared-memory transports
• Codec
  • wire encode/decode
  • typed views
  • response builders
  • validation rules
• Level 2 typed API
  • typed client calls
  • managed typed servers
  • retry / reconnect behavior
  • internal reusable buffers
• Level 3 snapshot API
  • refresh
  • local cache construction
  • fast hash lookup
  • cache preservation on failure

The design is layered:

• Level 1 and Codec are parallel building blocks
• Level 2 composes Level 1 + Codec
• Level 3 builds on Level 2

See:

• docs/README.md
• docs/level2-typed-api.md
• docs/level3-snapshot-api.md
• docs/getting-started.md
• docs/netipc-integrator-skill.md

Platforms And Transports

Platform	Baseline transport	Negotiated fast path	Languages
POSIX / Linux	Unix domain SOCK_SEQPACKET	POSIX shared memory	C, Rust, Go
Windows	Named Pipes	Windows shared memory	C, Rust, Go

Important facts:

• the same wire contracts are implemented in all three languages
• cross-language interoperability is mandatory
• Go stays pure Go, without cgo
• Level 2 and Level 3 are transport-agnostic from the caller perspective

API Levels

Level 1: Transport

Level 1 works with framed byte messages.

It owns:

• send / receive
• message IDs
• batch directories
• chunk continuation
• profile negotiation
• transport-specific session details

Relevant specs:

• docs/level1-transport.md
• docs/level1-wire-envelope.md
• docs/level1-posix-uds.md
• docs/level1-posix-shm.md
• docs/level1-windows-np.md
• docs/level1-windows-shm.md

Codec

Codec is pure wire-format logic.

It owns:

• encode / decode
• typed views over payload bytes
• response builders
• validation of field layout and bounds

It does not own:

• sockets
• pipes
• shared memory mappings
• retries
• cache policy

Relevant specs:

• docs/codec.md
• docs/codec-cgroups-snapshot.md
• docs/codec-cgroups-lookup.md
• docs/codec-apps-lookup.md

Level 2: Typed API

Level 2 is the public convenience layer.

The public contract is:

• clients issue typed calls
• servers export one typed service kind
• one server endpoint serves one request kind only
• callers do not manage transport scratch buffers
• callers do not manipulate raw payload bytes

Relevant specs:

• docs/level2-typed-api.md
• docs/getting-started.md

Level 3: Snapshot / Cache

Level 3 provides:

• typed snapshot refresh
• local materialization
• O(1)-style hash lookup on the hot path
• cache retention across refresh failures

Relevant spec:

• docs/level3-snapshot-api.md

Interoperability

This repository is intentionally built around interoperability, not single-language wrappers.

What is covered:

• C client -> C / Rust / Go server
• Rust client -> C / Rust / Go server
• Go client -> C / Rust / Go server
• baseline transport matrices on POSIX and Windows
• shared-memory matrices on POSIX and Windows
• typed Level 2 services
• snapshot refresh and local lookup flows
• benchmark matrices across all directed pairs

The interop results are validated by the test suite and by the checked-in benchmark reports:

• benchmarks-posix.md
• benchmarks-windows.md

Performance Snapshot

The repository includes checked-in benchmark reports with complete, fail-closed matrices:

• POSIX report: benchmarks-posix.md
  • generated 2026-05-25
  • machine: local benchmark host
  • complete matrix rows: 297
• Windows report: benchmarks-windows.md
  • generated 2026-05-25
  • machine: local Windows benchmark host
  • complete matrix rows: 201

Headline numbers from the current checked-in reports:

• POSIX baseline UDS ping-pong

  • 142.1k to 169.5k req/s across the 3x3 language matrix

• POSIX SHM ping-pong

  • 2.32M to 3.22M req/s

• POSIX UDS batch ping-pong

  • 20.18M to 30.13M req/s

• POSIX SHM batch ping-pong

  • 28.71M to 48.95M req/s

• POSIX UDS pipeline (depth=16)

  • 440.4k to 620.6k req/s

• POSIX UDS pipeline+batch (depth=16)

  • 41.61M to 76.45M req/s

• POSIX snapshot refresh

  • baseline: 131.2k to 156.3k req/s
  • SHM: 1.10M to 1.52M req/s

• POSIX lookup methods

  • cgroups-lookup: 31.8k to 1.10M req/s across max-rate scenarios
  • apps-lookup: 35.7k to 1.34M req/s across max-rate scenarios

• POSIX local cache lookup

  • C: 173.47M req/s
  • Go: 138.48M req/s
  • Rust: 147.68M req/s

• Windows Named Pipe ping-pong

  • 18.2k to 21.0k req/s

• Windows SHM ping-pong

  • 2.10M to 2.72M req/s

• Windows Named Pipe batch ping-pong

  • 7.01M to 8.55M req/s

• Windows SHM batch ping-pong

  • 36.49M to 58.77M req/s

• Windows Named Pipe pipeline (depth=16)

  • 245.4k to 270.5k req/s

• Windows Named Pipe pipeline+batch (depth=16)

  • 28.98M to 41.27M req/s

• Windows snapshot refresh

  • Named Pipe: 16.1k to 21.0k req/s
  • SHM: 857.8k to 1.26M req/s

• Windows local cache lookup

  • C: 130.65M req/s
  • Go: 107.47M req/s
  • Rust: 164.31M req/s

The full reports include:

• per-pair throughput
• latency percentiles
• client and server CPU
• complete scenario validation summaries
• performance floor checks

Reliability, Testing, And Coverage

The repo is not asking the reader to trust the design on words alone. The current validation story includes:

• CMake-based build and ctest workflows
• unit tests
• cross-language interop tests
• typed service tests
• transport tests
• shared-memory tests
• a required Linux size-limited-tmpfs regression for graceful SHM allocation failure
• coverage scripts for C, Go, and Rust
• benchmark generators that reject incomplete matrices

Current verified state

Linux / POSIX:

• build: passing
• ctest: 49/49 passing
• C coverage (tracked C gate files): 91.8%
• Go coverage (overall source packages): 90.2%
• Rust coverage (Linux library, Windows-tagged files excluded): 92.63%
  • measured with cargo-llvm-cov
  • Linux run now excludes Windows-tagged Rust files from the Linux total
  • Unix Rust service tests now live in a separate cgroups_unix_tests.rs file
  • Unix Rust transport tests now live in separate posix_tests.rs and shm_tests.rs files
  • the small Rust protocol test modules stay inline for now because externalizing them lowered the headline total without enough runtime-signal benefit

Windows (win11):

• build: passing
• ctest: 28/28 passing
• C coverage: 93.2%
• Go coverage: 95.4%
• Rust coverage: 92.08%

Important honesty point:

• core build, transport, service, interop, and benchmark validation is strong on both Linux and Windows
• Linux still has broader chaos / hardening / stress breadth than Windows
• so the platforms are in good functional parity, but not yet in full validation parity

Coverage details:

• WINDOWS-COVERAGE.md
• COVERAGE-EXCLUSIONS.md

Specifications And Trust Model

The specs are authoritative.

Rule:

• when code and spec disagree, the spec wins unless explicitly revised

Start here:

• docs/README.md

Recommended reading order:

1. docs/README.md
2. docs/getting-started.md
3. docs/level2-typed-api.md
4. docs/level3-snapshot-api.md
5. the relevant Level 1 transport spec for your platform

Building And Running

The standalone Rust package uses Rust edition 2024 and requires Rust 1.91 or newer. Use the latest stable toolchain for normal development; CI also compiles every target with Rust 1.91.0 to enforce the minimum. The repository rustfmt.toml keeps formatting on style edition 2021 independently of the language edition.

Linux / POSIX

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j4
ctest --test-dir build --output-on-failure -j4

Coverage:

bash tests/run-coverage-c.sh
bash tests/run-coverage-go.sh
bash tests/run-coverage-rust.sh

Windows (win11)

Use a mingw64 shell with native Windows cargo and go ahead of any MSYS toolchain copies in PATH. The native Rust toolchain must be Rust 1.91 or newer. This remains the native Windows sign-off path.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j4
ctest --test-dir build --output-on-failure -j4

MSYS transition validation:

bash tests/run-windows-msys-validation.sh

That lane builds the C artifacts with /usr/bin/gcc, runs the targeted Windows functional/interoperability slice, repeats test_win_shm, and compares a bounded benchmark subset against the native mingw64 lane with explicit throughput floors per scenario. Policy-failed benchmark rows are rerun as paired native+MSYS rows before final failure, with prior attempts saved next to the final policy.csv. It does not replace native Windows sign-off.

Coverage:

bash tests/run-coverage-c-windows.sh
bash tests/run-coverage-go-windows.sh
bash tests/run-coverage-rust-windows.sh

Verifier:

bash tests/run-verifier-windows.sh

For practical Windows workflow details, see:

• WINDOWS-COVERAGE.md
• TODO-pending-from-rewrite.md

Repository Layout

.
├── bench/
│   └── drivers/
├── docs/
├── src/
│   ├── crates/netipc/
│   ├── go/pkg/netipc/
│   └── libnetdata/netipc/
└── tests/
    ├── fixtures/
    └── run-*.sh

Main implementation roots:

• C: src/libnetdata/netipc/
• Rust: src/crates/netipc/
• Go: src/go/pkg/netipc/

Current Limits

This is the honest current state:

• coverage thresholds are enforced, but they are not at 100%
• Linux and Windows are functionally close, but Windows still has less chaos / hardening / stress breadth
• Linux SHM requires fallocate in strict syscall allowlists; seccomp policies that kill or trap it cannot be converted automatically into NetIPC baseline fallback
• some documented exclusions still require special infrastructure such as:
  • allocation-failure injection
  • kernel / OS failure injection
  • race-window orchestration

Those limits are tracked explicitly instead of being hidden:

• COVERAGE-EXCLUSIONS.md
• TODO-pending-from-rewrite.md

Summary

If you need the shortest trustworthy summary:

• the protocol stack is specified, implemented, and measured in C, Rust, and Go
• interop across the three languages is a core requirement, not an afterthought
• both POSIX and Windows have validated baseline and SHM benchmark matrices
• the public service API is typed
• the local snapshot/cache layer is implemented and benchmarked
• the repo has real tests, real coverage, and real benchmark artifacts checked in

For design details, start with docs/README.md.