Orion

Orion is a Rust workspace for a distributed node runtime with a facade crate, node binary, client SDK, transport adapters, and operator CLI.

The repository is split into focused crates so runtime, transport, client, and operational surfaces can evolve independently.

Workspace Layout

• crates/orion: consumer-facing facade and public API re-exports
• crates/node: node binary and runtime orchestration
• crates/client: Rust SDK for local and daemon clients
• crates/orionctl: operator CLI
• crates/runtime, crates/cluster, crates/control-plane, crates/data-plane: core runtime and protocol crates
• crates/transport-*: HTTP, TCP, QUIC, and IPC transport adapters
• crates/link: no_std framing for the MCU link protocol (CRC frames, COBS streams, CAN / CAN FD segmentation)
• crates/auth, crates/service, crates/macros, crates/core: shared support crates

Additional repository notes live under docs/README.md.

Getting Started

Build the workspace:

cargo build --workspace

Run the node:

cargo run -p orion-node

Run the CLI:

cargo run -p orionctl -- --help

Run the default validation surface:

cargo fmt --check
./scripts/check-file-sizes.sh
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features

Development

Common workspace commands:

./scripts/repo-clean.sh
cargo fmt --check
./scripts/check-file-sizes.sh
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo doc --workspace --no-deps

Heavier Docker, perf, and soak suites are intentionally separate and are documented in docs/testing.md.

Documentation Index

• docs/README.md: repository documentation index
• docs/architecture-crate-map.md: how the workspace crates fit together
• docs/development.md: repo layout, validation commands, and CI expectations
• docs/testing.md: test surfaces, Docker suites, perf, and soak notes
• CHANGELOG.md: release history and notable workspace changes
• testing/README.md: local and CI validation entry points
• scripts/repo-clean.sh: pre-commit cleanup and verification entry point
• docs/node-env.md: runtime environment contract
• packaging/README.md: run orion-node as a systemd service on Linux images (unit, env file, Gaia layer)
• docs/release-validation.md: release validation checklist
• docs/observability.md: health, readiness, and observability notes
• docs/logging.md: runtime logging behavior
• docs/public-api.md: public constructors and compatibility shims

Configuration

The node is configured primarily through environment variables. The typed entrypoints live in orion-node and use try_* constructors instead of panic-based startup helpers.

Important env vars include:

