coreshift_core/lib.rs
1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/
4
5//! CoreShift Core is the low-level Linux and Android foundation crate for the
6//! CoreShift ecosystem.
7//!
8//! CoreShift Core keeps direct kernel, `libc`, and procfs interaction in one
9//! place so higher layers can stay policy-oriented:
10//! - **CoreShift Core**: low-level Linux and Android primitives
11//! - **CoreShift Engine**: daemon and plugin runtime
12//! - **CoreShift Policy**: policy logic and product behavior
13//!
14//! This crate is intentionally policy-neutral. It provides mechanisms such as
15//! spawning, `epoll`, `inotify`, procfs inspection, and signal helpers. It
16//! does not make daemon lifecycle or product decisions for callers.
17//!
18//! ### Core Guarantees
19//!
20//! Core adheres to strict architectural invariants to ensure stability:
21//! - **No policy**: Primitives only; no allowlists, retry plans, or fallbacks.
22//! - **No hidden threads**: Work is performed on the caller's thread.
23//! Exceptions, all documented in `docs/ARCHITECTURE.md`: `binder` runs one
24//! process-lifetime NDK binder pool thread to receive framework callbacks
25//! (required by the NDK), and `spawn` runs one `spawn-orphan-reaper` thread
26//! that reaps children the caller gave up on and keeps sweeping sessions the
27//! D-state give-up handed to it (kill-totality, findings 15/H2).
28//! - **No global state**: Stateless execution; no global mutable configuration.
29//! Sole exception: `binder` keeps process-wide callback statics because NDK
30//! callbacks arrive with no caller userdata pointer to thread state through.
31//! - **No scheduler**: Provides reactor primitives but does not own execution.
32//!
33//! Public primitive modules:
34//! - [`crate::android::property`] for direct Android system property access
35//! - [`crate::binder`] for NDK binder service queries (Android only)
36//! - [`crate::drm`] for DRM card vblank wait primitives
37//! - [`crate::fs`] for filesystem probes and readahead
38//! - [`crate::proc`] for procfs helpers
39//! - [`crate::signal`] for signal and shutdown helpers
40//! - [`crate::spawn`] for explicit process spawning
41//! - [`crate::reactor`] for fd readiness primitives
42//! - [`crate::inotify`] for watch/decode helpers
43//! - [`crate::socket`] for Unix domain socket primitives
44//! - [`crate::io`] for explicit drain helpers
45//! - [`crate::transport`] for the command/watcher transport seam
46//!
47//! ```compile_fail
48//! use coreshift_core::Daemon;
49//! ```
50//!
51//! ```compile_fail
52//! use coreshift_core::ForegroundResolver;
53//! ```
54
55pub mod android;
56pub mod binder;
57pub mod drm;
58pub mod error;
59pub mod fd;
60pub mod fs;
61pub mod inotify;
62pub mod io;
63pub mod log;
64pub mod proc;
65pub mod process;
66pub mod reactor;
67pub mod signal;
68pub mod socket;
69pub mod spawn;
70pub mod transport;
71pub mod uevent;
72
73pub use error::CoreError;
74
75#[cfg(test)]
76mod tests;