Skip to main content

engine/
lib.rs

1#![warn(missing_docs)]
2
3//! The generic state substrate for the Virtual Computing Engine.
4//!
5//! This crate implements the **Engine** layer of the Virtual Computing
6//! Engine. It provides generic mechanisms only: object identity,
7//! metadata, a filesystem, detached namespaces, generic authorization, and a
8//! synchronous event system. It must never know about processes, networking,
9//! firewalls, package managers, or any operating system.
10//!
11//! The OS layer (not part of this crate) gives these mechanisms meaning.
12//!
13//! # Modules
14//!
15//! - [`core`] — object identity, object kinds, metadata, virtual time.
16//! - [`filesystem`] — the generic filesystem tree, paths, detached namespaces.
17//! - [`security`] — principals/actors, generic authorization mechanisms.
18//! - [`events`] — the synchronous event system and event bus.
19//! - [`io`] — generic input/output primitives (streams, pipes, and the
20//!   interactive terminal interface).
21//! - [`engine`] — the [`Engine`] facade combining everything.
22//!
23//! # Event model
24//!
25//! A state mutation commits atomically, then synchronously dispatches its
26//! event chain. Listeners observe the completed state and may
27//! re-enter the Engine (for example, to derive state). Dispatch never holds
28//! the store lock, so listener re-entry is safe.
29//!
30//! # Time
31//!
32//! The shared timeline is monotonic once seeded: it only ever moves
33//! forward ([`VirtualClock::set`] asserts this in debug builds). Work that
34//! must *appear* asynchronous (a background job) runs under
35//! [`Engine::suspend_time`], which books the virtual time it consumes
36//! against that work instead of moving the machine-wide clock backwards.
37
38pub mod core;
39pub mod engine;
40pub mod error;
41pub mod events;
42pub mod filesystem;
43pub mod io;
44pub mod security;
45
46pub use crate::core::metadata::{Metadata, MetadataPatch, MetadataValue, Name};
47pub use crate::core::object::ObjectKind;
48pub use crate::core::object_id::{Id, ObjectId};
49pub use crate::core::time::{Clock, HostClock, Timestamp, VirtualClock};
50pub use crate::engine::{CreateOptions, Engine};
51pub use crate::error::Error;
52pub use crate::events::event::{EventData, ObjectEvent};
53pub use crate::events::event_bus::EventBus;
54pub use crate::events::event_type::EventType;
55pub use crate::events::subscription::SubscriptionId;
56pub use crate::filesystem::detached_namespace::DetachedNamespace;
57pub use crate::filesystem::path::VirtualPath;
58pub use crate::io::{
59    BytesInput, BytesOutput, EmptyInput, Input, InputError, InputMode, Key, KeyEvent, Output,
60    OutputError, Pipe, SinkOutput, Size, StringInput, Terminal,
61};
62pub use crate::security::actor::ActorId;
63pub use crate::security::authorization::{
64    AuthorizationData, AuthorizationPolicy, AuthorizationRequest, AuthorizationResult, Operation,
65    ParentReference, PermissivePolicy,
66};