• ORION_NODE_ID
• ORION_NODE_HTTP_ADDR
• ORION_NODE_IPC_SOCKET
• ORION_NODE_PEERS (http://, https://, or orion+tcp:// peers)
• ORION_NODE_PEER_ADDR (orion+tcp peer listener)
• ORION_NODE_PEER_AUTH
• ORION_NODE_PEER_SYNC_MODE
• ORION_NODE_STATE_DIR
• ORION_NODE_HTTP_MTLS
• ORION_NODE_LOCAL_AUTH
• ORION_NODE_HTTP_PROBE_ADDR
• ORION_NODE_AUDIT_LOG

For the full runtime contract, defaults, and failure behavior, see docs/node-env.md. For release validation and ignored-suite guidance, see docs/release-validation.md. For audit-log behavior and operator guidance, see docs/audit-logging.md. For health/readiness/observability coverage, see docs/observability.md. For runtime logging behavior and operator guidance, see docs/logging.md. For preferred public constructors versus compatibility shims, see docs/public-api.md. For the current locking, blocking, and peer-sync concurrency audit, see docs/performance-concurrency.md. For the crate layout and layering, see docs/architecture-crate-map.md. For peer sync transports, merge rules, tombstones, and the protocol v3 upgrade, see docs/peer-sync.md.

Features

The facade crate orion is feature-gated by subsystem.

• Default features cover core, auth, control-plane, data-plane, and runtime.
• client enables the Rust SDK and implies runtime.
• service, macros, and cluster are explicit opt-ins.
• Transport layers stay opt-in through transport-http, transport-ipc, transport-tcp, and transport-quic.
• orion-client defaults to local IPC support through its ipc feature.
• orion-node enables transport-http, peer-tcp, transport-tcp, and transport-quic by default. The local IPC control plane is always built. cargo build -p orion-node --no-default-features produces an IPC-only node without the HTTP stack (no axum, hyper, reqwest, or rustls). In that build the HTTP control and probe listeners and HTTP TLS are unavailable, and configuring them fails at startup with an error. You can add back any of the transport features independently.
• orion-node's peer-tcp feature syncs desired state with orion+tcp:// peers over plain TCP with ed25519-signed requests and responses (ORION_NODE_PEER_ADDR listener). It needs only tokio, so --no-default-features --features peer-tcp gives a small IPC-only node that can still cluster. Concurrent writes from different nodes are merged per object, last writer wins by hybrid logical clock. See docs/peer-sync.md.
• orion-node's opt-in discovery-mdns feature finds the peers of a cluster with mDNS/DNS-SD (ORION_NODE_DISCOVERY=mdns, ORION_NODE_CLUSTER). Discovered peers are never trusted on their own: an operator enrolls them after comparing key fingerprints (orionctl get discovered-peers, orionctl peers enroll <node-id>), or nodes sharing ORION_NODE_ENROLLMENT_KEY enroll each other with a challenge-response handshake. Works in the appliance build (--no-default-features --features peer-tcp,discovery-mdns). See docs/discovery.md.
• orion-client's remote feature is an embeddable remote operator client for desktop and fleet tools: an ed25519 operator identity, enrollment (administrator approval with orionctl operators enroll, or the shared enrollment key), and signed orion+tcp requests to list node records with host facts, read status (forwarded to the owning node), run actions (forwarded to the owning node) and read observability, without running orion-node and without an HTTP stack. Nodes treat operators as their own principal kind with per-operator authorization; operators never become cluster members. See docs/remote-operator.md.
• orion-node's opt-in link-gateway feature (Linux) serves microcontroller links (serial ports and SocketCAN, configured with ORION_NODE_LINKS) and bridges each orion-link device into the node as an ordinary provider. It also works in the IPC-only build (--no-default-features --features link-gateway). See docs/link-protocol.md.
• orion-transport-http exposes its protocol types (payloads, routes, codec, errors, and handler traits) without the network stack. client adds HttpClient (reqwest over rustls, no axum/hyper server), server adds HttpServer (axum, hyper, tokio-rustls), and the default transport feature enables both.
• orionctl features http (--http remote targets, HTTP client only), yaml and toml (output formats and workload spec files) are all on by default. cargo build -p orionctl --no-default-features gives an IPC-only CLI with JSON output (1.80 MiB stripped, against 4.38 MiB for the default build); requesting a disabled transport or format fails with an error that names the feature. See crates/orionctl/README.md.

For production consumers that want a narrow dependency surface, prefer direct crate dependencies or disable default features on the facade and opt in explicitly.

Operational Surface

orion-node exposes:

• health and readiness endpoints
• observability snapshots
• local IPC control and stream sockets
• peer sync over HTTP(S) or orion+tcp, with per-object conflict resolution (docs/peer-sync.md)
• optional HTTP/TCP/QUIC transport security
• optional audit logging

Current high-value runtime endpoints and surfaces:

• HTTP control surface on ORION_NODE_HTTP_ADDR
• optional HTTP probe surface on ORION_NODE_HTTP_PROBE_ADDR
• local IPC unary socket on ORION_NODE_IPC_SOCKET
• local IPC stream socket on ORION_NODE_IPC_STREAM_SOCKET

Observability and runtime debugging rely on:

• health snapshots
• readiness snapshots
• observability snapshots with recent events and transport counters
• structured tracing from the node runtime
• optional audit log records for trust and transport-security lifecycle events

Notes On Performance

Most of the runtime and transport surface is written in an allocation-conscious style, but not every API is a zero-cost abstraction. In particular, orion-service intentionally uses Arc<dyn Trait> middleware for ergonomics at the control-plane boundary.

License

Licensed under either:

• MIT
• Apache-2.0