1use 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#[derive(Debug, Clone)]
33#[non_exhaustive]
34pub struct RuntimeConfig {
35 pub modules_dir: PathBuf,
45 pub allow_private_egress: bool,
49 pub memory_budget_bytes: usize,
54 pub max_in_flight_per_tenant: usize,
57 pub max_output_bytes: usize,
59 pub component_cache_entries: usize,
61 pub component_cache_bytes: usize,
63 pub compile_concurrency: usize,
66}
67
68impl RuntimeConfig {
69 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#[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 pub fn kv(mut self, kv: Arc<dyn KvStore>) -> Self {
96 self.kv = Some(kv);
97 self
98 }
99
100 pub fn meter(mut self, sink: Arc<dyn MeterSink>) -> Self {
103 self.meter = Some(sink);
104 self
105 }
106
107 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 admission: Arc<Semaphore>,
173 in_flight: Mutex<HashMap<String, usize>>,
174 compile_slots: Arc<Semaphore>,
175 _ticker: EpochTicker,
177}
178
179#[derive(Clone)]
226pub struct Runtime(Arc<Inner>);
227
228#[derive(Debug, Clone, PartialEq, Eq)]
231#[non_exhaustive]
232pub struct Staged {
233 pub digest: String,
235}
236
237#[derive(Debug, Clone)]
239#[non_exhaustive]
240pub struct Invocation {
241 pub output: Vec<u8>,
243 pub usage: Usage,
245}
246
247impl Runtime {
248 pub fn new(cfg: RuntimeConfig) -> Result<Self, Error> {
250 Self::builder(cfg).build()
251 }
252
253 pub fn builder(cfg: RuntimeConfig) -> RuntimeBuilder {
255 RuntimeBuilder {
256 cfg,
257 kv: None,
258 meter: None,
259 }
260 }
261
262 pub fn engine(&self) -> &Engine {
265 &self.0.engine
266 }
267
268 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 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 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 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 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 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 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 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 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 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 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 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
595fn 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
610struct 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
649struct 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 #[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 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 #[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 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}