Skip to content

Release 0.1.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 14 Feb 15:14
v0.1.0
748f8cb

ipcprims v0.1.0

Release date: 2026-02-13
Lifecycle phase: alpha
License: MIT OR Apache-2.0

Summary

First functional release of ipcprims — permissively licensed, cross-platform IPC primitives with framed messaging, channel multiplexing, schema validation, peer management, and a diagnostic CLI.

Highlights

  • Transport layer: Unix domain socket transport with bind/accept/connect, hardened permissions (0o600), automatic socket cleanup on drop
  • Frame codec: Length-prefixed wire format with 2-byte magic ("IP"), 4-byte LE length, 2-byte LE channel ID; 8-byte header, 16 MiB default max payload
  • Channel system: Built-in channels (CONTROL=0, COMMAND=1, DATA=2, TELEMETRY=3, ERROR=4) with user-defined range 256-65535
  • Framed reader/writer: Sync FrameReader/FrameWriter wrapping any Read/Write stream; partial-read handling, WouldBlock propagation, configurable timeouts
  • Schema validation: JSON Schema 2020-12 validation at the transport boundary via SchemaRegistry; strict mode (deny_unknown_fields), directory loading with symlink rejection and file-size limits
  • Peer management: Handshake protocol over CONTROL channel with version negotiation, channel intersection, and optional auth token; Peer API with send/recv/recv_on/request patterns, bounded per-channel buffering, control flood protection, graceful shutdown
  • CLI: 8 commands — listen, send, echo, info, doctor, envinfo, version (with --extended); --format json|table|pretty|raw, rsfulmen-aligned exit codes, tracing to stderr
  • Security review: 5 accepted SDRs (schema validation scope, peer/transport hardening, registry boundaries, auth token handling, ordering/replay boundary)
  • Dogfooding: End-to-end CLI behavior matrix with P0-P3 findings all remediated

Crates

Crate Description
ipcprims-transport Cross-platform IPC transport abstraction (UDS on Linux/macOS)
ipcprims-frame Length-prefixed message framing with channel multiplexing
ipcprims-schema Optional JSON Schema 2020-12 validation (behind schema feature)
ipcprims-peer High-level peer connection management (behind peer feature)
ipcprims Umbrella crate (re-exports) + CLI binary (behind cli feature)

CLI Commands

Command Purpose
listen Start a listener on a Unix domain socket
send Connect and send a framed message (with --wait and --wait-timeout)
echo Echo server for integration testing (with --validate for schema checks)
info Connection diagnostics and peer status
doctor Environment health check
envinfo Build and platform metadata
version Version with --extended provenance (git hash, target triple)

Exit Codes

Condition Code
Success 0
Connection refused 1
Transport error 3
Health check failed 30
Permission denied 50
Schema validation / data invalid 60
Invalid arguments (usage) 64
Timeout 124
Internal error 125

Wire Format

+----------+---------+---------+-----------------+
| Magic 2B | Len 4B  | Chan 2B | Payload         |
| "IP"     | (LE)    | (LE)    | (Len bytes)     |
+----------+---------+---------+-----------------+

Wire format is frozen for the 0.x series.

Platform Support

Platform Transport Status
Linux x64/arm64 (glibc + musl) UDS (abstract) Primary
macOS arm64 UDS (filesystem) Supported
Windows x64 Named pipes Deferred to v0.2.0

Quality

  • 118 tests passing (cargo test --workspace --all-features)
  • Zero clippy warnings (--all-features)
  • License-clean: all dependencies MIT/Apache-2.0/BSD/ISC (verified via cargo deny)
  • Decision records: DDR-0001, DDR-0002, SDR-0001 through SDR-0005 (all Accepted)

Known Issues

  • Async API: Feature flags (async) are declared but no async code exists yet. Planned for v0.2.0.
  • Transitive dep duplication: getrandom (0.2 + 0.3) and windows-sys (0.60 + 0.61) appear as duplicates via the jsonschema dependency tree. No functional impact; tracked for supply chain awareness.
  • FFI: cbindgen.toml is present as a placeholder; the ffi/ crate does not exist yet. Planned for v0.2.0.

What's Next (v0.2.0)

  • Tokio-native async API behind async feature flag
  • TCP transport behind feature flag (per DDR-0001)
  • CLI P2 commands: connect --interactive, monitor, bench
  • FFI crate + Go bindings

Decision Records

ID Title Status
DDR-0001 Transport Scope: IPC-First, Extensible Accepted
DDR-0002 CLI Design Precepts Accepted
SDR-0001 Schema Validation at IPC Boundary Accepted
SDR-0002 Peer and Transport Hardening Defaults Accepted
SDR-0003 Schema Registry Hardening Boundaries Accepted
SDR-0004 auth_token and Peer Credentials Boundary Accepted
SDR-0005 Ordering and Replay Boundary Accepted
Assets 15
Loading