Shared

The shared crate is the low-level cross-cutting utility layer used by modules, drivers, and executables.

Role

• Centralizes reusable primitives that do not belong to one domain subsystem.
• Reduces duplication of utility code and shared type definitions across the workspace.

Boundaries

• In scope: generic helpers and value types (flags, size, time, HTTP/unit/UTF-8/slice helpers, layout-based any wrappers).
• Out of scope: module orchestration, stateful managers, backend-specific logic.

Internal structure

• Utility modules include any, bijective_map, flags, http, size, slice, task, time, unit, utf8.
• error.rs provides shared error representation utilities.

Runtime interaction

• Typically used as pure library calls/value containers.
• Frequently appears at crate boundaries where generic data conversion is needed (for example control payload casting and UTF-8 chunk iteration).

Dependency model

• Dependency-light by design (num, workspace log).
• Sits near the bottom of the dependency graph and is imported by many crates.

Failure semantics

• Errors are mostly local utility conversion/validation errors (for example slice/layout checks).
• Crates consuming shared utilities usually remap these errors into their own domains.

Extension points

• Add new generic helpers when used by multiple subsystems.
• Keep module additions cohesion-focused to avoid this crate becoming a catch-all for domain logic.

Contract vs implementation

• Contract: stable, dependency-light utility API surface safe for broad workspace reuse.
• Current implementation: collection of no-std-friendly helper modules with selective logging integration.

Limitations and trade-offs

• Broad reuse increases API stability pressure.
• Keeping scope strictly “shared only” avoids coupling but may require small wrappers in consumer crates.

Core public helpers and borrowing rules

The library is no_std with alloc. AnyByLayout is a borrowed byte-layout wrapper used by typed VFS/device controls. AnyByLayout::from(&value) and from_mutable(&mut value) expose bytes of a live Rust value; cast::<T>() and cast_mutable::<T>() attempt to recover a typed reference. The unsafe from_raw_parts form requires a valid, correctly aligned raw buffer for its entire lifetime.

use shared::AnyByLayout;
let value: u32 = 42;
let raw = AnyByLayout::from(&value);
assert_eq!(raw.get_size(), core::mem::size_of::<u32>());
assert_eq!(raw.cast::<u32>(), Some(&42));

Do not treat this as arbitrary wire deserialization. The byte layout is the compiler’s in-memory representation and may include padding or architecture-dependent details. Typed command contracts still need exact type, size, alignment and initialization guarantees; untrusted bytes should be validated through explicit parsing instead.

Additional utilities

• xila_http::Url::parse("https://example.com/path") splits the borrowed scheme, host and path and defaults to "/" when no path is supplied. It is a small structural helper, not a full URL parser/validator, so do not use it as an origin-security boundary.
• utf8_chunks(&bytes) iterates valid UTF-8 fragments and skips malformed bytes; it may also yield empty strings where invalid bytes were encountered. It is intended for lossy text presentation, not for validating configuration or filenames.
• BijectiveMap and size/unit/time helpers reduce duplicate representations across consumers, while the shadow_type module provides reusable typed wrappers.
• HTTP response/request parsing is now a separate HTTP library, not part of shared; shared does not own sockets or routing.

Ownership and limitations

These helpers do not register global services and their data lifetimes remain with the caller. Prefer domain-specific types inside subsystem public APIs rather than growing shared into a catch-all that forces unrelated crates to couple.

Source and API references

• libraries/shared/src/any.rs - byte layout and casts.
• libraries/http/src/url.rs - compact URL parsing.
• libraries/shared/src/utf8.rs - lossy UTF-8 iteration.
• shared::AnyByLayout - device-control payload helper.

References

• shared crate
• libraries/shared
• Synchronization