aardvark_core/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! Aardvark is an embeddable multi-language runtime for executing sandboxed bundles inside V8.
4//!
5//! The crate targets host services that need a predictable, resource-constrained way to run
6//! guest code without shipping a full browser. It currently supports Python (via Pyodide)
7//! and an experimental JavaScript engine. It exposes:
8//!
9//! * [`PyRuntime`] – a single-tenant runtime that prepares bundles, enforces
10//!   resource limits, and surfaces structured outcomes.
11//! * [`PyRuntimePool`] – a reset-aware pool for amortising Pyodide startup cost.
12//! * [`Bundle`] and [`BundleManifest`] helpers for normalising user-provided ZIP
13//!   archives and their manifest metadata.
14//! * [`InvocationDescriptor`] – a host-controlled contract describing inputs,
15//!   outputs, and budgets for individual invocations.
16//! * [`ExecutionOutcome`] and [`SandboxTelemetry`] – diagnostics tailored for
17//!   observability pipelines.
18//!
19//! ### Quick Example
20//!
21//! ```no_run
22//! use aardvark_core::{Bundle, PyRuntime, PyRuntimeConfig};
23//!
24//! fn invoke(bytes: &[u8]) -> anyhow::Result<()> {
25//!     let mut runtime = PyRuntime::new(PyRuntimeConfig::default())?;
26//!     let bundle = Bundle::from_zip_bytes(bytes)?;
27//!     let (session, _manifest) = runtime.prepare_session_with_manifest(bundle)?;
28//!     let outcome = runtime.run_session(&session)?;
29//!     if let Some(payload) = outcome.payload() {
30//!         println!("payload kind: {}", payload.kind());
31//!     }
32//!     if outcome.sandbox_telemetry().has_policy_violations() {
33//!         eprintln!("invocation tripped sandbox policy");
34//!     }
35//!     Ok(())
36//! }
37//! ```
38//!
39//! See the `docs/architecture` and `docs/api` directories in the repository for
40//! a deeper discussion of the runtime design, manifest schema, and integration
41//! patterns.
42
43mod asset_store;
44pub mod assets;
45pub mod bundle;
46mod bundle_manifest;
47pub mod config;
48pub mod error;
49pub mod host;
50pub mod invocation;
51pub mod outcome;
52mod package_metadata;
53pub mod persistent;
54pub mod pool;
55pub mod pyodide;
56pub mod runtime;
57mod runtime_language;
58pub mod strategy;
59
60mod engine;
61mod session;
62
63pub use bundle::{Bundle, BundleFingerprint};
64pub use bundle_manifest::{
65    BundleManifest, ManifestCpuResources, ManifestFilesystemMode, ManifestFilesystemResources,
66    ManifestNetworkResources, ManifestPyodide, ManifestResources, ManifestRuntime,
67    MANIFEST_BASENAME as BUNDLE_MANIFEST_BASENAME, MANIFEST_SCHEMA as BUNDLE_MANIFEST_SCHEMA,
68    MANIFEST_SCHEMA_VERSION as BUNDLE_MANIFEST_SCHEMA_VERSION,
69};
70pub use config::{HostHooks, PyRuntimeConfig, WarmHook, WarmState};
71pub use engine::{ExecutionOutput, OverlayBlob, OverlayExport};
72pub use error::{PyRunnerError, Result};
73pub use host::{
74    FilesystemTelemetry, MemoryTelemetry, NetworkTelemetry, PoolTelemetry, SandboxTelemetry,
75};
76pub use invocation::{FieldDescriptor, InvocationDescriptor, InvocationLimits, WindowConfig};
77pub use outcome::{
78    Diagnostics, ExecutionOutcome, FailureKind, OutcomeStatus, ResultPayload, SharedBufferHandle,
79};
80pub use persistent::{
81    BundleArtifact, BundleHandle, BundlePool, CleanupMode, HandlerSession, InlinePythonOptions,
82    IsolateConfig, PoolOptions, PoolStats, PythonIsolate, QueueMode,
83};
84pub use pool::{PoolConfig, PyRuntimePool};
85pub use runtime::PyRuntime;
86pub use runtime_language::RuntimeLanguage;
87pub use session::PySession;
88pub use strategy::{
89    DefaultInvocationStrategy, JavaScriptInvocationStrategy, JsonInvocationStrategy,
90    PyInvocationStrategy, RawCtxBindingBuilder, RawCtxInput, RawCtxInvocationStrategy,
91    RawCtxMetadata, RawCtxPublishBuilder, RawCtxTableColumnBuilder, RawCtxTableSpec,
92    RawCtxTableSpecBuilder,
93};
aardvark_core/lib.rs

aardvark_core/
lib.rs
