Skip to content

v0.2.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 27 Feb 15:43
v0.2.0
cee0318
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

ipcprims v0.2.0

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

Summary

Tokio-native async API on Unix (UDS). First minor version bump adding new public API surface since v0.1.0. Introduces a full async stack behind the async feature flag, MSRV consistency fixes, and developer tooling improvements.

Async (Tokio, Unix-only)

Transport Layer

ipcprims-transport gains async UDS transport types gated behind #[cfg(all(unix, feature = "async"))]:

Type Purpose
AsyncIpcStream Wraps tokio::net::UnixStream with async peer_credentials()
AsyncUnixDomainSocket bind() (sync), accept()/connect() (async)

Frame Codec

ipcprims-frame adds IpcCodec for tokio_util::codec::Framed* integration:

#[cfg(feature = "async")]
pub struct IpcCodec { config: FrameConfig }

impl Decoder for IpcCodec {
    type Item = Frame;
    type Error = FrameError;
    fn decode(&mut self, src: &mut BytesMut) -> Result<Option<Frame>, FrameError>;
}

impl Encoder<Frame> for IpcCodec {
    type Error = FrameError;
    fn encode(&mut self, frame: Frame, dst: &mut BytesMut) -> Result<(), FrameError>;
}

This enables composable Tokio ecosystem integration via Framed<AsyncIpcStream, IpcCodec>.

Peer Layer

ipcprims-peer adds async peer management:

Type Purpose
AsyncPeer Split Tx/Rx handles with background reader task
AsyncPeerListener Async accept() with builder pattern
async_connect() Convenience function for client-side connections
async_connect_with_config() Full-config variant

AsyncPeer Design (ADR-0001)

Aspect Behavior
Read model Background reader task dispatches to per-channel mpsc::Receiver + optional arrival-ordered any_rx queue
Write model &self send with internal tokio::sync::Mutex for concurrent writes
Split handles peer.into_split() -> (AsyncPeerTx, AsyncPeerRx)
Cancellation Optional external CancellationToken; reader task cancels on drop
CONTROL Reader task auto-handles ping/pong and shutdown

Platform Scope

Platform Async Status
Linux x64 (glibc/musl) Supported
Linux arm64 (glibc/musl) Supported
macOS arm64 Supported
Windows x64 Deferred to v0.2.1

Important: In v0.2.0, the async peer API (AsyncPeer, AsyncPeerListener, async_connect) is Unix-gated — these types do not compile on Windows. Windows async named pipes are NOT a gate for v0.2.0. Windows transport (sync named pipes) remains planned; the existing placeholder/cfg-gating behavior is unchanged.

MSRV Consistency

Resolves inconsistencies discovered during Lanyte integration:

Location Before After
README.md badge 1.81+ 1.85+
envinfo.rs test fixture 1.81.0 1.85.0
ipcprims-napi Cargo.toml workspace = true 1.88.0 (napi-build requirement)

MSRV Policy

  • Core crates: MSRV 1.85.0 (workspace rust-version)
  • Binding crates: MSRV 1.88.0 (napi-build requirement, explicit override)
  • Local verification: make msrv (excludes ipcprims-napi)
  • CI verification: Tag-triggered msrv-matrix.yml (Linux/macOS/Windows)

Dev Tooling

Local Windows Cross-Check

New Makefile targets mirror CI windows-cross-check:

make check-windows           # All Windows targets
make check-windows-msvc      # x86_64-pc-windows-msvc
make check-windows-gnu       # x86_64-pc-windows-gnu
make check-windows-arm64-msvc # aarch64-pc-windows-msvc

Each runs cargo check -p ipcprims-transport -p ipcprims-frame --target <triple> with RUSTFLAGS="-Dwarnings". This enables early detection of Windows-only warnings without CI round-trips.

AI-Assisted Commit Template

scripts/commit-template-ai.txt provides the correct trailer format for AI-assisted commits:

git commit -t scripts/commit-template-ai.txt

Test Coverage

Async Peer Tests

Scenario Coverage
Arrival-ordered global queue (any_rx) Verified via async ordering tests
Per-channel tee semantics Same frame observed on any + per-channel paths
Buffer-full disconnect Exceeding max_buffer_per_channel triggers peer disconnect
External cancellation CancellationToken triggers clean reader shutdown
Drop without explicit shutdown Reader task cancels, socket closes on drop

Async UDS Hardening Parity

Async UDS transport mirrors sync hardening tests:

  • path_too_long → TransportError::PathTooLong
  • bind_default_permissions_hardened → socket file mode 0o600
  • bind_rejects_existing_non_socket_file
  • drop_does_not_remove_replaced_path (inode identity check)
  • drop_cleans_socket_file_when_identity_matches

Framed Integration

IpcCodec tested via tokio_util::codec::Framed*:

  • Full round-trip through Framed stack
  • Oversize-length rejection regression test

Quality

  • All tests passing (cargo test --workspace --all-features)
  • Zero clippy warnings (--all-features)
  • make prepush green
  • All dependencies permissively licensed
  • MSRV gate: make msrv (requires rustup 1.85)

New Dependencies (async feature only)

Crate Version Purpose
tokio-util 0.7 codec::Framed, Decoder, Encoder
futures-core 0.3 Stream trait for async receivers

All pass cargo deny check licenses (MIT/Apache-2.0).

Known Issues

  • Windows async: Deferred to v0.2.1 (sync named pipes + async follow-on)
  • Transitive dep duplication: getrandom (0.2 + 0.3) and windows-sys (0.60 + 0.61) via jsonschema dep tree. No functional impact.

What's Next

  • v0.2.1: Windows named pipes (sync first, async follow-on), full Windows CI integration, local Windows development session

References

  • ADR-0001: docs/decisions/ADR-0001-async-peer-receive-model.md
  • CI/CD documentation: docs/cicd.md
Assets 22
Loading