asupersync/
lib.rs

1//! Asupersync: Spec-first, cancel-correct, capability-secure async runtime for Rust.
2//!
3//! # Overview
4//!
5//! Asupersync is an async runtime built on the principle that correctness should be
6//! structural, not conventional. Every task is owned by a region that closes to
7//! quiescence. Cancellation is a first-class protocol, not a silent drop. Effects
8//! require explicit capabilities.
9//!
10//! # Core Guarantees
11//!
12//! - **No orphan tasks**: Every spawned task is owned by a region; region close waits for all children
13//! - **Cancel-correctness**: Cancellation is request → drain → finalize, never silent data loss
14//! - **Bounded cleanup**: Cleanup budgets are sufficient conditions, not hopes
15//! - **No silent drops**: Two-phase effects (reserve/commit) prevent data loss
16//! - **Deterministic testing**: Lab runtime with virtual time and deterministic scheduling
17//! - **Capability security**: All effects flow through explicit `Cx`; no ambient authority
18//!
19//! # Module Structure
20//!
21//! - [`types`]: Core types (identifiers, outcomes, budgets, policies)
22//! - [`record`]: Internal records for tasks, regions, obligations
23//! - [`trace`](mod@trace): Tracing infrastructure for deterministic replay
24//! - [`runtime`]: Scheduler and runtime state
25//! - [`cx`]: Capability context and scope API
26//! - [`combinator`]: Join, race, timeout combinators
27//! - [`lab`]: Deterministic lab runtime for testing
28//! - [`util`]: Internal utilities (deterministic RNG, arenas)
29//! - [`error`](mod@error): Error types
30//! - [`channel`]: Two-phase channel primitives (MPSC, etc.)
31//! - [`encoding`]: RaptorQ encoding pipeline
32//! - [`observability`]: Structured logging, metrics, and diagnostic context
33//! - [`security`]: Symbol authentication and security primitives
34//! - [`time`]: Sleep and timeout primitives for time-based operations
35//! - [`io`]: Async I/O traits and adapters
36//! - [`net`]: Async networking primitives (Phase 0: synchronous wrappers)
37//! - [`bytes`]: Zero-copy buffer types (Bytes, BytesMut, Buf, BufMut)
38//! - [`tracing_compat`]: Optional tracing integration (requires `tracing-integration` feature)
39//! - [`plan`]: Plan DAG IR for join/race/timeout rewrites
40//!
41//! # API Stability
42//!
43//! Asupersync is currently in the 0.x series. Unless explicitly noted in
44//! `docs/api_audit.md`, public items should be treated as **unstable** and
45//! subject to change. Core types like [`Cx`], [`Outcome`], and [`Budget`] are
46//! intended to stabilize first.
47
48// Default to deny for unsafe code - specific modules (like epoll reactor) can use #[allow(unsafe_code)]
49// when they need to interface with FFI or low-level system APIs
50#![deny(unsafe_code)]
51#![warn(missing_docs)]
52#![warn(clippy::pedantic)]
53#![warn(clippy::nursery)]
54// Phase 0: Allow dead code and documentation lints for stubs
55#![allow(dead_code)]
56#![allow(clippy::missing_panics_doc)]
57#![allow(clippy::missing_errors_doc)]
58#![allow(clippy::missing_const_for_fn)]
59#![allow(clippy::module_inception)]
60#![allow(clippy::doc_markdown)]
61#![allow(clippy::cast_possible_truncation)]
62#![cfg_attr(test, allow(clippy::large_stack_arrays))]
63// Test harness builds a large test table in one frame.
64#![cfg_attr(test, allow(clippy::large_stack_frames))]
65#![cfg_attr(feature = "simd-intrinsics", feature(portable_simd))]
66
67#[cfg(feature = "quic-compat")]
68compile_error!(
69    "feature `quic-compat` is reserved for legacy quinn-backed adapters and is disabled \
70     in this Tokio-free core build."
71);
72
73#[cfg(feature = "http3-compat")]
74compile_error!(
75    "feature `http3-compat` is reserved for legacy h3/h3-quinn adapters and is disabled \
76     in this Tokio-free core build."
77);
78
79#[cfg(all(
80    target_arch = "wasm32",
81    not(any(
82        feature = "wasm-browser-dev",
83        feature = "wasm-browser-prod",
84        feature = "wasm-browser-deterministic",
85        feature = "wasm-browser-minimal",
86    ))
87))]
88compile_error!(
89    "wasm32 builds require exactly one canonical profile feature: `wasm-browser-dev`, \
90     `wasm-browser-prod`, `wasm-browser-deterministic`, or `wasm-browser-minimal`."
91);
92
93#[cfg(all(
94    target_arch = "wasm32",
95    any(
96        all(feature = "wasm-browser-dev", feature = "wasm-browser-prod"),
97        all(feature = "wasm-browser-dev", feature = "wasm-browser-deterministic"),
98        all(feature = "wasm-browser-dev", feature = "wasm-browser-minimal"),
99        all(feature = "wasm-browser-prod", feature = "wasm-browser-deterministic"),
100        all(feature = "wasm-browser-prod", feature = "wasm-browser-minimal"),
101        all(
102            feature = "wasm-browser-deterministic",
103            feature = "wasm-browser-minimal"
104        ),
105    )
106))]
107compile_error!("wasm32 builds must select exactly one canonical browser profile feature.");
108
109#[cfg(all(target_arch = "wasm32", feature = "native-runtime"))]
110compile_error!("feature `native-runtime` is forbidden on wasm32 browser builds.");
111
112#[cfg(all(
113    target_arch = "wasm32",
114    feature = "wasm-browser-minimal",
115    feature = "browser-io"
116))]
117compile_error!("feature `browser-io` is forbidden with `wasm-browser-minimal`.");
118
119#[cfg(all(
120    target_arch = "wasm32",
121    feature = "wasm-browser-minimal",
122    feature = "browser-trace"
123))]
124compile_error!("feature `browser-trace` is forbidden with `wasm-browser-minimal`.");
125
126#[cfg(all(target_arch = "wasm32", feature = "cli"))]
127compile_error!(
128    "feature `cli` is unsupported on wasm32 (requires native filesystem/process surfaces)."
129);
130
131#[cfg(all(target_arch = "wasm32", feature = "io-uring"))]
132compile_error!("feature `io-uring` is unsupported on wasm32.");
133
134#[cfg(all(target_arch = "wasm32", feature = "tls"))]
135compile_error!("feature `tls` is unsupported on wasm32 browser preview builds.");
136
137#[cfg(all(target_arch = "wasm32", feature = "tls-native-roots"))]
138compile_error!("feature `tls-native-roots` is unsupported on wasm32.");
139
140#[cfg(all(target_arch = "wasm32", feature = "tls-webpki-roots"))]
141compile_error!("feature `tls-webpki-roots` is unsupported on wasm32.");
142
143#[cfg(all(target_arch = "wasm32", feature = "sqlite"))]
144compile_error!("feature `sqlite` is unsupported on wasm32 browser preview builds.");
145
146#[cfg(all(target_arch = "wasm32", feature = "postgres"))]
147compile_error!("feature `postgres` is unsupported on wasm32 browser preview builds.");
148
149#[cfg(all(target_arch = "wasm32", feature = "mysql"))]
150compile_error!("feature `mysql` is unsupported on wasm32 browser preview builds.");
151
152#[cfg(all(target_arch = "wasm32", feature = "kafka"))]
153compile_error!("feature `kafka` is unsupported on wasm32 browser preview builds.");
154
155// ── Portable modules (no platform assumptions) ──────────────────────────
156pub mod actor;
157pub mod app;
158pub mod audit;
159pub mod bytes;
160pub mod cancel;
161pub mod channel;
162pub mod codec;
163pub mod combinator;
164pub mod config;
165pub mod conformance;
166pub mod console;
167pub mod cx;
168pub mod decoding;
169pub mod distributed;
170pub mod encoding;
171pub mod epoch;
172pub mod error;
173pub mod evidence;
174pub mod evidence_sink;
175pub mod gen_server;
176pub mod http;
177pub mod io;
178pub mod lab;
179pub mod link;
180pub mod migration;
181pub mod monitor;
182pub mod net;
183pub mod obligation;
184pub mod observability;
185pub mod plan;
186pub mod raptorq;
187pub mod record;
188pub mod remote;
189pub mod runtime;
190pub mod security;
191pub mod service;
192pub mod session;
193pub mod spork;
194pub mod stream;
195pub mod supervision;
196pub mod sync;
197pub mod time;
198pub mod trace;
199pub mod tracing_compat;
200pub mod transport;
201pub mod types;
202pub mod util;
203pub mod web;
204
205// ── Feature-gated modules ───────────────────────────────────────────────
206#[cfg(feature = "cli")]
207pub mod cli;
208#[cfg(any(feature = "sqlite", feature = "postgres", feature = "mysql"))]
209pub mod database;
210#[cfg(feature = "tls")]
211pub mod tls;
212
213// ── Platform-specific modules (excluded from wasm32 browser builds) ─────
214// These modules depend on native OS surfaces (libc, nix, epoll, signal-hook,
215// socket2) that are unavailable on wasm32-unknown-unknown. Browser adapters
216// for the portable modules above are provided via platform trait seams
217// (see docs/wasm_platform_trait_seams.md).
218#[cfg(not(target_arch = "wasm32"))]
219pub mod fs;
220#[cfg(not(target_arch = "wasm32"))]
221pub mod grpc;
222#[cfg(all(not(target_arch = "wasm32"), feature = "kafka"))]
223pub mod messaging;
224#[cfg(unix)]
225pub mod process;
226#[cfg(not(target_arch = "wasm32"))]
227pub mod server;
228#[cfg(not(target_arch = "wasm32"))]
229pub mod signal;
230
231// ── Test-only modules ───────────────────────────────────────────────────
232#[cfg(any(test, feature = "test-internals"))]
233pub mod test_logging;
234#[cfg(any(test, feature = "test-internals"))]
235pub mod test_ndjson;
236#[cfg(any(test, feature = "test-internals"))]
237pub mod test_utils;
238
239// Re-exports for convenient access to core types
240pub use config::{
241    AdaptiveConfig, BackoffConfig, ConfigError, ConfigLoader, EncodingConfig,
242    PathSelectionStrategy, RaptorQConfig, ResourceConfig, RuntimeProfile, SecurityConfig,
243    TimeoutConfig, TransportConfig,
244};
245pub use cx::{Cx, Scope};
246pub use decoding::{
247    DecodingConfig, DecodingError, DecodingPipeline, DecodingProgress, RejectReason,
248    SymbolAcceptResult,
249};
250pub use encoding::{EncodedSymbol, EncodingError, EncodingPipeline, EncodingStats};
251pub use epoch::{
252    BarrierResult, BarrierTrigger, Epoch, EpochBarrier, EpochBulkheadError,
253    EpochCircuitBreakerError, EpochClock, EpochConfig, EpochContext, EpochError, EpochId,
254    EpochJoin2, EpochPolicy, EpochRace2, EpochScoped, EpochSelect, EpochSource, EpochState,
255    EpochTransitionBehavior, SymbolValidityWindow, bulkhead_call_in_epoch,
256    bulkhead_call_weighted_in_epoch, circuit_breaker_call_in_epoch, epoch_join2, epoch_race2,
257    epoch_select,
258};
259pub use error::{
260    AcquireError, BackoffHint, Error, ErrorCategory, ErrorKind, Recoverability, RecoveryAction,
261    RecvError, Result, ResultExt, SendError,
262};
263pub use lab::{LabConfig, LabRuntime};
264pub use remote::{
265    CancelRequest, CompensationResult, ComputationName, DedupDecision, IdempotencyKey,
266    IdempotencyRecord, IdempotencyStore, Lease, LeaseError, LeaseRenewal, LeaseState, NodeId,
267    RemoteCap, RemoteError, RemoteHandle, RemoteMessage, RemoteOutcome, RemoteTaskId,
268    ResultDelivery, Saga, SagaState, SagaStepError, SpawnAck, SpawnAckStatus, SpawnRejectReason,
269    SpawnRequest, spawn_remote,
270};
271pub use types::{
272    Budget, CancelKind, CancelReason, NextjsBootstrapPhase, NextjsIntegrationSnapshot,
273    NextjsNavigationType, NextjsRenderEnvironment, ObligationId, Outcome, OutcomeError,
274    PanicPayload, Policy, ProgressiveLoadSlot, ProgressiveLoadSnapshot, ReactProviderConfig,
275    ReactProviderPhase, ReactProviderState, RegionId, Severity, SuspenseBoundaryState,
276    SuspenseDiagnosticEvent, SuspenseTaskConfig, SuspenseTaskSnapshot, SystemPressure, TaskId,
277    Time, TransitionTaskState, WASM_ABI_MAJOR_VERSION, WASM_ABI_MINOR_VERSION,
278    WASM_ABI_SIGNATURE_FINGERPRINT_V1, WASM_ABI_SIGNATURES_V1, WasmAbiBoundaryEvent,
279    WasmAbiCancellation, WasmAbiChangeClass, WasmAbiCompatibilityDecision, WasmAbiErrorCode,
280    WasmAbiFailure, WasmAbiOutcomeEnvelope, WasmAbiPayloadShape, WasmAbiRecoverability,
281    WasmAbiSignature, WasmAbiSymbol, WasmAbiValue, WasmAbiVersion, WasmAbiVersionBump,
282    WasmAbortInteropSnapshot, WasmAbortInteropUpdate, WasmAbortPropagationMode, WasmBoundaryState,
283    WasmBoundaryTransitionError, WasmExportDispatcher, WasmHandleKind, WasmHandleRef,
284    WasmOutcomeExt, WasmTaskCancelRequest, WasmTaskSpawnBuilder, apply_abort_signal_event,
285    apply_runtime_cancel_phase_event, classify_wasm_abi_compatibility,
286    is_valid_bootstrap_transition, is_valid_wasm_boundary_transition, join_outcomes,
287    outcome_to_error_boundary_action, outcome_to_suspense_state, outcome_to_transition_state,
288    required_wasm_abi_bump, validate_wasm_boundary_transition, wasm_abi_signature_fingerprint,
289    wasm_boundary_state_for_cancel_phase,
290};
291
292// Re-export proc macros when the proc-macros feature is enabled
293// Note: join! and race! are not re-exported because they conflict with the
294// existing macro_rules! definitions in combinator/. The proc macro versions
295// will replace those in future tasks (asupersync-mwff, asupersync-hcpl).
296#[cfg(feature = "proc-macros")]
297pub use asupersync_macros::{join_all, scope, spawn};
298
299// Proc macro versions available with explicit path when needed
300#[cfg(feature = "proc-macros")]
301pub mod proc_macros {
302    //! Proc macro versions of structured concurrency macros.
303    //!
304    //! These are provided for explicit access when the macro_rules! versions
305    //! are also in scope.
306    pub use asupersync_macros::{join, join_all, race, scope, session_protocol, spawn};
307}
asupersync/lib.rs

asupersync/
lib.rs
