Skip to main content

warpline_core/
runtime.rs

1//! The [`Runtime`] facade: the one type an embedding app holds.
2//!
3//! A `Runtime` owns the wasmtime engine and linker, the epoch ticker that
4//! enforces CPU budgets, the on-disk module registry (content-addressed
5//! `.wasm`/`.cwasm` blobs plus one pointer file per `(tenant, func)`), the
6//! in-memory component cache, and admission control. It is cheap to clone
7//! (an `Arc`); clones share everything, and the ticker stops only when the
8//! last clone, including those held by in-flight invocations, is gone.
9
10use std::collections::HashMap;
11use std::path::PathBuf;
12use std::sync::atomic::{AtomicU64, Ordering};
13use std::sync::{Arc, Mutex};
14use std::time::{Duration, Instant};
15
16use bytes::Bytes;
17use tokio::sync::Semaphore;
18use wasmtime::component::Linker;
19use wasmtime::Engine;
20
21use crate::cache;
22use crate::kv::{KvStore, MemKv};
23use crate::registry::{self, ComponentCache, Loaded, Lookup};
24use crate::sandbox::{self, EpochTicker, Failure};
25use crate::types::{valid_name, HostCtx};
26use crate::{Error, InvokeError, Limits, MeterSink, PublishError, Usage};
27
28const MIB: usize = 1024 * 1024;
29
30/// Configuration for a [`Runtime`]. Build with [`RuntimeConfig::new`] and
31/// adjust the public fields; new fields may be added in minor releases.
32#[derive(Debug, Clone)]
33#[non_exhaustive]
34pub struct RuntimeConfig {
35    /// Root of the module registry. Created if missing.
36    ///
37    /// # Trust
38    ///
39    /// Everything under `modules_dir/cwasm` is deserialized as native
40    /// machine code and executed. Anyone who can write there can run
41    /// arbitrary code as the host process, so the directory (and its
42    /// parents) must be writable only by the host process and trusted
43    /// operators, never by tenants or shared with less-trusted services.
44    pub modules_dir: PathBuf,
45    /// Let guests' `http-out` reach loopback/private/link-local addresses.
46    /// One flag drives both the DNS resolver filter and the IP-literal check.
47    /// Default `false`; enable only for local development and tests.
48    pub allow_private_egress: bool,
49    /// Total guest memory admitted concurrently, in bytes (default 1 GiB).
50    /// Each invocation weighs its `Limits::mem_cap_bytes` rounded up to whole
51    /// MiB; when the running total would exceed this, the invocation fails
52    /// fast with [`InvokeError::Overloaded`]. At least 1 MiB.
53    pub memory_budget_bytes: usize,
54    /// Invocations one tenant may have in flight (default 32); beyond that
55    /// [`InvokeError::TenantBusy`]. At least 1.
56    pub max_in_flight_per_tenant: usize,
57    /// Largest output an invocation may return, bytes (default 8 MiB).
58    pub max_output_bytes: usize,
59    /// Components kept loaded in memory (default 256). At least 1.
60    pub component_cache_entries: usize,
61    /// Serialized bytes of loaded components kept in memory (default 512 MiB).
62    pub component_cache_bytes: usize,
63    /// Concurrent compilations in [`Runtime::stage`] (default half the cores,
64    /// at least 1).
65    pub compile_concurrency: usize,
66}
67
68impl RuntimeConfig {
69    /// Defaults everywhere except the registry location.
70    pub fn new(modules_dir: impl Into<PathBuf>) -> Self {
71        let cores = std::thread::available_parallelism().map_or(1, |n| n.get());
72        Self {
73            modules_dir: modules_dir.into(),
74            allow_private_egress: false,
75            memory_budget_bytes: 1024 * MIB,
76            max_in_flight_per_tenant: 32,
77            max_output_bytes: 8 * MIB,
78            component_cache_entries: 256,
79            component_cache_bytes: 512 * MIB,
80            compile_concurrency: (cores / 2).max(1),
81        }
82    }
83}
84
85/// Builder for a [`Runtime`] with a custom KV store and/or meter.
86#[must_use]
87pub struct RuntimeBuilder {
88    cfg: RuntimeConfig,
89    kv: Option<Arc<dyn KvStore>>,
90    meter: Option<Arc<dyn MeterSink>>,
91}
92
93impl RuntimeBuilder {
94    /// Back guests' `kv` capability with `kv` (default: a fresh [`MemKv`]).
95    pub fn kv(mut self, kv: Arc<dyn KvStore>) -> Self {
96        self.kv = Some(kv);
97        self
98    }
99
100    /// Report every invocation that reached the guest to `sink` (default:
101    /// none).
102    pub fn meter(mut self, sink: Arc<dyn MeterSink>) -> Self {
103        self.meter = Some(sink);
104        self
105    }
106
107    /// Validate the config, create the registry directory and start the
108    /// epoch ticker. Synchronous; only the async methods need a tokio runtime.
109    pub fn build(self) -> Result<Runtime, Error> {
110        let cfg = self.cfg;
111        if cfg.memory_budget_bytes < MIB {
112            return Err(Error::Config("memory_budget_bytes must be at least 1 MiB"));
113        }
114        if cfg.max_in_flight_per_tenant == 0 {
115            return Err(Error::Config("max_in_flight_per_tenant must be at least 1"));
116        }
117        if cfg.component_cache_entries == 0 {
118            return Err(Error::Config("component_cache_entries must be at least 1"));
119        }
120        if cfg.compile_concurrency == 0 {
121            return Err(Error::Config("compile_concurrency must be at least 1"));
122        }
123        std::fs::create_dir_all(&cfg.modules_dir)?;
124
125        let engine = sandbox::build_engine()?;
126        let linker = Arc::new(sandbox::build_linker(&engine)?);
127        let http_client = sandbox::build_http_client(cfg.allow_private_egress)
128            .map_err(|e| Error::Internal(format!("failed to build http client: {e}")))?;
129        let components = ComponentCache::new(
130            engine.clone(),
131            linker.clone(),
132            cfg.modules_dir.clone(),
133            cfg.component_cache_entries,
134            cfg.component_cache_bytes,
135        );
136        let ticker = EpochTicker::spawn(engine.clone())?;
137        Ok(Runtime(Arc::new(Inner {
138            admission: Arc::new(Semaphore::new(cfg.memory_budget_bytes / MIB)),
139            compile_slots: Arc::new(Semaphore::new(cfg.compile_concurrency)),
140            in_flight: Mutex::new(HashMap::new()),
141            kv: self.kv.unwrap_or_else(|| Arc::new(MemKv::new())),
142            meter: self.meter,
143            http_client,
144            components,
145            linker,
146            engine,
147            cfg,
148            _ticker: ticker,
149        })))
150    }
151}
152
153impl std::fmt::Debug for RuntimeBuilder {
154    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
155        f.debug_struct("RuntimeBuilder")
156            .field("cfg", &self.cfg)
157            .field("custom_kv", &self.kv.is_some())
158            .field("meter", &self.meter.is_some())
159            .finish()
160    }
161}
162
163struct Inner {
164    cfg: RuntimeConfig,
165    engine: Engine,
166    linker: Arc<Linker<HostCtx>>,
167    kv: Arc<dyn KvStore>,
168    meter: Option<Arc<dyn MeterSink>>,
169    http_client: reqwest::Client,
170    components: ComponentCache,
171    /// Permits are MiB of guest memory.
172    admission: Arc<Semaphore>,
173    in_flight: Mutex<HashMap<String, usize>>,
174    compile_slots: Arc<Semaphore>,
175    /// Stops (and joins) the epoch thread when the last `Arc<Inner>` goes.
176    _ticker: EpochTicker,
177}
178
179/// A multi-tenant WebAssembly function runtime.
180///
181/// Publish a component under `(tenant, function)`, then invoke it with
182/// per-call [`Limits`]. Cheap to clone; clones share all state.
183///
184/// Guests implement the [`handler` world](https://github.com/Bunty9/warpline/blob/main/crates/core/wit/warpline.wit).
185///
186/// ```
187/// use std::sync::Arc;
188/// use warpline_core::{Bytes, Limits, MemKv, Runtime, RuntimeConfig};
189///
190/// # #[tokio::main]
191/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
192/// # let dir = tempfile::tempdir()?;
193/// let runtime = Runtime::builder(RuntimeConfig::new(dir.path()))
194///     .kv(Arc::new(MemKv::new()))
195///     .build()?;
196///
197/// // Build one with any component toolchain, e.g. a Rust guest with
198/// // `cargo build --target wasm32-wasip2 --release`; `examples/storefront`
199/// // has a complete one. The doctest uses an echo guest from the test suite.
200/// # #[cfg(any())]
201/// let wasm = std::fs::read("hello_wasm.wasm")?;
202/// # let wasm = include_bytes!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/test_guest.wasm")).to_vec();
203/// runtime.publish("acme", "hello", Bytes::from(wasm)).await?;
204///
205/// let limits = Limits::new(50, 32 << 20)?;
206/// let out = runtime.invoke("acme", "hello", b"hi".to_vec(), &limits).await?;
207/// assert_eq!(out.output, b"hi");
208/// println!("{} bytes back, {} us cpu", out.output.len(), out.usage.cpu_us);
209/// # Ok(())
210/// # }
211/// ```
212///
213/// # Trust
214///
215/// The registry directory ([`RuntimeConfig::modules_dir`]) holds native code
216/// (`cwasm/`) that is loaded without further checks. Keep it writable only
217/// by the host process and trusted operators.
218///
219/// # Capacity
220///
221/// `invoke` is fail-fast: it never queues. A tenant beyond its in-flight
222/// cap gets [`InvokeError::TenantBusy`] and an invocation the memory budget
223/// cannot admit gets [`InvokeError::Overloaded`]; map those to 429/503 (see
224/// [`InvokeError::http_status`]) and let the caller retry.
225#[derive(Clone)]
226pub struct Runtime(Arc<Inner>);
227
228/// A component that has been compiled, type-checked and persisted, but is not
229/// yet reachable by any function name. See [`Runtime::stage`].
230#[derive(Debug, Clone, PartialEq, Eq)]
231#[non_exhaustive]
232pub struct Staged {
233    /// Hex SHA-256 of the component bytes; also [`digest`](crate::digest).
234    pub digest: String,
235}
236
237/// A successful invocation.
238#[derive(Debug, Clone)]
239#[non_exhaustive]
240pub struct Invocation {
241    /// The bytes the guest returned.
242    pub output: Vec<u8>,
243    /// What the call used. `cpu_us` has 1 ms granularity.
244    pub usage: Usage,
245}
246
247impl Runtime {
248    /// A runtime with an in-memory KV store and no meter.
249    pub fn new(cfg: RuntimeConfig) -> Result<Self, Error> {
250        Self::builder(cfg).build()
251    }
252
253    /// Start building a runtime with a custom KV store and/or meter.
254    pub fn builder(cfg: RuntimeConfig) -> RuntimeBuilder {
255        RuntimeBuilder {
256            cfg,
257            kv: None,
258            meter: None,
259        }
260    }
261
262    /// The wasmtime engine (the same version as [`crate::wasmtime`]), e.g.
263    /// to compile components ahead of time with matching settings.
264    pub fn engine(&self) -> &Engine {
265        &self.0.engine
266    }
267
268    /// Compile `wasm`, check it fits the handler world and persist it, without
269    /// making it reachable. Compilation runs on the blocking pool behind the
270    /// `compile_concurrency` semaphore. Idempotent: re-staging identical bytes
271    /// refreshes their timestamps so a concurrent [`gc`](Self::gc) leaves them
272    /// for the [`activate`](Self::activate) that follows.
273    ///
274    /// Split from [`activate`](Self::activate) so a caller can do its own
275    /// bookkeeping (a quota check, a database row) between the two.
276    pub async fn stage(&self, wasm: Bytes) -> Result<Staged, PublishError> {
277        let inner = self.0.clone();
278        let permit = inner
279            .compile_slots
280            .clone()
281            .acquire_owned()
282            .await
283            .map_err(|_| {
284                PublishError::Registry(Error::Internal("compile semaphore closed".into()))
285            })?;
286        tokio::task::spawn_blocking(move || {
287            let _permit = permit;
288            let modules_dir = &inner.cfg.modules_dir;
289            let cwasm_dir = registry::cwasm_dir(modules_dir);
290            let (component, digest, fresh) = cache::compile(&inner.engine, &wasm, &cwasm_dir)
291                .map_err(|e| match e {
292                    Error::Wasmtime(e) => PublishError::Compile(e),
293                    other => into_publish_err(other),
294                })?;
295            sandbox::typecheck_component(&inner.linker, &component)
296                .map_err(PublishError::ImportMismatch)?;
297            // Only a typechecked component is persisted.
298            if fresh {
299                cache::persist_cwasm(&component, &inner.engine, &cwasm_dir, &digest)
300                    .map_err(into_publish_err)?;
301            } else if let Err(e) =
302                registry::touch(&cwasm_dir.join(cache::cache_file_name(&inner.engine, &digest)))
303            {
304                tracing::warn!(%digest, error = %e, "could not refresh .cwasm mtime");
305            }
306            registry::write_wasm_source(modules_dir, &digest, &wasm).map_err(into_publish_err)?;
307            Ok(Staged { digest })
308        })
309        .await
310        .map_err(|e| PublishError::Registry(Error::Internal(format!("stage task failed: {e}"))))?
311    }
312
313    /// Atomically point `(tenant, func)` at `staged`. Invocations that start
314    /// afterwards run the new component; ones already running are unaffected.
315    pub async fn activate(
316        &self,
317        tenant: &str,
318        func: &str,
319        staged: &Staged,
320    ) -> Result<(), PublishError> {
321        if !valid_name(tenant) || !valid_name(func) {
322            return Err(PublishError::InvalidName);
323        }
324        let inner = self.0.clone();
325        let (tenant, func, digest) = (tenant.to_owned(), func.to_owned(), staged.digest.clone());
326        tokio::task::spawn_blocking(move || {
327            registry::write_pointer(&inner.cfg.modules_dir, &tenant, &func, &digest)
328        })
329        .await
330        .map_err(|e| PublishError::Registry(Error::Internal(format!("activate task failed: {e}"))))?
331        .map_err(into_publish_err)
332    }
333
334    /// The component `(tenant, func)` currently points at, if any. Lets a
335    /// caller that activates inside its own transaction remember what to
336    /// [`activate`](Self::activate) again (or [`deactivate`](Self::deactivate)
337    /// if `None`) when the transaction fails to commit.
338    pub async fn active(&self, tenant: &str, func: &str) -> Result<Option<Staged>, PublishError> {
339        if !valid_name(tenant) || !valid_name(func) {
340            return Err(PublishError::InvalidName);
341        }
342        let inner = self.0.clone();
343        let (tenant, func) = (tenant.to_owned(), func.to_owned());
344        let digest = tokio::task::spawn_blocking(move || {
345            registry::read_pointer(&inner.cfg.modules_dir, &tenant, &func)
346        })
347        .await
348        .map_err(|e| PublishError::Registry(Error::Internal(format!("active task failed: {e}"))))?
349        .map_err(into_publish_err)?;
350        Ok(digest.map(|digest| Staged { digest }))
351    }
352
353    /// Remove the `(tenant, func)` pointer, so invocations get
354    /// [`NotFound`](InvokeError::NotFound). Idempotent. The blobs stay until
355    /// [`gc`](Self::gc) collects them.
356    pub async fn deactivate(&self, tenant: &str, func: &str) -> Result<(), PublishError> {
357        if !valid_name(tenant) || !valid_name(func) {
358            return Err(PublishError::InvalidName);
359        }
360        let inner = self.0.clone();
361        let (tenant, func) = (tenant.to_owned(), func.to_owned());
362        tokio::task::spawn_blocking(move || {
363            registry::remove_pointer(&inner.cfg.modules_dir, &tenant, &func)
364        })
365        .await
366        .map_err(|e| {
367            PublishError::Registry(Error::Internal(format!("deactivate task failed: {e}")))
368        })?
369        .map_err(into_publish_err)
370    }
371
372    /// Point `(tenant, func)` at a component that was staged earlier, given
373    /// only its digest (e.g. read back from a database row). Errors if no
374    /// source blob for `digest` exists ([`Error::NotFound`] inside
375    /// [`PublishError::Registry`]), the digest is malformed, or a name is
376    /// invalid ([`PublishError::InvalidName`]).
377    pub async fn activate_digest(
378        &self,
379        tenant: &str,
380        func: &str,
381        digest: &str,
382    ) -> Result<(), PublishError> {
383        if !valid_name(tenant) || !valid_name(func) {
384            return Err(PublishError::InvalidName);
385        }
386        if !cache::is_valid_digest(digest) {
387            return Err(PublishError::Registry(Error::Corrupt(
388                "invalid digest: expected 64 lowercase hex characters".into(),
389            )));
390        }
391        if !registry::wasm_exists(&self.0.cfg.modules_dir, digest) {
392            return Err(PublishError::Registry(Error::NotFound(format!(
393                "no staged component with digest {digest}"
394            ))));
395        }
396        self.activate(
397            tenant,
398            func,
399            &Staged {
400                digest: digest.to_owned(),
401            },
402        )
403        .await
404    }
405
406    /// [`stage`](Self::stage) then [`activate`](Self::activate).
407    pub async fn publish(
408        &self,
409        tenant: &str,
410        func: &str,
411        wasm: Bytes,
412    ) -> Result<Staged, PublishError> {
413        if !valid_name(tenant) || !valid_name(func) {
414            return Err(PublishError::InvalidName);
415        }
416        let staged = self.stage(wasm).await?;
417        self.activate(tenant, func, &staged).await?;
418        Ok(staged)
419    }
420
421    /// Run `(tenant, func)` on `input` under `limits`.
422    ///
423    /// Fails fast, in this order: [`InvalidName`](InvokeError::InvalidName),
424    /// [`InvalidLimits`](InvokeError::InvalidLimits),
425    /// [`TenantBusy`](InvokeError::TenantBusy),
426    /// [`Overloaded`](InvokeError::Overloaded),
427    /// [`NotFound`](InvokeError::NotFound). Once the guest has started, the
428    /// configured [`MeterSink`] is called exactly once with the outcome,
429    /// including when the returned future is dropped mid-call (then as a
430    /// failure). The tenant's in-flight slot and the memory admission are
431    /// released on every exit path.
432    ///
433    /// Admission is taken *before* the module is loaded and held through it,
434    /// so a burst of cold invocations (first use, or after an engine upgrade
435    /// forces recompiles) occupies budget while loading and can see
436    /// [`Overloaded`](InvokeError::Overloaded).
437    pub async fn invoke(
438        &self,
439        tenant: &str,
440        func: &str,
441        input: Vec<u8>,
442        limits: &Limits,
443    ) -> Result<Invocation, InvokeError> {
444        if !valid_name(tenant) || !valid_name(func) {
445            return Err(InvokeError::InvalidName);
446        }
447        validate_limits(limits)?;
448        // Held for the whole call: keeps the ticker alive even if every
449        // other `Runtime` handle is dropped meanwhile.
450        let inner = self.0.clone();
451
452        let _slot = TenantSlot::acquire(&inner, tenant).ok_or(InvokeError::TenantBusy)?;
453
454        let weight = limits.mem_cap_bytes.div_ceil(MIB).max(1);
455        let weight = u32::try_from(weight)
456            .ok()
457            .filter(|w| (*w as usize) <= inner.cfg.memory_budget_bytes / MIB)
458            .ok_or(InvokeError::Overloaded)?;
459        let _admission = inner
460            .admission
461            .clone()
462            .try_acquire_many_owned(weight)
463            .map_err(|_| InvokeError::Overloaded)?;
464
465        let pre = {
466            let lookup = {
467                let inner = inner.clone();
468                let (t, f) = (tenant.to_owned(), func.to_owned());
469                tokio::task::spawn_blocking(move || inner.components.lookup(&t, &f))
470                    .await
471                    .map_err(|e| {
472                        InvokeError::Load(Error::Internal(format!("resolve task failed: {e}")))
473                    })?
474                    .map_err(InvokeError::Load)?
475            };
476            match lookup {
477                Lookup::NotFound => return Err(InvokeError::NotFound),
478                Lookup::Hit(pre) => pre,
479                Lookup::Miss(digest) => {
480                    // Cheap path first, with no permit: deserialise the
481                    // `.cwasm` on disk. Only when it needs a real compile do
482                    // we queue for one, so a restart does not serialise cold
483                    // loads behind in-flight stages.
484                    let loaded = {
485                        let (inner, digest) = (inner.clone(), digest.clone());
486                        tokio::task::spawn_blocking(move || inner.components.load_existing(&digest))
487                            .await
488                            .map_err(|e| {
489                                InvokeError::Load(Error::Internal(format!("load task failed: {e}")))
490                            })?
491                            .map_err(InvokeError::Load)?
492                    };
493                    match loaded {
494                        Loaded::Ready(pre) => pre,
495                        Loaded::NeedsCompile => {
496                            // The permit is taken here, asynchronously, and
497                            // moved into the blocking task: a blocking thread
498                            // must never wait for a permit, or a burst of
499                            // misses could park the whole blocking pool while
500                            // the permit holders (stages) wait for a thread.
501                            let permit =
502                                inner.compile_slots.clone().acquire_owned().await.map_err(
503                                    |_| {
504                                        InvokeError::Load(Error::Internal(
505                                            "compile semaphore closed".into(),
506                                        ))
507                                    },
508                                )?;
509                            let inner = inner.clone();
510                            tokio::task::spawn_blocking(move || {
511                                let _permit = permit;
512                                inner.components.get_or_load(&digest)
513                            })
514                            .await
515                            .map_err(|e| {
516                                InvokeError::Load(Error::Internal(format!(
517                                    "recompile task failed: {e}"
518                                )))
519                            })?
520                            .map_err(InvokeError::Load)?
521                        }
522                    }
523                }
524            }
525        };
526
527        let ctx = HostCtx::new(
528            tenant.to_owned(),
529            func.to_owned(),
530            inner.kv.clone(),
531            limits.allowed_hosts.clone(),
532            inner.cfg.allow_private_egress,
533            inner.http_client.clone(),
534            limits.mem_cap_bytes,
535        );
536
537        let ticks = Arc::new(AtomicU64::new(0));
538        let started = Instant::now();
539        let mut meter = MeterGuard {
540            sink: inner.meter.as_deref(),
541            tenant,
542            func,
543            ticks: &ticks,
544            started,
545            done: false,
546        };
547
548        let run = sandbox::run(&pre, ctx, &input, limits.cpu_budget_ms, ticks.clone()).await;
549        let usage = Usage::new(
550            ticks.load(Ordering::Relaxed) * (sandbox::EPOCH_TICK_MS * 1000),
551            started.elapsed().as_micros() as u64,
552            run.mem_peak,
553        );
554        let limit = inner.cfg.max_output_bytes;
555        let result = match run.result {
556            Ok(output) if output.len() > limit => Err(InvokeError::OutputTooLarge { usage, limit }),
557            Ok(output) => Ok(Invocation { output, usage }),
558            Err(Failure::CpuBudget) => Err(InvokeError::CpuBudgetExceeded {
559                usage,
560                budget_ms: limits.cpu_budget_ms,
561            }),
562            Err(Failure::MemCap { cap_bytes }) => {
563                Err(InvokeError::MemoryCapExceeded { usage, cap_bytes })
564            }
565            Err(Failure::WallClock) => Err(InvokeError::WallClockTimeout { usage }),
566            Err(Failure::Trap(source)) => Err(InvokeError::GuestTrap { usage, source }),
567        };
568        meter.finish(usage, result.is_ok());
569        result
570    }
571
572    /// Delete blobs no pointer references (and `.cwasm` files compiled by a
573    /// different engine), skipping anything modified within `grace`. Returns
574    /// the number of files removed. Errors out before deleting anything if a
575    /// pointer file cannot be read. Run it at startup, with
576    /// [`GC_GRACE_PERIOD`](crate::GC_GRACE_PERIOD) as `grace`.
577    pub async fn gc(&self, grace: Duration) -> Result<usize, Error> {
578        let inner = self.0.clone();
579        tokio::task::spawn_blocking(move || {
580            registry::gc_unreferenced_blobs(&inner.cfg.modules_dir, &inner.engine, grace)
581        })
582        .await
583        .map_err(|e| Error::Internal(format!("gc task failed: {e}")))?
584    }
585}
586
587impl std::fmt::Debug for Runtime {
588    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
589        f.debug_struct("Runtime")
590            .field("modules_dir", &self.0.cfg.modules_dir)
591            .finish_non_exhaustive()
592    }
593}
594
595/// Re-check what `Limits::new` enforces; the fields are public, so a caller
596/// may have mutated them out of range since.
597fn validate_limits(l: &Limits) -> Result<(), crate::ConfigError> {
598    use crate::types::{validate_cpu_budget_ms, validate_mem_cap_bytes};
599    validate_cpu_budget_ms(i64::try_from(l.cpu_budget_ms).unwrap_or(i64::MAX))?;
600    validate_mem_cap_bytes(i64::try_from(l.mem_cap_bytes).unwrap_or(i64::MAX))
601}
602
603fn into_publish_err(e: Error) -> PublishError {
604    match e {
605        Error::Io(e) => PublishError::Io(e),
606        other => PublishError::Registry(other),
607    }
608}
609
610/// RAII in-flight counter for one tenant; released on every exit path.
611struct TenantSlot {
612    inner: Arc<Inner>,
613    tenant: String,
614}
615
616impl TenantSlot {
617    fn acquire(inner: &Arc<Inner>, tenant: &str) -> Option<Self> {
618        let mut map = inner.in_flight.lock().unwrap_or_else(|p| p.into_inner());
619        match map.get_mut(tenant) {
620            Some(n) if *n >= inner.cfg.max_in_flight_per_tenant => return None,
621            Some(n) => *n += 1,
622            None => {
623                map.insert(tenant.to_owned(), 1);
624            }
625        }
626        Some(Self {
627            inner: inner.clone(),
628            tenant: tenant.to_owned(),
629        })
630    }
631}
632
633impl Drop for TenantSlot {
634    fn drop(&mut self) {
635        let mut map = self
636            .inner
637            .in_flight
638            .lock()
639            .unwrap_or_else(|p| p.into_inner());
640        if let Some(n) = map.get_mut(&self.tenant) {
641            *n -= 1;
642            if *n == 0 {
643                map.remove(&self.tenant);
644            }
645        }
646    }
647}
648
649/// Reports to the meter exactly once: explicitly via [`finish`](Self::finish),
650/// or from `Drop` (as a failure, with the ticks counted so far) if the
651/// invocation future was cancelled mid-call, so cancelling cannot make CPU
652/// use free.
653struct MeterGuard<'a> {
654    sink: Option<&'a dyn MeterSink>,
655    tenant: &'a str,
656    func: &'a str,
657    ticks: &'a AtomicU64,
658    started: Instant,
659    done: bool,
660}
661
662impl MeterGuard<'_> {
663    fn finish(&mut self, usage: Usage, ok: bool) {
664        self.done = true;
665        if let Some(sink) = self.sink {
666            sink.record(self.tenant, self.func, usage, ok);
667        }
668    }
669}
670
671impl Drop for MeterGuard<'_> {
672    fn drop(&mut self) {
673        if self.done {
674            return;
675        }
676        if let Some(sink) = self.sink {
677            let usage = Usage::new(
678                self.ticks.load(Ordering::Relaxed) * (sandbox::EPOCH_TICK_MS * 1000),
679                self.started.elapsed().as_micros() as u64,
680                0,
681            );
682            sink.record(self.tenant, self.func, usage, false);
683        }
684    }
685}
686
687#[cfg(test)]
688mod tests {
689    use super::*;
690
691    const TEST_GUEST_WASM: &[u8] = include_bytes!(concat!(
692        env!("CARGO_MANIFEST_DIR"),
693        "/tests/fixtures/test_guest.wasm"
694    ));
695
696    /// The epoch thread lives exactly as long as the shared state: it keeps
697    /// running while any clone (or in-flight invoke) exists and is stopped
698    /// and joined once the last one is dropped.
699    #[tokio::test]
700    async fn ticker_stops_after_last_clone_is_dropped() {
701        let dir = tempfile::tempdir().unwrap();
702        let rt = Runtime::new(RuntimeConfig::new(dir.path())).unwrap();
703        let stopped = rt.0._ticker.stop_flag();
704        let weak = Arc::downgrade(&rt.0);
705
706        let clone = rt.clone();
707        drop(rt);
708        assert!(!stopped.load(Ordering::Relaxed), "a clone is still alive");
709        assert!(weak.upgrade().is_some());
710
711        // Also after real use: invoke, then drop the last handle.
712        clone
713            .publish("t", "f", Bytes::from_static(TEST_GUEST_WASM))
714            .await
715            .unwrap();
716        clone
717            .invoke("t", "f", b"x".to_vec(), &Limits::default())
718            .await
719            .unwrap();
720        drop(clone);
721        assert!(stopped.load(Ordering::Relaxed), "ticker must stop");
722        assert!(weak.upgrade().is_none(), "no leaked Arc<Inner>");
723    }
724
725    /// A cold LRU miss whose `.cwasm` is on disk only deserialises: it must
726    /// not queue for a compile permit, even while a stage holds the only one.
727    #[tokio::test]
728    async fn cold_load_from_cwasm_does_not_wait_for_compile_permit() {
729        let dir = tempfile::tempdir().unwrap();
730        let mut cfg = RuntimeConfig::new(dir.path());
731        cfg.compile_concurrency = 1;
732        let first = Runtime::new(cfg.clone()).unwrap();
733        first
734            .publish("t", "f", Bytes::from_static(TEST_GUEST_WASM))
735            .await
736            .unwrap();
737        drop(first);
738
739        // Fresh runtime: empty LRU, cwasm on disk. Hold the only permit, as
740        // a long-running stage would.
741        let rt = Runtime::new(cfg).unwrap();
742        let _held = rt.0.compile_slots.clone().acquire_owned().await.unwrap();
743        let out = tokio::time::timeout(
744            Duration::from_secs(10),
745            rt.invoke("t", "f", b"x".to_vec(), &Limits::default()),
746        )
747        .await
748        .expect("cold load queued behind the compile permit")
749        .unwrap();
750        assert_eq!(out.output, b"x");
751    }
752}