lib-service

lib-service is the service-discovery client helper crate for EriX.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

Technical requirements are tracked in the EriX requirements, conventions, and project documentation.

See:

• docs for design documents, specifications, and development plans.
• Related architecture repositories for kernel, services, libraries, drivers, and integration tooling.

Purpose of This Repository

This repository implements the EriX service library. Its purpose in EriX is to provide reusable service primitives and contracts to EriX components.

Functionally, it exposes the service APIs, validation tests, and documentation used by dependent repositories. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• expose the lib-service crate API for service behavior used by dependent components
• keep data formats, constants, and validation helpers documented and tested
• preserve clean-room, no-external-crate implementation boundaries
• keep retry, scheduling, cancellation, and CSpace authority with callers
• coordinate deliberate API changes across downstream repositories

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

EriX development is modular, deterministic, reproducible, authority-explicit, security-first, and self-hosting oriented.

This repository follows the project roadmap and the validation rules documented in its own roadmap.

Status

• Service discovery is fully implemented.
• Used by memd, vspaced, pagerd, and procd for service discovery.
• Target-scoped resolution performs exactly one RPC and exposes transient results to caller-owned policy.
• Endpoint validation and cleanup use caller-supplied CSpace operations; the crate has no syscall dependency or ambient process authority.
• Scoped resolution validates the target's exact publication rights: ordinary peers receive SEND, while IRQD receives SEND|GRANT so clients can explicitly delegate handler endpoints during registration.
• Successful resolution also requires one exact kernel-normalized transfer receipt. The shared transport capacity includes that receipt, and unexpected receipt destinations are dropped through the caller-supplied CSpace operation.
• Unit tests cover response framing, normalized authority receipts, explicit CSpace operations, and fail-closed cleanup.

Build and test

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

Repository CI prepares identity-preserving caches for exact commit-pinned dependencies before default-feature cargo build, cargo test, and cargo doc.

Governance Principles

lib-service governance is scoped to reusable service contracts shared by dependent repositories.

The scoped governance rules are:

• It must expose narrow, documented APIs rather than component-specific policy.
• It keeps wire formats, constants, parsers, and validation helpers deterministic and testable.
• It preserves clean-room implementation boundaries and does not introduce external crate dependencies.
• API or format changes require coordinated updates in every dependent repository; pre-alpha interfaces do not retain obsolete compatibility shims.

Library Boundaries

• lib-service carries no runtime authority by itself; authority is held by callers that use the library.
• The crate must not hide ambient I/O, allocation policy, or service discovery behind helper APIs.
• Every library RPC performs one transport attempt. Retry and scheduling policy remains visible in the caller.

Contact

Development occurs in EriX organization and discussions happen in issues and design documents.

No decisions are considered valid without documented rationale.

Maintainers can be reached via email: admin@erikinkinen.fi.