1#![cfg_attr(
2 test,
3 allow(
4 clippy::disallowed_methods,
5 clippy::disallowed_types,
6 reason = "tests spawn, join and drain freely; production sites carry their own expectation"
7 )
8)]
9#![deny(unsafe_code)]
10#![cfg_attr(test, allow(clippy::unwrap_used))]
11
12use std::{
13 collections::BTreeMap,
14 fmt,
15 io::Read as _,
16 path::{Path, PathBuf},
17 sync::Arc,
18 time::{Duration, Instant},
19};
20
21use dekopon_capability::{AuthorizedInvocation, ChatSlotValues, ExecutionConstraints};
22use dekopon_core::{CapabilityId, ProviderId, offload};
23pub use dekopon_provider_sdk::{
24 CommandRunOutcome, ComponentFailure, ProviderApiVersion, ProviderCapability, ProviderManifest,
25};
26use dekopon_storage_host::{StorageEvidence, StorageGrant, StorageHost};
27pub use host::ProviderConflicts;
28use host::{
29 CommandExport, CommandExportProblem, ConflictScan, EngineError, RUN_COMMAND_EXPORT,
30 StoreLimits, check_command_export, command_export, command_input_bytes,
31};
32use serde::Serialize;
33use serde_json::Value;
34use thiserror::Error;
35use tokio::time::timeout;
36use tracing::Instrument as _;
37use wasmtime::component::{HasSelf, Linker};
38use wasmtime::{Engine, Store};
39
40pub mod asset;
41mod clock;
42mod cwasm;
43pub mod host;
44mod http;
45mod memory;
46mod metadata;
47mod random;
48mod rss;
49mod signed_download;
50pub use rss::peak_rss_bytes;
51mod settings;
52pub mod skills;
53mod spawn;
54mod stdio;
55mod storage;
56mod test_component_memo;
57use clock::ClockState;
58pub use dekopon_broker_protocol::{Streams, UpcallStdin, UpcallStreams};
59pub use dekopon_http_host::{
60 HttpRequestFacts, PolicyViolation, ReachableDestinationSettings, RequestAuthorizer,
61 reachable_destination_settings,
62};
63pub use http::{
64 BoundCredential, HttpCallEvidence, HttpConfigurationError, HttpInvocation,
65 NonPublicHttpsAuthority, PlaintextHostError, PlaintextHosts, destinations_cover,
66};
67use http::{HttpCeilings, HttpState};
68pub use metadata::LoadedProviderMetadata;
69use metadata::identify_bytes;
70use settings::SettingsState;
71pub use spawn::{UpcallExit, UpcallRequest};
72pub use stdio::{
73 MAX_READ_BYTES, MAX_STDERR_BYTES, STDERR_TRUNCATION_MARKER, StdioAdmissionError, StdioTrap,
74 ZERO_FAILURE_STATUS_NOTE,
75};
76pub use test_component_memo::{TestComponentMemoization, enable_test_component_memoization};
77
78pub(crate) mod bindings {
79 wasmtime::component::bindgen!({
80 path: "wit",
81 world: "provider",
82 imports: { default: async | trappable },
83 exports: { default: async },
84 with: {
85 "dekopon:storage/durable-files.file": crate::storage::FileResource,
86 "dekopon:asset/asset.handle": crate::asset::HandleResource,
87 "dekopon:asset/asset.writer": crate::asset::WriterResource,
88 "dekopon:stdio/streams.reader": crate::stdio::ReaderResource,
89 "dekopon:stdio/streams.writer": crate::stdio::WriterResource,
90 "dekopon:spawn/run.status": crate::spawn::StatusResource,
91 },
92 });
93}
94
95#[derive(Clone, Copy, Debug, Eq, PartialEq)]
96pub enum HostCallRejection {
97 Http(dekopon_http_host::PolicyViolation),
98 MonotonicOverflow,
99 RandomTooLarge,
100 RandomEntropy,
101 AssetCallRejected,
102}
103
104impl HostCallRejection {
105 pub const fn label(self) -> &'static str {
106 match self {
107 Self::Http(violation) => violation.label(),
108 Self::MonotonicOverflow => "monotonic-overflow",
109 Self::RandomTooLarge => "random-too-large",
110 Self::RandomEntropy => "random-entropy",
111 Self::AssetCallRejected => "asset-call-rejected",
112 }
113 }
114}
115
116impl fmt::Display for HostCallRejection {
117 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
118 formatter.write_str(self.label())
119 }
120}
121
122pub const PROVIDER_WIT: &str = include_str!("../wit/deps/provider.wit");
123pub const HTTP_WIT: &str = include_str!("../wit/deps/http.wit");
124pub const STORAGE_WIT: &str = include_str!("../wit/deps/storage.wit");
125pub const STDIO_WIT: &str = include_str!("../wit/deps/stdio.wit");
126
127pub const HARD_MAX_PROVIDER_COMPONENT_BYTES: u64 = 64 * 1024 * 1024;
128pub const DEFAULT_MAX_HTTP_REQUESTS: u32 = 32;
129pub const DEFAULT_MAX_HTTP_REQUEST_BYTES: u64 = 1024 * 1024;
130pub const DEFAULT_MAX_HTTP_RESPONSE_BYTES: u64 = 4 * 1024 * 1024;
131pub const DEFAULT_MAX_HTTP_HEADERS: usize = 128;
132pub const DEFAULT_MAX_HTTP_HEADER_BYTES: usize = 64 * 1024;
133pub const DEFAULT_FUEL: u64 = 8_000_000_000;
134pub const DEFAULT_MAX_TIMEOUT: Duration = Duration::from_secs(30);
135pub const DEFAULT_MAX_TOTAL_MEMORY_BYTES: usize = 256 * 1024 * 1024;
136
137#[derive(Clone, Debug, Eq, PartialEq)]
138pub struct BrokerHostLimits {
139 pub max_memory_bytes: usize,
140 pub max_table_elements: usize,
141 pub max_instances: usize,
142 pub max_tables: usize,
143 pub max_memories: usize,
144 pub max_input_bytes: usize,
145 pub max_output_bytes: usize,
146 pub max_http_requests: u32,
147 pub max_http_request_bytes: u64,
148 pub max_http_response_bytes: u64,
149 pub max_http_headers: usize,
150 pub max_http_header_bytes: usize,
151 pub fuel: u64,
152 pub max_timeout: Duration,
153}
154
155impl Default for BrokerHostLimits {
156 fn default() -> Self {
157 Self {
158 max_memory_bytes: host::DEFAULT_MAX_MEMORY_BYTES,
159 max_table_elements: host::DEFAULT_MAX_TABLE_ELEMENTS,
160 max_instances: host::DEFAULT_MAX_INSTANCES,
161 max_tables: host::DEFAULT_MAX_TABLES,
162 max_memories: host::DEFAULT_MAX_MEMORIES,
163 max_input_bytes: host::DEFAULT_MAX_INPUT_BYTES,
164 max_output_bytes: host::DEFAULT_MAX_OUTPUT_BYTES,
165 max_http_requests: DEFAULT_MAX_HTTP_REQUESTS,
166 max_http_request_bytes: DEFAULT_MAX_HTTP_REQUEST_BYTES,
167 max_http_response_bytes: DEFAULT_MAX_HTTP_RESPONSE_BYTES,
168 max_http_headers: DEFAULT_MAX_HTTP_HEADERS,
169 max_http_header_bytes: DEFAULT_MAX_HTTP_HEADER_BYTES,
170 fuel: DEFAULT_FUEL,
171 max_timeout: DEFAULT_MAX_TIMEOUT,
172 }
173 }
174}
175
176#[derive(Clone, Debug, Default)]
177pub struct TestImports {
178 #[cfg(feature = "native-test")]
179 pub http_transport: Option<dekopon_http_host::test_transport::Transport>,
180 #[cfg(feature = "native-test")]
181 pub credential: Option<BoundCredential>,
182 pub assets: Option<dekopon_http_host::asset::AssetDirectory>,
183 pub clock: Option<std::time::SystemTime>,
184 pub loopback_https_pin: Option<dekopon_http_host::LoopbackHttpsPin>,
185 pub settings: Option<String>,
186}
187
188#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
189pub enum CompiledCacheMode {
190 #[default]
191 Reader,
192 Publisher,
193}
194
195#[derive(Clone, Copy, Debug)]
196pub struct HttpDestinationOptions<'a> {
197 pub plaintext_hosts: &'a PlaintextHosts,
198 pub extra_ca_bundles: &'a [Vec<u8>],
199 pub non_public_https: &'a [NonPublicHttpsAuthority],
200}
201
202#[derive(Clone, Debug, Eq, PartialEq)]
203pub struct BrokerHostOptions {
204 pub cwasm_dir: Option<PathBuf>,
205 pub compiled_cache_mode: CompiledCacheMode,
206 pub max_total_memory_bytes: Option<usize>,
207 pub plaintext_hosts: PlaintextHosts,
208 pub extra_ca_bundles: Arc<Vec<Vec<u8>>>,
209 pub non_public_https: Arc<Vec<NonPublicHttpsAuthority>>,
210 pub provider_settings: Arc<BTreeMap<ProviderId, String>>,
211 pub test_clock: Option<std::time::SystemTime>,
212 pub loopback_https_pin: Option<dekopon_http_host::LoopbackHttpsPin>,
213}
214
215impl Default for BrokerHostOptions {
216 fn default() -> Self {
217 Self {
218 cwasm_dir: None,
219 compiled_cache_mode: CompiledCacheMode::Reader,
220 max_total_memory_bytes: Some(DEFAULT_MAX_TOTAL_MEMORY_BYTES),
221 plaintext_hosts: PlaintextHosts::default(),
222 extra_ca_bundles: Arc::new(Vec::new()),
223 non_public_https: Arc::new(Vec::new()),
224 provider_settings: Arc::new(BTreeMap::new()),
225 test_clock: None,
226 loopback_https_pin: None,
227 }
228 }
229}
230
231#[derive(Clone, Debug, Eq, PartialEq)]
232pub struct LockedProviderSource {
233 path: PathBuf,
234 artifact_bytes: u64,
235 artifact_sha256: String,
236 provider_id: ProviderId,
237}
238
239impl LockedProviderSource {
240 pub fn new(
241 path: impl Into<PathBuf>,
242 artifact_bytes: u64,
243 artifact_sha256: impl Into<String>,
244 provider_id: ProviderId,
245 ) -> Result<Self, BrokerHostError> {
246 let artifact_sha256 = artifact_sha256.into();
247 if artifact_bytes == 0 || artifact_bytes > HARD_MAX_PROVIDER_COMPONENT_BYTES {
248 return Err(BrokerHostError::InvalidArtifactSize {
249 size: artifact_bytes,
250 maximum: HARD_MAX_PROVIDER_COMPONENT_BYTES,
251 });
252 }
253 if artifact_sha256.len() != 64
254 || !artifact_sha256
255 .bytes()
256 .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
257 {
258 return Err(BrokerHostError::InvalidArtifactDigest);
259 }
260 Ok(Self {
261 path: path.into(),
262 artifact_bytes,
263 artifact_sha256,
264 provider_id,
265 })
266 }
267
268 pub fn read(&self) -> Result<Vec<u8>, BrokerHostError> {
269 read_source(&self.path, Some(self)).map(|(bytes, _)| bytes)
270 }
271
272 #[must_use]
273 pub fn path(&self) -> &Path {
274 &self.path
275 }
276
277 #[must_use]
278 pub const fn artifact_bytes(&self) -> u64 {
279 self.artifact_bytes
280 }
281
282 #[must_use]
283 pub fn artifact_sha256(&self) -> &str {
284 &self.artifact_sha256
285 }
286
287 #[must_use]
288 pub fn provider_id(&self) -> &ProviderId {
289 &self.provider_id
290 }
291}
292
293#[derive(Clone)]
294struct ProviderSource {
295 path: PathBuf,
296 expected: Option<LockedProviderSource>,
297}
298
299impl From<PathBuf> for ProviderSource {
300 fn from(path: PathBuf) -> Self {
301 Self {
302 path,
303 expected: None,
304 }
305 }
306}
307
308impl From<LockedProviderSource> for ProviderSource {
309 fn from(expected: LockedProviderSource) -> Self {
310 Self {
311 path: expected.path.clone(),
312 expected: Some(expected),
313 }
314 }
315}
316
317const MAX_FUEL_YIELD_INTERVAL: u64 = 10_000;
318
319const MAX_COMMAND_WORD_HELP_BYTES: usize = 2048;
322
323impl BrokerHostLimits {
324 #[must_use]
325 pub const fn fuel_yield_interval(&self) -> u64 {
326 if self.fuel < MAX_FUEL_YIELD_INTERVAL {
327 self.fuel
328 } else {
329 MAX_FUEL_YIELD_INTERVAL
330 }
331 }
332
333 fn store_bounds(&self) -> StoreLimits {
334 StoreLimits {
335 max_memory_bytes: self.max_memory_bytes,
336 max_table_elements: self.max_table_elements,
337 max_instances: self.max_instances,
338 max_tables: self.max_tables,
339 max_memories: self.max_memories,
340 }
341 }
342}
343
344#[derive(Debug)]
345pub struct BrokerInvocationFailure {
346 pub error: Box<BrokerHostError>,
347 pub http_calls: Vec<HttpCallEvidence>,
348 pub storage: Option<StorageEvidence>,
349}
350
351impl From<BrokerHostError> for BrokerInvocationFailure {
352 fn from(error: BrokerHostError) -> Self {
353 Self {
354 error: Box::new(error),
355 http_calls: Vec::new(),
356 storage: None,
357 }
358 }
359}
360
361impl fmt::Display for BrokerInvocationFailure {
362 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
363 self.error.fmt(formatter)
364 }
365}
366
367impl std::error::Error for BrokerInvocationFailure {
368 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
369 Some(self.error.as_ref())
370 }
371}
372
373#[derive(Debug, Serialize)]
374#[serde(rename_all = "camelCase")]
375pub struct BrokerInvocationOutput {
376 #[serde(skip)]
377 pub assets: asset::AssetOutputs,
378 pub provider: ProviderId,
379 pub capability: CapabilityId,
380 pub stderr: String,
381 pub http_calls: Vec<HttpCallEvidence>,
382 #[serde(skip_serializing_if = "Option::is_none")]
383 pub storage: Option<StorageEvidence>,
384}
385
386struct Runtime {
387 engine: Engine,
388 engine_key: String,
389 cwasm: Option<cwasm::Cache>,
390 compiled_cache_mode: CompiledCacheMode,
391 linker: Linker<StoreState>,
392 limits: BrokerHostLimits,
393 memory_budget: Option<Arc<memory::MemoryBudget>>,
394 plaintext_hosts: PlaintextHosts,
395 extra_ca_bundles: Arc<Vec<Vec<u8>>>,
396 non_public_https: Arc<Vec<NonPublicHttpsAuthority>>,
397 provider_settings: Arc<BTreeMap<ProviderId, String>>,
398 test_clock: Option<std::time::SystemTime>,
399 loopback_https_pin: Option<dekopon_http_host::LoopbackHttpsPin>,
400}
401
402impl Runtime {
403 fn new(limits: BrokerHostLimits, options: &BrokerHostOptions) -> Result<Self, BrokerHostError> {
404 validate_limits(&limits)?;
405 if options
406 .max_total_memory_bytes
407 .is_some_and(|maximum| maximum < limits.max_memory_bytes)
408 {
409 return Err(BrokerHostError::InvalidLimit {
410 name: "max_total_memory_bytes",
411 });
412 }
413 let config = host::config();
414 let engine = host::engine(config).map_err(|error| match error {
415 EngineError::Engine { source } => BrokerHostError::Engine { source },
416 })?;
417 let cwasm = options
418 .cwasm_dir
419 .clone()
420 .map(|root| cwasm::Cache::new(root, &engine));
421 let mut linker = Linker::new(&engine);
422 signed_download::bindings::dekopon::http0_1_0::signed_download::add_to_linker::<
423 _,
424 HasSelf<_>,
425 >(&mut linker, |state| state)
426 .map_err(|source| BrokerHostError::Linker { source })?;
427 bindings::Provider::add_to_linker::<_, HasSelf<_>>(&mut linker, |state| state)
428 .map_err(|source| BrokerHostError::Linker { source })?;
429 asset::link_bounded_writer(&mut linker)
430 .map_err(|source| BrokerHostError::Linker { source })?;
431 Ok(Self {
432 engine_key: cwasm::compatibility_key(&engine),
433 engine,
434 cwasm,
435 compiled_cache_mode: options.compiled_cache_mode,
436 linker,
437 limits,
438 memory_budget: options
439 .max_total_memory_bytes
440 .map(|maximum| Arc::new(memory::MemoryBudget::new(maximum))),
441 plaintext_hosts: options.plaintext_hosts.clone(),
442 extra_ca_bundles: Arc::clone(&options.extra_ca_bundles),
443 non_public_https: Arc::clone(&options.non_public_https),
444 provider_settings: Arc::clone(&options.provider_settings),
445 test_clock: options.test_clock,
446 loopback_https_pin: options.loopback_https_pin.clone(),
447 })
448 }
449
450 fn store_for_provider(
451 &self,
452 provider: &str,
453 http: HttpState,
454 storage: storage::StorageState,
455 clock: ClockState,
456 settings: SettingsState,
457 ) -> Result<Store<StoreState>, BrokerHostError> {
458 let mut store = Store::new(
459 &self.engine,
460 StoreState {
461 limits: memory::MemoryLimiter::new(
462 self.limits.store_bounds(),
463 self.memory_budget.clone(),
464 provider,
465 ),
466 http,
467 storage,
468 clock,
469 settings,
470 assets: asset::AssetState::disabled(),
471 stdio: stdio::StdioState::none(),
472 spawn: spawn::SpawnState::default(),
473 table: storage::new_table(),
474 instantiations: 0,
475 },
476 );
477 store.limiter(|state| &mut state.limits);
478 store
479 .set_fuel(self.limits.fuel)
480 .map_err(|source| BrokerHostError::Store { source })?;
481 store
482 .fuel_async_yield_interval(Some(self.limits.fuel_yield_interval()))
483 .map_err(|source| BrokerHostError::Store { source })?;
484 tracing::Span::current().record("stores", 1_u64);
485 Ok(store)
486 }
487
488 fn http_ceilings(&self) -> HttpCeilings {
489 HttpCeilings {
490 max_requests: self.limits.max_http_requests,
491 max_request_bytes: self.limits.max_http_request_bytes,
492 max_response_bytes: self.limits.max_http_response_bytes,
493 max_headers: self.limits.max_http_headers,
494 max_header_bytes: self.limits.max_http_header_bytes,
495 plaintext_hosts: self.plaintext_hosts.clone(),
496 extra_ca_bundles: Arc::clone(&self.extra_ca_bundles),
497 non_public_https: Arc::clone(&self.non_public_https),
498 loopback_https_pin: self.loopback_https_pin.clone(),
499 }
500 }
501}
502
503struct StoreState {
504 assets: asset::AssetState,
505 limits: memory::MemoryLimiter,
506 http: HttpState,
507 storage: storage::StorageState,
508 clock: ClockState,
509 settings: SettingsState,
510 stdio: stdio::StdioState,
511 spawn: spawn::SpawnState,
512 table: wasmtime::component::ResourceTable,
513 instantiations: u64,
514}
515
516impl bindings::dekopon::http1_1_0::client::Host for StoreState {
517 async fn stream(
518 &mut self,
519 request: bindings::dekopon::http1_1_0::client::StreamedRequest,
520 ) -> wasmtime::Result<
521 Result<
522 bindings::dekopon::http1_1_0::client::StreamedResponse,
523 bindings::dekopon::http1_1_0::client::HttpError,
524 >,
525 > {
526 use bindings::dekopon::http1_1_0::client as wit;
527 let Some(directory) = self.assets.directory()? else {
528 self.assets
529 .reject(bindings::dekopon::asset::asset::ErrorCode::Unconfigured);
530 return Ok(Err(wit::HttpError {
531 code: wit::ErrorCode::Internal,
532 message: "unconfigured: configure assets.rootPath before streaming HTTP".to_owned(),
533 }));
534 };
535 let mut body = Vec::with_capacity(request.body.len());
536 for part in request.body {
537 body.push(match part {
538 wit::Part::Literal(bytes) => dekopon_http_host::Part::Literal(bytes),
539 wit::Part::Asset(part) => {
540 let part = self.table.get(&part.handle)?.http_part(part.encoding);
541 if let Err(error) = self.assets.charge_stream(part.decoded_bytes) {
542 return Ok(Err(wit::HttpError {
543 code: wit::ErrorCode::RequestTooLarge,
544 message: error.message,
545 }));
546 }
547 dekopon_http_host::Part::Asset(part)
548 }
549 });
550 }
551 let response = self
552 .http
553 .client
554 .stream(
555 dekopon_http_host::StreamedRequest {
556 method: request.method,
557 uri: request.uri,
558 headers: request
559 .headers
560 .into_iter()
561 .map(|header| dekopon_http_host::Header {
562 name: header.name,
563 value: header.value,
564 })
565 .collect(),
566 body,
567 },
568 &directory,
569 )
570 .await;
571 let response = match response {
572 Ok(response) => response,
573 Err(error) => {
574 self.assets.reject(if self.http.client.asset_over_budget() {
575 bindings::dekopon::asset::asset::ErrorCode::OverBudget
576 } else {
577 bindings::dekopon::asset::asset::ErrorCode::Io
578 });
579 return Ok(Err(http::map_error(error)));
580 }
581 };
582 let content_type = response
583 .headers
584 .iter()
585 .find(|header| header.name.eq_ignore_ascii_case("content-type"))
586 .and_then(|header| std::str::from_utf8(&header.value).ok())
587 .unwrap_or("application/octet-stream")
588 .to_owned();
589 let handle = match asset::HandleResource::from_output(
590 response.body,
591 content_type,
592 bindings::dekopon::asset::asset::Encoding::Identity,
593 "response".to_owned(),
594 )
595 .await
596 {
597 Ok(handle) => handle,
598 Err(error) => {
599 self.assets.reject(error.code);
600 return Ok(Err(wit::HttpError {
601 code: wit::ErrorCode::Internal,
602 message: error.message,
603 }));
604 }
605 };
606 Ok(Ok(wit::StreamedResponse {
607 status: response.status,
608 headers: response
609 .headers
610 .into_iter()
611 .map(|header| wit::Header {
612 name: header.name,
613 value: header.value,
614 })
615 .collect(),
616 body: self.table.push(handle)?,
617 }))
618 }
619
620 async fn send(
621 &mut self,
622 request: bindings::dekopon::http1_1_0::client::Request,
623 ) -> wasmtime::Result<
624 Result<
625 bindings::dekopon::http1_1_0::client::Response,
626 bindings::dekopon::http1_1_0::client::HttpError,
627 >,
628 > {
629 Ok(self.http.send(request).await)
630 }
631}
632struct CompiledComponent {
633 source: PathBuf,
634 expected_provider_id: Option<ProviderId>,
635 artifact_bytes: u64,
636 artifact_sha256: String,
637 compile_ms: u64,
638 pre: bindings::ProviderPre<StoreState>,
639 command_export: CommandExport,
640}
641
642#[derive(Clone)]
643pub struct BrokerWasmProvider {
644 runtime: Arc<Runtime>,
645 pre: bindings::ProviderPre<StoreState>,
646 source: PathBuf,
647 artifact_bytes: u64,
648 artifact_sha256: String,
649 manifest: ProviderManifest,
650 command_export: CommandExport,
651 command_word_help: BTreeMap<String, String>,
652}
653
654impl fmt::Debug for BrokerWasmProvider {
655 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
656 formatter
657 .debug_struct("BrokerWasmProvider")
658 .field("source", &self.source)
659 .field("manifest", &self.manifest)
660 .finish_non_exhaustive()
661 }
662}
663
664fn compile_component(
665 runtime: &Runtime,
666 source: ProviderSource,
667) -> Result<CompiledComponent, BrokerHostError> {
668 let span = tracing::info_span!(
669 "provider.compile",
670 path = %source.path.display(),
671 artifact_bytes = tracing::field::Empty,
672 artifact_sha256 = tracing::field::Empty,
673 cache = if runtime.cwasm.is_some() { "lookup" } else { "bypass" },
674 engine_key = %runtime.engine_key,
675 cwasm_bytes = tracing::field::Empty,
676 cwasm_sha256 = tracing::field::Empty,
677 source_verify_us = tracing::field::Empty,
678 cache_wait_us = tracing::field::Empty,
679 elapsed_us = tracing::field::Empty,
680 elapsed_ms = tracing::field::Empty,
681 outcome = tracing::field::Empty,
682 peak_rss_bytes = tracing::field::Empty,
683 );
684 span.in_scope(|| {
685 let started = Instant::now();
686 let mut result = prepare_component(runtime, source);
687 let elapsed_us = cwasm::micros(started);
688 let elapsed_ms = elapsed_us / 1000;
689 if let Ok(compiled) = &mut result {
690 compiled.compile_ms = elapsed_ms;
691 }
692 let outcome = if result.is_ok() { "succeeded" } else { "failed" };
693 span.record("elapsed_us", elapsed_us);
694 span.record("elapsed_ms", elapsed_ms);
695 span.record("outcome", outcome);
696 if let Some(bytes) = peak_rss_bytes() {
697 span.record("peak_rss_bytes", bytes);
698 }
699 match &result {
700 Ok(_) => tracing::info!(elapsed_us, outcome, "provider.load.finished"),
701 Err(error) => tracing::error!(elapsed_us, outcome, error = %dekopon_core::bounded_attribute(&dekopon_core::error_chain(error)), "provider.load.failed"),
702 }
703 result
704 })
705}
706
707fn prepare_component(
708 runtime: &Runtime,
709 source: ProviderSource,
710) -> Result<CompiledComponent, BrokerHostError> {
711 let started = Instant::now();
712 let (bytes, artifact) = read_source(&source.path, source.expected.as_ref())?;
713 let span = tracing::Span::current();
714 span.record("artifact_bytes", artifact.bytes);
715 span.record("artifact_sha256", &artifact.sha256);
716 let source_verify_us = cwasm::micros(started);
717 span.record("source_verify_us", source_verify_us);
718 tracing::info!(
719 source_verify_us,
720 artifact_bytes = artifact.bytes,
721 "provider.source.verified"
722 );
723 let expected_provider_id = source.expected.map(|expected| expected.provider_id);
724 let source = source.path;
725 let component = match &runtime.cwasm {
726 Some(cache) => match runtime.compiled_cache_mode {
727 CompiledCacheMode::Reader => match cache
728 .load(&runtime.engine, &artifact.sha256)
729 .map_err(|error| BrokerHostError::CompiledArtifact {
730 path: source.clone(),
731 source: error,
732 })? {
733 cwasm::Lookup::Mapped(component) => component,
734 cwasm::Lookup::Missing => {
735 return Err(BrokerHostError::CompiledArtifactMissing {
736 path: source,
737 engine_key: runtime.engine_key.clone(),
738 });
739 }
740 },
741 CompiledCacheMode::Publisher => cache
742 .publish_component(&runtime.engine, &bytes, &artifact.sha256)
743 .map_err(|error| BrokerHostError::CompiledArtifact {
744 path: source.clone(),
745 source: error,
746 })?,
747 },
748 None => cwasm::stage("compile", artifact.bytes, || {
749 test_component_memo::compile(
750 &runtime.engine,
751 &runtime.engine_key,
752 &artifact.sha256,
753 &bytes,
754 )
755 })
756 .map_err(|error| BrokerHostError::Compile {
757 path: source.clone(),
758 source: error,
759 })?,
760 };
761 drop(bytes);
762 let command_export = command_export(&runtime.engine, &component);
763 let pre = runtime
764 .linker
765 .instantiate_pre(&component)
766 .and_then(bindings::ProviderPre::new)
767 .map_err(|error| BrokerHostError::Instantiate {
768 path: source.clone(),
769 source: error,
770 })?;
771 Ok(CompiledComponent {
772 source,
773 expected_provider_id,
774 artifact_bytes: artifact.bytes,
775 artifact_sha256: artifact.sha256,
776 compile_ms: 0,
777 pre,
778 command_export,
779 })
780}
781
782fn read_source(
783 path: &Path,
784 expected: Option<&LockedProviderSource>,
785) -> Result<(Vec<u8>, metadata::ArtifactIdentity), BrokerHostError> {
786 let file = std::fs::File::open(path).map_err(|error| BrokerHostError::ArtifactMetadata {
789 path: path.to_path_buf(),
790 source: error,
791 })?;
792 let metadata = file
793 .metadata()
794 .map_err(|error| BrokerHostError::ArtifactMetadata {
795 path: path.to_path_buf(),
796 source: error,
797 })?;
798 let maximum = expected.map_or(HARD_MAX_PROVIDER_COMPONENT_BYTES, |expected| {
799 expected.artifact_bytes
800 });
801 if let Some(expected) = expected
802 && metadata.len() != expected.artifact_bytes
803 {
804 return Err(BrokerHostError::ArtifactSizeMismatch {
805 path: path.to_path_buf(),
806 expected: expected.artifact_bytes,
807 actual: metadata.len(),
808 });
809 }
810 if metadata.len() > maximum {
811 return Err(BrokerHostError::ArtifactTooLarge {
812 path: path.to_path_buf(),
813 actual: metadata.len(),
814 maximum,
815 });
816 }
817 let mut bytes = Vec::new();
818 file.take(maximum.saturating_add(1))
819 .read_to_end(&mut bytes)
820 .map_err(|error| BrokerHostError::ArtifactMetadata {
821 path: path.to_path_buf(),
822 source: error,
823 })?;
824 let actual = bytes.len() as u64;
825 if actual > maximum {
826 return match expected {
827 Some(expected) => Err(BrokerHostError::ArtifactSizeMismatch {
828 path: path.to_path_buf(),
829 expected: expected.artifact_bytes,
830 actual,
831 }),
832 None => Err(BrokerHostError::ArtifactTooLarge {
833 path: path.to_path_buf(),
834 actual,
835 maximum,
836 }),
837 };
838 }
839 let artifact = identify_bytes(&bytes);
840 if let Some(expected) = expected {
841 if artifact.bytes != expected.artifact_bytes {
842 return Err(BrokerHostError::ArtifactSizeMismatch {
843 path: path.to_path_buf(),
844 expected: expected.artifact_bytes,
845 actual: artifact.bytes,
846 });
847 }
848 if artifact.sha256 != expected.artifact_sha256 {
849 return Err(BrokerHostError::ArtifactDigestMismatch {
850 path: path.to_path_buf(),
851 expected: expected.artifact_sha256.clone(),
852 actual: artifact.sha256,
853 });
854 }
855 }
856 Ok((bytes, artifact))
857}
858
859impl BrokerWasmProvider {
860 async fn load(
861 runtime: Arc<Runtime>,
862 compiled: CompiledComponent,
863 ) -> Result<Self, BrokerHostError> {
864 let CompiledComponent {
865 source,
866 expected_provider_id,
867 artifact_bytes,
868 artifact_sha256,
869 compile_ms,
870 pre,
871 command_export,
872 } = compiled;
873 let manifest_json =
874 describe_component(&runtime, &pre, &source, expected_provider_id.as_ref())
875 .instrument(tracing::info_span!(
876 "provider.describe",
877 path = %source.display(),
878 stores = tracing::field::Empty,
879 instantiations = tracing::field::Empty,
880 fuel.consumed = tracing::field::Empty,
881 ))
882 .await?;
883 if manifest_json.len() > runtime.limits.max_output_bytes {
884 return Err(BrokerHostError::OutputTooLarge {
885 provider: source.display().to_string(),
886 length: manifest_json.len(),
887 maximum: runtime.limits.max_output_bytes,
888 });
889 }
890 let manifest =
891 serde_json::from_str::<ProviderManifest>(&manifest_json).map_err(|error| {
892 BrokerHostError::InvalidManifest {
893 path: source.clone(),
894 source: error,
895 }
896 })?;
897 validate_manifest(&manifest, &source)?;
898 if let Some(expected) = expected_provider_id
899 && manifest.id != expected
900 {
901 return Err(BrokerHostError::ProviderIdentityMismatch {
902 path: source,
903 expected,
904 actual: manifest.id,
905 });
906 }
907 if let Err(problem) = check_command_export(&manifest, &command_export) {
910 return Err(match problem {
911 CommandExportProblem::Missing => BrokerHostError::MissingCommandExport {
912 provider: manifest.id.clone(),
913 path: source.clone(),
914 },
915 CommandExportProblem::Mismatched { found } => {
916 BrokerHostError::CommandExportSignature {
917 provider: manifest.id.clone(),
918 path: source.clone(),
919 found,
920 }
921 }
922 });
923 }
924 tracing::info!(
925 provider = %manifest.id,
926 path = %source.display(),
927 artifact_bytes,
928 artifact_sha256 = &artifact_sha256[..artifact_sha256.len().min(12)],
929 compile_ms,
930 capabilities = manifest.capabilities.len(),
931 command_words = manifest.command_words.len(),
932 command_export = command_export_name(&command_export),
933 "provider.loaded"
934 );
935 let mut provider = Self {
936 runtime,
937 pre,
938 source,
939 artifact_bytes,
940 artifact_sha256,
941 manifest,
942 command_export,
943 command_word_help: BTreeMap::new(),
944 };
945 provider.command_word_help = provider.render_command_word_help().await;
946 Ok(provider)
947 }
948
949 pub async fn run_command(
950 &self,
951 argv: &[String],
952 stdin_piped: bool,
953 ) -> Result<String, BrokerHostError> {
954 let length = command_input_bytes(argv);
955 if length > self.runtime.limits.max_input_bytes {
956 return Err(BrokerHostError::CommandInputTooLarge {
957 provider: self.manifest.id.clone(),
958 length,
959 maximum: self.runtime.limits.max_input_bytes,
960 });
961 }
962 match &self.command_export {
963 CommandExport::Present => {}
964 CommandExport::Absent => {
965 return Err(BrokerHostError::MissingCommandExport {
966 provider: self.manifest.id.clone(),
967 path: self.source.clone(),
968 });
969 }
970 CommandExport::Mismatched { found } => {
971 return Err(BrokerHostError::CommandExportSignature {
972 provider: self.manifest.id.clone(),
973 path: self.source.clone(),
974 found: found.clone(),
975 });
976 }
977 }
978 let operation_timeout = self.runtime.limits.max_timeout;
979 let http = HttpState::describe(self.runtime.http_ceilings(), operation_timeout)
980 .map_err(|source| BrokerHostError::HttpConfiguration { source })?;
981 let mut store = self.runtime.store_for_provider(
982 self.manifest.id.as_str(),
983 http,
984 storage::StorageState::disabled(),
985 ClockState::describe(),
986 SettingsState::describe(),
987 )?;
988 let argv = argv.to_vec();
989 let signature = |source: wasmtime::Error| BrokerHostError::CommandExportSignature {
990 provider: self.manifest.id.clone(),
991 path: self.source.clone(),
992 found: source.to_string(),
993 };
994 let failed = |source: wasmtime::Error| BrokerHostError::RunCommand {
995 provider: self.manifest.id.clone(),
996 source,
997 };
998 let operation = async {
999 let instance = self
1000 .pre
1001 .instance_pre()
1002 .instantiate_async(&mut store)
1003 .await
1004 .map_err(|source| BrokerHostError::Instantiate {
1005 path: self.source.clone(),
1006 source,
1007 })?;
1008 store.data_mut().instantiations += 1;
1009 let function = instance
1010 .get_typed_func::<(Vec<String>, bool), (String,)>(&mut store, RUN_COMMAND_EXPORT)
1011 .map_err(signature)?;
1012 let (output,) = function
1013 .call_async(&mut store, (argv, stdin_piped))
1014 .await
1015 .map_err(failed)?;
1016 Ok::<_, BrokerHostError>(output)
1017 };
1018 #[allow(
1019 clippy::map_err_ignore,
1020 reason = "`tokio::time::error::Elapsed` carries only \"deadline has elapsed\"; the \
1021 Timeout variant already names the operation and the budget it exceeded"
1022 )]
1023 let output =
1024 timeout(operation_timeout, operation)
1025 .await
1026 .map_err(|_| BrokerHostError::Timeout {
1027 operation: format!("{RUN_COMMAND_EXPORT} {}", self.manifest.id),
1028 timeout_ms: operation_timeout.as_millis() as u64,
1029 });
1030 record_store_outcome(&mut store, self.runtime.limits.fuel);
1031 if store.data().clock.attempted() || store.data().settings.attempted() {
1033 return Err(BrokerHostError::RunCommandUsedHostImport {
1034 path: self.source.clone(),
1035 });
1036 }
1037 let output = output??;
1038 if store.data().http.attempted()
1039 || store.data().storage.attempted()
1040 || store.data().assets.attempted()
1041 {
1042 return Err(BrokerHostError::RunCommandUsedHostImport {
1043 path: self.source.clone(),
1044 });
1045 }
1046 if output.len() > self.runtime.limits.max_output_bytes {
1047 return Err(BrokerHostError::OutputTooLarge {
1048 provider: self.manifest.id.to_string(),
1049 length: output.len(),
1050 maximum: self.runtime.limits.max_output_bytes,
1051 });
1052 }
1053 Ok(output)
1054 }
1055
1056 async fn render_command_word_help(&self) -> BTreeMap<String, String> {
1057 if self.manifest.command_words.is_empty() {
1058 return BTreeMap::new();
1059 }
1060 let Some(page) = self.render_provider_help().await else {
1061 return BTreeMap::new();
1062 };
1063 self.manifest
1064 .command_words
1065 .iter()
1066 .cloned()
1067 .map(|word| (word, page.clone()))
1068 .collect()
1069 }
1070
1071 #[expect(
1072 clippy::wildcard_enum_match_arm,
1073 reason = "reshaped by the unit that next rewrites this"
1074 )]
1075 async fn render_provider_help(&self) -> Option<String> {
1076 let json = match self.run_command(&["--help".to_owned()], false).await {
1077 Ok(json) => json,
1078 Err(error) => {
1079 tracing::warn!(
1080 provider = %self.manifest.id,
1081 error = %dekopon_core::bounded_attribute(&dekopon_core::error_chain(&error)),
1082 "provider.help.failed"
1083 );
1084 return None;
1085 }
1086 };
1087 let outcome = match serde_json::from_str::<CommandRunOutcome>(&json) {
1088 Ok(outcome) => outcome,
1089 Err(error) => {
1090 tracing::warn!(
1091 provider = %self.manifest.id,
1092 error = %error,
1093 "provider.help.failed"
1094 );
1095 return None;
1096 }
1097 };
1098 match outcome {
1099 CommandRunOutcome::Rendered { stdout, status, .. }
1100 if status == 0 && !stdout.is_empty() =>
1101 {
1102 Some(bounded_command_word_help(stdout))
1103 }
1104 _ => {
1105 tracing::warn!(
1106 provider = %self.manifest.id,
1107 "provider.help.failed"
1108 );
1109 None
1110 }
1111 }
1112 }
1113
1114 #[allow(
1115 clippy::too_many_arguments,
1116 clippy::too_many_lines,
1117 reason = "the invocation keeps separate authority grants, cancellation, and cleanup in one owned store"
1118 )]
1119 async fn invoke(
1120 &self,
1121 test_imports: Option<&TestImports>,
1122 capability: &CapabilityId,
1123 input: &Value,
1124 constraints: &ExecutionConstraints,
1125 credential: Option<BoundCredential>,
1126 slots: ChatSlotValues,
1127 request_authorizer: Option<RequestAuthorizer>,
1128 storage_transaction: Option<dekopon_storage_host::StorageHandle>,
1129 mut assets: asset::AssetInputs,
1130 directory: Option<dekopon_http_host::asset::AssetDirectory>,
1131 ) -> Result<BrokerInvocationOutput, BrokerInvocationFailure> {
1132 validate_authorized_constraints(constraints, &self.runtime.limits)?;
1133 if !self
1134 .manifest
1135 .capabilities
1136 .iter()
1137 .any(|candidate| &candidate.id == capability)
1138 {
1139 return Err(BrokerHostError::ProviderDoesNotImplement {
1140 provider: self.manifest.id.clone(),
1141 capability: capability.clone(),
1142 }
1143 .into());
1144 }
1145 if !input.is_object() {
1146 return Err(BrokerHostError::InputNotObject {
1147 capability: capability.clone(),
1148 }
1149 .into());
1150 }
1151 let input_json = serde_json::to_string(input)
1152 .map_err(|source| BrokerHostError::SerializeInput { source })?;
1153 if input_json.len() > self.runtime.limits.max_input_bytes {
1154 return Err(BrokerHostError::InputTooLarge {
1155 capability: capability.clone(),
1156 length: input_json.len(),
1157 maximum: self.runtime.limits.max_input_bytes,
1158 }
1159 .into());
1160 }
1161
1162 let operation_timeout = Duration::from_millis(constraints.timeout_ms);
1163 let mut ceilings = self.runtime.http_ceilings();
1164 if let Some(pin) = test_imports.and_then(|imports| imports.loopback_https_pin.as_ref()) {
1165 ceilings.loopback_https_pin = Some(pin.clone());
1166 }
1167 let http = match HttpState::invoke(
1168 constraints.http.clone(),
1169 constraints.secret_use.clone(),
1170 credential,
1171 HttpInvocation {
1172 slots,
1173 authorizer: request_authorizer,
1174 },
1175 ceilings,
1176 operation_timeout,
1177 ) {
1178 Ok(http) => http,
1179 Err(source) => return Err(BrokerHostError::HttpConfiguration { source }.into()),
1180 };
1181 #[cfg(feature = "native-test")]
1182 let http = match test_imports.and_then(|imports| imports.http_transport.clone()) {
1183 Some(transport) => HttpState {
1184 client: http.client.with_test_transport(transport),
1185 },
1186 None => http,
1187 };
1188 let storage_state = storage_transaction.map_or_else(
1189 storage::StorageState::disabled,
1190 storage::StorageState::active,
1191 );
1192 let mut store = self.runtime.store_for_provider(
1193 self.manifest.id.as_str(),
1194 http,
1195 storage_state,
1196 ClockState::invoke(
1197 test_imports
1198 .and_then(|imports| imports.clock)
1199 .or(self.runtime.test_clock),
1200 ),
1201 SettingsState::invoke(
1202 test_imports
1203 .and_then(|imports| imports.settings.clone())
1204 .or_else(|| {
1205 self.runtime
1206 .provider_settings
1207 .get(&self.manifest.id)
1208 .cloned()
1209 }),
1210 ),
1211 )?;
1212 let cancel = assets.cancel.take();
1213 store.data_mut().stdio = stdio::StdioState::invoke(assets.streams.take())
1214 .map_err(|source| BrokerHostError::StdioAdmission { source })?;
1215 store.data_mut().spawn =
1216 spawn::SpawnState::invoke(assets.upcalls.take(), self.runtime.limits.max_input_bytes);
1217 store.data_mut().assets = asset::AssetState::invoke(
1218 assets,
1219 constraints.asset.clone().unwrap_or_default(),
1220 directory,
1221 format!("provider:{capability}"),
1222 )
1223 .await
1224 .map_err(|source| BrokerHostError::AssetInput { source })?;
1225 let initial_fuel = store.get_fuel().ok();
1228 store
1229 .data_mut()
1230 .limits
1231 .observe_invocation(capability.as_str(), initial_fuel);
1232 let mut executed = self
1235 .execute_in_store(
1236 &mut store,
1237 capability,
1238 &input_json,
1239 constraints,
1240 operation_timeout,
1241 cancel,
1242 )
1243 .await;
1244 executed = executed
1245 .map_err(|error| invocation_budget_failure(error, store.data().limits.refusal()));
1246 store.data_mut().stdio.close();
1247 store.data_mut().spawn = spawn::SpawnState::default();
1248 store.data().assets.drain().await;
1249 if matches!(
1252 store.data().assets.violation(),
1253 Some(bindings::dekopon::asset::asset::ErrorCode::OverBudget)
1254 ) {
1255 executed = Err(BrokerHostError::AssetOverBudget);
1256 }
1257 record_stream_trace(&store.data().stdio);
1258 let stderr = store.data_mut().stdio.take_stderr();
1259 executed = match executed {
1260 Ok(0) => Ok(0),
1261 Ok(status) => Err(BrokerHostError::ProviderFailure {
1262 provider: self.manifest.id.clone(),
1263 capability: capability.clone(),
1264 status,
1265 stderr: stderr.clone(),
1266 }),
1267 Err(error) => Err(error),
1268 };
1269 let commit = executed.is_ok();
1270 if let Err(source) = store.data_mut().storage.finish(commit).await {
1271 executed = Err(BrokerHostError::Storage { source });
1272 }
1273 record_store_outcome(&mut store, self.runtime.limits.fuel);
1274 store.data_mut().limits.finish(match &executed {
1275 Ok(_) => "succeeded",
1276 Err(BrokerHostError::ProviderFailure { .. }) => "provider-error",
1277 Err(BrokerHostError::Timeout { .. }) => "timeout",
1278 Err(BrokerHostError::PeerDisconnected) => "peer-disconnected",
1279 Err(BrokerHostError::MemoryBudgetExhausted { .. }) => "host-memory-budget",
1280 Err(BrokerHostError::Invoke { source, .. })
1281 if source.downcast_ref::<wasmtime::Trap>() == Some(&wasmtime::Trap::OutOfFuel) =>
1282 {
1283 "fuel-exhausted"
1284 }
1285 Err(BrokerHostError::Invoke { .. }) => "trap",
1286 Err(BrokerHostError::Instantiate { .. }) => "instantiation-error",
1287 Err(_) => "host-error",
1288 });
1289 let mut data = store.into_data();
1290 let storage = data.storage.take_evidence();
1291 let http_calls = data.http.into_evidence();
1292 match executed {
1293 Ok(_) => Ok(BrokerInvocationOutput {
1294 provider: self.manifest.id.clone(),
1295 capability: capability.clone(),
1296 stderr,
1297 assets: data.assets.finish(),
1298 http_calls,
1299 storage,
1300 }),
1301 Err(error) => Err(BrokerInvocationFailure {
1302 error: Box::new(error),
1303 http_calls,
1304 storage,
1305 }),
1306 }
1307 }
1308
1309 #[expect(
1310 clippy::too_many_arguments,
1311 reason = "the host keeps the authorized budget and peer cancellation separate from guest inputs"
1312 )]
1313 async fn execute_in_store(
1314 &self,
1315 store: &mut Store<StoreState>,
1316 capability: &CapabilityId,
1317 input_json: &str,
1318 constraints: &ExecutionConstraints,
1319 operation_timeout: Duration,
1320 mut cancel: Option<tokio::sync::watch::Receiver<bool>>,
1321 ) -> Result<u8, BrokerHostError> {
1322 let clock = store.data().stdio.clock.clone();
1323 let operation = async {
1324 let bindings = self
1325 .pre
1326 .instantiate_async(&mut *store)
1327 .await
1328 .map_err(|source| BrokerHostError::Instantiate {
1329 path: self.source.clone(),
1330 source,
1331 })?;
1332 store.data_mut().instantiations += 1;
1333 bindings
1334 .call_invoke(&mut *store, capability.as_str(), input_json)
1335 .await
1336 .map_err(|source| BrokerHostError::Invoke {
1337 provider: self.manifest.id.clone(),
1338 capability: capability.clone(),
1339 source,
1340 })
1341 };
1342 #[allow(
1343 clippy::map_err_ignore,
1344 reason = "`tokio::time::error::Elapsed` carries only \"deadline has elapsed\"; the \
1345 Timeout variant already names the operation and the budget it exceeded"
1346 )]
1347 let operation_result = tokio::select! {
1348 result = clock.run(operation_timeout, operation) => result,
1349 () = async {
1350 if let Some(signal) = cancel.as_mut() {
1351 loop {
1352 if *signal.borrow_and_update() { break; }
1353 if signal.changed().await.is_err() { std::future::pending::<()>().await; }
1354 }
1355 } else {
1356 std::future::pending::<()>().await;
1357 }
1358 } => return Err(BrokerHostError::PeerDisconnected),
1359 }
1360 .ok_or_else(|| BrokerHostError::Timeout {
1361 operation: format!("invoke {capability}"),
1362 timeout_ms: constraints.timeout_ms,
1363 })?;
1364 if let Some(reason) = store.data().clock.failure() {
1367 return Err(BrokerHostError::HostCallRejected {
1368 provider: self.manifest.id.clone(),
1369 capability: capability.clone(),
1370 reason,
1371 });
1372 }
1373 if let Some(reason) = store.data().http.policy_violation() {
1374 return Err(BrokerHostError::HostCallRejected {
1375 provider: self.manifest.id.clone(),
1376 capability: capability.clone(),
1377 reason: HostCallRejection::Http(reason),
1378 });
1379 }
1380 if store.data().assets.violation().is_some() {
1381 return Err(BrokerHostError::HostCallRejected {
1382 provider: self.manifest.id.clone(),
1383 capability: capability.clone(),
1384 reason: HostCallRejection::AssetCallRejected,
1385 });
1386 }
1387 if let Some(reason) = store.data().storage.violation() {
1388 return Err(BrokerHostError::StorageCallRejected {
1389 provider: self.manifest.id.clone(),
1390 capability: capability.clone(),
1391 reason,
1392 });
1393 }
1394 match operation_result? {
1395 Ok(()) => Ok(0),
1396 Err(0) => {
1397 store.data_mut().stdio.note_zero_status();
1398 Ok(1)
1399 }
1400 Err(status) => Ok(status),
1401 }
1402 }
1403}
1404
1405#[derive(Clone, Debug)]
1406pub struct BrokerProviderRegistry {
1407 providers: Vec<BrokerWasmProvider>,
1408 routes: BTreeMap<CapabilityId, usize>,
1409 storage_host: Option<StorageHost>,
1410 assets: Option<dekopon_http_host::asset::AssetDirectory>,
1411}
1412
1413#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
1414pub struct PrecompileReport {
1415 pub providers: usize,
1416 pub compiled: usize,
1417 pub repaired: usize,
1418 pub removed_files: u64,
1419 pub removed_bytes: u64,
1420}
1421
1422pub async fn precompile(
1423 sources: Vec<LockedProviderSource>,
1424 cwasm_dir: PathBuf,
1425) -> Result<PrecompileReport, BrokerHostError> {
1426 let parent = tracing::Span::current();
1427 offload(move || parent.in_scope(|| precompile_sources(&sources, &cwasm_dir)))
1428 .await
1429 .map_err(|source| BrokerHostError::PrecompileWorker {
1430 source: dekopon_core::TaskOutcome::from(source),
1431 })?
1432}
1433
1434fn precompile_sources(
1435 sources: &[LockedProviderSource],
1436 cwasm_dir: &Path,
1437) -> Result<PrecompileReport, BrokerHostError> {
1438 let engine = host::engine(host::config()).map_err(|error| match error {
1439 EngineError::Engine { source } => BrokerHostError::Engine { source },
1440 })?;
1441 let mut report = PrecompileReport {
1442 providers: sources.len(),
1443 ..PrecompileReport::default()
1444 };
1445 let span = tracing::Span::current();
1446 for locked in sources {
1447 let source = ProviderSource::from(locked.clone());
1448 let (bytes, artifact) = read_source(&source.path, source.expected.as_ref())?;
1449 let cache = cwasm::Cache::new(cwasm_dir.to_owned(), &engine);
1450 let publication = cache
1451 .precompile_component(&engine, &bytes, &artifact.sha256)
1452 .map_err(|source| BrokerHostError::CompiledArtifact {
1453 path: locked.path().to_owned(),
1454 source,
1455 })?;
1456 match publication {
1457 cwasm::Publication::Hit => {}
1458 cwasm::Publication::Compiled => report.compiled += 1,
1459 cwasm::Publication::Repaired => {
1460 report.compiled += 1;
1461 report.repaired += 1;
1462 }
1463 }
1464 span.record("compiled", report.compiled);
1465 span.record("repaired", report.repaired);
1466 }
1467 let cache = cwasm::Cache::new(cwasm_dir.to_owned(), &engine);
1468 let removed = cache
1469 .prune(sources.iter().map(LockedProviderSource::artifact_sha256))
1470 .map_err(|source| BrokerHostError::CacheMaintenance {
1471 path: cwasm_dir.to_owned(),
1472 source,
1473 })?;
1474 report.removed_files = removed.files;
1475 report.removed_bytes = removed.bytes;
1476 span.record("removed_files", report.removed_files);
1477 span.record("removed_bytes", report.removed_bytes);
1478 Ok(report)
1479}
1480
1481impl BrokerProviderRegistry {
1482 pub async fn load<I, P>(sources: I, limits: BrokerHostLimits) -> Result<Self, BrokerHostError>
1483 where
1484 I: IntoIterator<Item = P>,
1485 P: Into<PathBuf>,
1486 {
1487 Self::load_with_storage(sources, limits, None).await
1488 }
1489
1490 pub async fn load_with_storage<I, P>(
1491 sources: I,
1492 limits: BrokerHostLimits,
1493 storage_host: Option<StorageHost>,
1494 ) -> Result<Self, BrokerHostError>
1495 where
1496 I: IntoIterator<Item = P>,
1497 P: Into<PathBuf>,
1498 {
1499 Self::load_with_options(sources, limits, storage_host, &BrokerHostOptions::default()).await
1500 }
1501
1502 pub async fn load_with_options<I, P>(
1503 sources: I,
1504 limits: BrokerHostLimits,
1505 storage_host: Option<StorageHost>,
1506 options: &BrokerHostOptions,
1507 ) -> Result<Self, BrokerHostError>
1508 where
1509 I: IntoIterator<Item = P>,
1510 P: Into<PathBuf>,
1511 {
1512 Self::load_sources(
1513 sources
1514 .into_iter()
1515 .map(|source| ProviderSource::from(source.into())),
1516 limits,
1517 storage_host,
1518 options,
1519 )
1520 .await
1521 }
1522
1523 pub async fn load_locked_with_options<I>(
1524 sources: I,
1525 limits: BrokerHostLimits,
1526 storage_host: Option<StorageHost>,
1527 options: &BrokerHostOptions,
1528 ) -> Result<Self, BrokerHostError>
1529 where
1530 I: IntoIterator<Item = LockedProviderSource>,
1531 {
1532 Self::load_sources(
1533 sources.into_iter().map(ProviderSource::from),
1534 limits,
1535 storage_host,
1536 options,
1537 )
1538 .await
1539 }
1540
1541 async fn load_sources<I>(
1542 sources: I,
1543 limits: BrokerHostLimits,
1544 storage_host: Option<StorageHost>,
1545 options: &BrokerHostOptions,
1546 ) -> Result<Self, BrokerHostError>
1547 where
1548 I: IntoIterator<Item = ProviderSource>,
1549 {
1550 let sources = sources.into_iter().collect::<Vec<_>>();
1551 let span = tracing::info_span!(
1552 "provider.registry_load",
1553 providers = sources.len(),
1554 mmap = options.cwasm_dir.is_some(),
1555 elapsed_us = tracing::field::Empty,
1556 outcome = tracing::field::Empty
1557 );
1558 let started = Instant::now();
1559 let result = async {
1560 if sources.is_empty() {
1561 return Err(BrokerHostError::NoProviders);
1562 }
1563 let runtime = Arc::new(Runtime::new(limits, options)?);
1564 let mut providers = Vec::with_capacity(sources.len());
1565 let mut scan = ConflictScan::new();
1566 for source in sources {
1567 let task_runtime = Arc::clone(&runtime);
1568 let task_source = source.clone();
1569 let span = tracing::Span::current();
1570 let compiling = offload(move || {
1571 span.in_scope(|| compile_component(&task_runtime, task_source))
1572 });
1573 let compiled = compiling.await.map_err(|join| BrokerHostError::Compile {
1574 path: source.path,
1575 source: wasmtime::Error::new(dekopon_core::TaskOutcome::from(join)),
1576 })??;
1577 let provider = BrokerWasmProvider::load(Arc::clone(&runtime), compiled).await?;
1578 scan.record(&provider.manifest, providers.len());
1579 providers.push(provider);
1580 }
1581
1582 let routes = scan
1583 .finish()
1584 .map_err(|report| BrokerHostError::ConflictingProviders {
1585 report: Box::new(report),
1586 })?;
1587 Ok(Self {
1588 providers,
1589 routes,
1590 storage_host,
1591 assets: None,
1592 })
1593 }
1594 .instrument(span.clone())
1595 .await;
1596 let elapsed_us = cwasm::micros(started);
1597 let outcome = if result.is_ok() {
1598 "succeeded"
1599 } else {
1600 "failed"
1601 };
1602 span.record("elapsed_us", elapsed_us);
1603 span.record("outcome", outcome);
1604 span.in_scope(|| tracing::info!(elapsed_us, outcome, "provider.registry.loaded"));
1605 result
1606 }
1607
1608 #[must_use]
1609 pub fn command_words_by_provider(&self) -> Vec<(&ProviderId, &[String])> {
1610 self.providers
1611 .iter()
1612 .filter(|provider| !provider.manifest.command_words.is_empty())
1613 .map(|provider| {
1614 (
1615 &provider.manifest.id,
1616 provider.manifest.command_words.as_slice(),
1617 )
1618 })
1619 .collect()
1620 }
1621
1622 #[must_use]
1623 pub fn command_word_help(&self) -> BTreeMap<String, String> {
1624 let mut pages = BTreeMap::new();
1625 for provider in &self.providers {
1626 pages.extend(
1627 provider
1628 .command_word_help
1629 .iter()
1630 .map(|(word, page)| (word.clone(), page.clone())),
1631 );
1632 }
1633 pages
1634 }
1635
1636 #[must_use]
1637 pub fn command_words(&self) -> Vec<String> {
1638 let mut words = self
1639 .providers
1640 .iter()
1641 .flat_map(|provider| provider.manifest.command_words.iter().cloned())
1642 .collect::<Vec<_>>();
1643 words.sort();
1644 words.dedup();
1645 words
1646 }
1647
1648 pub async fn run_command(
1649 &self,
1650 word: &str,
1651 argv: &[String],
1652 stdin_piped: bool,
1653 ) -> Result<CommandRunOutcome, BrokerHostError> {
1654 let provider = self
1655 .providers
1656 .iter()
1657 .find(|provider| {
1658 provider
1659 .manifest
1660 .command_words
1661 .iter()
1662 .any(|candidate| candidate == word)
1663 })
1664 .ok_or_else(|| BrokerHostError::UnknownCommandWord {
1665 word: word.to_owned(),
1666 })?;
1667 let span = tracing::info_span!(
1668 "provider.run_command",
1669 provider = %provider.manifest.id,
1670 word,
1671 command.export = command_export_name(&provider.command_export),
1672 command.arguments = tracing::field::Empty,
1673 command.arguments.bytes = tracing::field::Empty,
1674 command.stdin.piped = stdin_piped,
1675 command.output = tracing::field::Empty,
1676 command.output.bytes = tracing::field::Empty,
1677 stores = tracing::field::Empty,
1678 instantiations = tracing::field::Empty,
1679 fuel.consumed = tracing::field::Empty,
1680 );
1681 let arguments = Value::Array(argv.iter().cloned().map(Value::String).collect()).to_string();
1682 span.record(
1683 "command.arguments",
1684 &*dekopon_core::bounded_attribute(&arguments),
1685 );
1686 span.record("command.arguments.bytes", arguments.len());
1687 let json = provider
1688 .run_command(argv, stdin_piped)
1689 .instrument(span.clone())
1690 .await?;
1691 span.record("command.output", &*dekopon_core::bounded_attribute(&json));
1692 span.record("command.output.bytes", json.len());
1693 serde_json::from_str::<CommandRunOutcome>(&json).map_err(|source| {
1694 BrokerHostError::InvalidCommandRun {
1695 provider: provider.manifest.id.clone(),
1696 source,
1697 }
1698 })
1699 }
1700
1701 pub fn manifests(&self) -> impl ExactSizeIterator<Item = &ProviderManifest> {
1702 self.providers.iter().map(|provider| &provider.manifest)
1703 }
1704
1705 pub fn loaded_provider_metadata(
1706 &self,
1707 ) -> impl ExactSizeIterator<Item = LoadedProviderMetadata> + '_ {
1708 self.providers
1709 .iter()
1710 .map(|provider| LoadedProviderMetadata {
1711 source: provider.source.clone(),
1712 artifact_bytes: provider.artifact_bytes,
1713 artifact_sha256: provider.artifact_sha256.clone(),
1714 manifest: provider.manifest.clone(),
1715 })
1716 }
1717
1718 #[must_use]
1719 pub fn host_limits(&self) -> &BrokerHostLimits {
1720 &self
1721 .providers
1722 .first()
1723 .expect("a registry is constructed with at least one provider")
1724 .runtime
1725 .limits
1726 }
1727
1728 pub fn set_assets(&mut self, directory: dekopon_http_host::asset::AssetDirectory) {
1729 self.assets = Some(directory);
1730 }
1731
1732 #[must_use]
1733 pub fn http_destination_options(&self) -> HttpDestinationOptions<'_> {
1734 let runtime = &self
1735 .providers
1736 .first()
1737 .expect("a registry is constructed with at least one provider")
1738 .runtime;
1739 HttpDestinationOptions {
1740 plaintext_hosts: &runtime.plaintext_hosts,
1741 extra_ca_bundles: &runtime.extra_ca_bundles,
1742 non_public_https: &runtime.non_public_https,
1743 }
1744 }
1745
1746 #[must_use]
1747 pub fn storage_host(&self) -> Option<StorageHost> {
1748 self.storage_host.clone()
1749 }
1750
1751 #[must_use]
1752 pub fn capability(
1753 &self,
1754 capability: &CapabilityId,
1755 ) -> Option<(&ProviderId, &ProviderCapability)> {
1756 let provider = &self.providers[*self.routes.get(capability)?];
1757 let capability = provider
1758 .manifest
1759 .capabilities
1760 .iter()
1761 .find(|candidate| &candidate.id == capability)
1762 .expect("routes originate from validated provider manifests");
1763 Some((&provider.manifest.id, capability))
1764 }
1765
1766 pub fn capabilities(&self) -> impl Iterator<Item = (&ProviderId, &ProviderCapability)> {
1767 self.routes.iter().map(|(capability_id, provider_index)| {
1768 let provider = &self.providers[*provider_index];
1769 let capability = provider
1770 .manifest
1771 .capabilities
1772 .iter()
1773 .find(|candidate| &candidate.id == capability_id)
1774 .expect("routes originate from validated provider manifests");
1775 (&provider.manifest.id, capability)
1776 })
1777 }
1778
1779 pub fn validate_constraints(
1780 &self,
1781 constraints: &ExecutionConstraints,
1782 ) -> Result<(), BrokerHostError> {
1783 if constraints.storage.is_some() && self.storage_host.is_none() {
1784 return Err(BrokerHostError::StorageDisabled);
1785 }
1786 let runtime = &self
1787 .providers
1788 .first()
1789 .expect("a registry is constructed with at least one provider")
1790 .runtime;
1791 validate_authorized_constraints(constraints, &runtime.limits)
1792 }
1793
1794 pub async fn invoke(
1795 &self,
1796 authorized: AuthorizedInvocation,
1797 credential: Option<BoundCredential>,
1798 assets: asset::AssetInputs,
1799 ) -> Result<BrokerInvocationOutput, BrokerInvocationFailure> {
1800 self.invoke_with_storage(
1801 authorized,
1802 credential,
1803 None,
1804 HttpInvocation::default(),
1805 assets,
1806 )
1807 .await
1808 }
1809
1810 pub async fn invoke_with_storage(
1811 &self,
1812 authorized: AuthorizedInvocation,
1813 credential: Option<BoundCredential>,
1814 storage_grant: Option<StorageGrant>,
1815 invocation: HttpInvocation,
1816 assets: asset::AssetInputs,
1817 ) -> Result<BrokerInvocationOutput, BrokerInvocationFailure> {
1818 self.invoke_authorized(
1819 authorized,
1820 credential,
1821 storage_grant,
1822 invocation.slots,
1823 invocation.authorizer,
1824 assets,
1825 None,
1826 )
1827 .await
1828 }
1829
1830 pub async fn invoke_with_test_imports(
1831 &self,
1832 authorized: AuthorizedInvocation,
1833 slots: ChatSlotValues,
1834 assets: asset::AssetInputs,
1835 test_imports: Option<&TestImports>,
1836 ) -> Result<BrokerInvocationOutput, BrokerInvocationFailure> {
1837 #[cfg(feature = "native-test")]
1838 let credential = test_imports.and_then(|imports| imports.credential.clone());
1839 #[cfg(not(feature = "native-test"))]
1840 let credential = None;
1841 self.invoke_authorized(
1842 authorized,
1843 credential,
1844 None,
1845 slots,
1846 None,
1847 assets,
1848 test_imports,
1849 )
1850 .await
1851 }
1852
1853 #[expect(
1854 clippy::too_many_arguments,
1855 reason = "the authorization, credential, storage grant and chat slots are separate grants \
1856 the broker hands over once each"
1857 )]
1858 async fn invoke_authorized(
1859 &self,
1860 authorized: AuthorizedInvocation,
1861 credential: Option<BoundCredential>,
1862 storage_grant: Option<StorageGrant>,
1863 slots: ChatSlotValues,
1864 request_authorizer: Option<RequestAuthorizer>,
1865 assets: asset::AssetInputs,
1866 test_imports: Option<&TestImports>,
1867 ) -> Result<BrokerInvocationOutput, BrokerInvocationFailure> {
1868 let storage_backed = authorized.constraints().storage.is_some();
1869 let proposal = authorized.proposal();
1870 let provider_index = self
1871 .routes
1872 .get(&proposal.capability)
1873 .copied()
1874 .ok_or_else(|| BrokerHostError::UnknownCapability {
1875 capability: proposal.capability.clone(),
1876 })?;
1877 let provider = &self.providers[provider_index];
1878 if &provider.manifest.id != authorized.provider() {
1879 return Err(BrokerHostError::AuthorizedProviderMismatch {
1880 capability: proposal.capability.clone(),
1881 authorized: authorized.provider().clone(),
1882 routed: provider.manifest.id.clone(),
1883 }
1884 .into());
1885 }
1886 let secret_grant = authorized.constraints().secret_use.as_ref();
1887 if credential
1888 .as_ref()
1889 .is_some_and(|credential| !credential.matches_secret_grant(secret_grant))
1890 || (secret_grant.is_some() && credential.is_none())
1891 {
1892 return Err(BrokerHostError::SecretCredentialMismatch.into());
1893 }
1894 let storage_transaction = match (&authorized.constraints().storage, storage_grant) {
1895 (None, None) => None,
1896 (None, Some(_)) => return Err(BrokerHostError::UnexpectedStorageGrant.into()),
1897 (Some(_), None) => return Err(BrokerHostError::MissingStorageGrant.into()),
1898 #[allow(
1899 clippy::map_err_ignore,
1900 reason = "an offload join failure distinguishes only a panic from \
1901 runtime cancellation, and the panic hook has already printed the panic \
1902 with its location; `storage::StorageState::call` classes the same \
1903 failure as `Io` for the same reason"
1904 )]
1905 (Some(constraints), Some(grant)) => {
1906 if grant.invocation() != &proposal.id
1907 || grant.capability() != &proposal.capability
1908 || grant.provider() != authorized.provider()
1909 || grant.interface() != constraints.interface
1910 || grant.access() != constraints.access
1911 || grant.scope() != constraints.scope
1912 || grant.shared_namespace() != constraints.namespace.as_ref()
1913 {
1914 return Err(BrokerHostError::StorageGrantMismatch.into());
1915 }
1916 let host = self
1917 .storage_host
1918 .as_ref()
1919 .ok_or(BrokerHostError::StorageDisabled)?
1920 .clone();
1921 Some(
1922 offload(move || host.begin(grant))
1923 .await
1924 .map_err(|_| BrokerHostError::Storage {
1925 source: dekopon_storage_host::StorageHostError::Io,
1926 })?
1927 .map_err(|source| BrokerHostError::Storage { source })?,
1928 )
1929 }
1930 };
1931 let span = tracing::info_span!(
1932 "provider.invoke",
1933 capability = %proposal.capability,
1934 provider = %provider.manifest.id,
1935 input = tracing::field::Empty,
1936 input.bytes = tracing::field::Empty,
1937 stdin.bytes = tracing::field::Empty,
1938 stdin.prefix = tracing::field::Empty,
1939 stdout.bytes = tracing::field::Empty,
1940 stdout.prefix = tracing::field::Empty,
1941 stderr.bytes = tracing::field::Empty,
1942 stderr.prefix = tracing::field::Empty,
1943 storage = tracing::field::Empty,
1944 stores = tracing::field::Empty,
1945 instantiations = tracing::field::Empty,
1946 fuel.consumed = tracing::field::Empty,
1947 );
1948 let input = dekopon_core::bounded_display(&proposal.input);
1949 span.record("input", tracing::field::display(input.text()));
1950 span.record("input.bytes", input.bytes());
1951 if storage_backed {
1952 span.record("storage", true);
1953 }
1954 provider
1955 .invoke(
1956 test_imports,
1957 &proposal.capability,
1958 &proposal.input,
1959 authorized.constraints(),
1960 credential,
1961 slots,
1962 request_authorizer,
1963 storage_transaction,
1964 assets,
1965 test_imports
1966 .and_then(|imports| imports.assets.as_ref())
1967 .or(self.assets.as_ref())
1968 .cloned(),
1969 )
1970 .instrument(span)
1971 .await
1972 }
1973}
1974
1975fn record_stream_trace(stream: &stdio::StdioState) {
1976 let span = tracing::Span::current();
1977 for (name, trace) in [
1978 ("stdin", &stream.stdin_trace),
1979 ("stdout", &stream.stdout_trace),
1980 ("stderr", &stream.stderr_trace),
1981 ] {
1982 span.record(format!("{name}.bytes").as_str(), trace.bytes);
1983 span.record(format!("{name}.prefix").as_str(), trace.prefix().as_str());
1984 }
1985}
1986
1987fn record_store_outcome(store: &mut Store<StoreState>, supplied: u64) {
1988 let span = tracing::Span::current();
1989 span.record("instantiations", store.data().instantiations);
1990 let remaining = store.get_fuel().ok();
1991 if let Some(remaining) = remaining {
1992 span.record("fuel.consumed", supplied.saturating_sub(remaining));
1993 }
1994 store.data_mut().limits.record_remaining_fuel(remaining);
1995}
1996
1997const fn command_export_name(export: &CommandExport) -> &'static str {
1998 match export {
1999 CommandExport::Present => RUN_COMMAND_EXPORT,
2000 CommandExport::Absent | CommandExport::Mismatched { .. } => "none",
2001 }
2002}
2003
2004fn bounded_command_word_help(mut page: String) -> String {
2005 if page.len() <= MAX_COMMAND_WORD_HELP_BYTES {
2006 return page;
2007 }
2008 let mut end = MAX_COMMAND_WORD_HELP_BYTES;
2009 while !page.is_char_boundary(end) {
2010 end -= 1;
2011 }
2012 page.truncate(end);
2013 page.push_str(&format!("\n[--help truncated at {end} bytes]"));
2014 page
2015}
2016
2017async fn describe_component(
2018 runtime: &Runtime,
2019 pre: &bindings::ProviderPre<StoreState>,
2020 source: &Path,
2021 provider: Option<&ProviderId>,
2022) -> Result<String, BrokerHostError> {
2023 let operation_timeout = runtime.limits.max_timeout;
2024 let http = HttpState::describe(runtime.http_ceilings(), operation_timeout)
2025 .map_err(|source| BrokerHostError::HttpConfiguration { source })?;
2026 let mut store = runtime.store_for_provider(
2027 provider
2028 .map(ProviderId::as_str)
2029 .unwrap_or_else(|| source.to_str().unwrap_or("unknown-provider")),
2030 http,
2031 storage::StorageState::disabled(),
2032 ClockState::describe(),
2033 SettingsState::describe(),
2034 )?;
2035 let operation = async {
2036 let bindings = pre.instantiate_async(&mut store).await.map_err(|error| {
2037 BrokerHostError::Instantiate {
2038 path: source.to_path_buf(),
2039 source: error,
2040 }
2041 })?;
2042 store.data_mut().instantiations += 1;
2043 bindings
2044 .call_describe(&mut store)
2045 .await
2046 .map_err(|error| BrokerHostError::Describe {
2047 path: source.to_path_buf(),
2048 source: error,
2049 })
2050 };
2051 #[allow(
2052 clippy::map_err_ignore,
2053 reason = "`tokio::time::error::Elapsed` carries only \"deadline has elapsed\"; the Timeout \
2054 variant already names the operation and the budget it exceeded"
2055 )]
2056 let manifest =
2057 timeout(operation_timeout, operation)
2058 .await
2059 .map_err(|_| BrokerHostError::Timeout {
2060 operation: format!("describe {}", source.display()),
2061 timeout_ms: operation_timeout.as_millis() as u64,
2062 });
2063 record_store_outcome(&mut store, runtime.limits.fuel);
2064 if store.data().clock.attempted() || store.data().settings.attempted() {
2066 return Err(BrokerHostError::DescribeUsedHostImport {
2067 path: source.to_path_buf(),
2068 });
2069 }
2070 let manifest = manifest??;
2071 if store.data().http.attempted()
2072 || store.data().storage.attempted()
2073 || store.data().assets.attempted()
2074 {
2075 return Err(BrokerHostError::DescribeUsedHostImport {
2076 path: source.to_path_buf(),
2077 });
2078 }
2079 Ok(manifest)
2080}
2081
2082fn invocation_budget_failure(
2083 error: BrokerHostError,
2084 refusal: Option<memory::BudgetRefusal>,
2085) -> BrokerHostError {
2086 match refusal {
2087 Some(refusal) => BrokerHostError::MemoryBudgetExhausted {
2088 requested: refusal.requested,
2089 maximum: refusal.maximum,
2090 },
2091 None => error,
2092 }
2093}
2094
2095fn validate_limits(limits: &BrokerHostLimits) -> Result<(), BrokerHostError> {
2096 host::validate_limits(
2097 &limits.store_bounds(),
2098 &[
2099 ("max_input_bytes", limits.max_input_bytes as u128),
2100 ("max_output_bytes", limits.max_output_bytes as u128),
2101 ("max_http_requests", u128::from(limits.max_http_requests)),
2102 (
2103 "max_http_request_bytes",
2104 u128::from(limits.max_http_request_bytes),
2105 ),
2106 (
2107 "max_http_response_bytes",
2108 u128::from(limits.max_http_response_bytes),
2109 ),
2110 ("max_http_headers", limits.max_http_headers as u128),
2111 (
2112 "max_http_header_bytes",
2113 limits.max_http_header_bytes as u128,
2114 ),
2115 ("fuel", u128::from(limits.fuel)),
2116 ("max_timeout", limits.max_timeout.as_nanos()),
2117 ],
2118 )
2119 .map_err(|zero| BrokerHostError::InvalidLimit { name: zero.name })
2120}
2121
2122fn validate_authorized_constraints(
2123 constraints: &ExecutionConstraints,
2124 limits: &BrokerHostLimits,
2125) -> Result<(), BrokerHostError> {
2126 if constraints.timeout_ms == 0
2127 || Duration::from_millis(constraints.timeout_ms) > limits.max_timeout
2128 {
2129 return Err(BrokerHostError::AuthorizationExceedsHostLimit {
2130 field: "timeout_ms",
2131 });
2132 }
2133 if constraints.http.is_some() && constraints.storage.is_some() {
2134 return Err(BrokerHostError::MixedHostAuthorization);
2135 }
2136 if let Some(secret) = &constraints.secret_use {
2137 secret
2138 .validate()
2139 .map_err(|source| BrokerHostError::InvalidSecretAuthorization { source })?;
2140 let Some(http) = &constraints.http else {
2141 return Err(BrokerHostError::SecretAuthorizationExceedsHttp);
2142 };
2143 if secret.max_injections > http.max_requests
2144 || secret
2145 .allowed_hosts
2146 .iter()
2147 .any(|host| !http.allowed_hosts.contains(host))
2148 || secret
2149 .allowed_methods
2150 .iter()
2151 .any(|method| !http.allowed_methods.contains(method))
2152 {
2153 return Err(BrokerHostError::SecretAuthorizationExceedsHttp);
2154 }
2155 }
2156 if let Some(http) = &constraints.http {
2157 if http.allowed_hosts.is_empty()
2158 || http.allowed_methods.is_empty()
2159 || http.max_requests == 0
2160 || http.max_request_bytes == 0
2161 || http.max_response_bytes == 0
2162 {
2163 return Err(BrokerHostError::InvalidHttpAuthorization);
2164 }
2165 if http.max_requests > limits.max_http_requests
2166 || http.max_request_bytes > limits.max_http_request_bytes
2167 || http.max_response_bytes > limits.max_http_response_bytes
2168 {
2169 return Err(BrokerHostError::AuthorizationExceedsHostLimit { field: "http" });
2170 }
2171 }
2172 Ok(())
2173}
2174
2175fn validate_manifest(manifest: &ProviderManifest, source: &Path) -> Result<(), BrokerHostError> {
2176 host::validate_manifest(manifest)
2177 .map_err(|rejection| invalid_manifest(source, rejection.to_string()))
2178}
2179
2180fn invalid_manifest(source: &Path, message: impl Into<String>) -> BrokerHostError {
2181 BrokerHostError::Manifest {
2182 path: source.to_path_buf(),
2183 message: message.into(),
2184 }
2185}
2186
2187#[derive(Debug, Error)]
2188pub enum BrokerHostError {
2189 #[error("broker peer disconnected during invocation")]
2190 PeerDisconnected,
2191 #[error("over-budget: broker asset disk capacity exhausted")]
2192 AssetOverBudget,
2193 #[error("invalid invocation assets")]
2194 AssetInput {
2195 #[source]
2196 source: asset::AssetAdmissionError,
2197 },
2198
2199 #[error("at least one broker provider component is required")]
2200 NoProviders,
2201 #[error("broker host limit {name} must be greater than zero")]
2202 InvalidLimit { name: &'static str },
2203 #[error("authorization constraint {field} exceeds the broker host ceiling")]
2204 AuthorizationExceedsHostLimit { field: &'static str },
2205 #[error("HTTP authorization must contain destinations, methods, and positive limits")]
2206 InvalidHttpAuthorization,
2207 #[error("HTTP and storage authority cannot coexist in one capability")]
2208 MixedHostAuthorization,
2209 #[error("secret-use authorization is invalid")]
2210 InvalidSecretAuthorization {
2211 #[source]
2212 source: dekopon_capability::SecretUseGrantError,
2213 },
2214 #[error("secret-use authorization exceeds HTTP authority")]
2215 SecretAuthorizationExceedsHttp,
2216 #[error("resolved secret credential does not match authorized secret use")]
2217 SecretCredentialMismatch,
2218 #[error("provider storage is disabled")]
2219 StorageDisabled,
2220 #[error("authorized storage invocation is missing its storage grant")]
2221 MissingStorageGrant,
2222 #[error("storage grant accompanied an invocation with no storage authority")]
2223 UnexpectedStorageGrant,
2224 #[error("storage grant does not match authorized invocation")]
2225 StorageGrantMismatch,
2226 #[error("broker provider storage failed")]
2227 Storage {
2228 #[source]
2229 source: dekopon_storage_host::StorageHostError,
2230 },
2231 #[error("could not initialize the bounded HTTP execution context")]
2232 HttpConfiguration {
2233 #[source]
2234 source: dekopon_http_host::ConfigurationError,
2235 },
2236 #[error("could not initialize the broker Wasmtime engine")]
2237 Engine {
2238 #[source]
2239 source: wasmtime::Error,
2240 },
2241 #[error("could not initialize a bounded broker Wasmtime store")]
2242 Store {
2243 #[source]
2244 source: wasmtime::Error,
2245 },
2246 #[error("could not register broker host interfaces")]
2247 Linker {
2248 #[source]
2249 source: wasmtime::Error,
2250 },
2251 #[error("locked provider artifact is {size} bytes; maximum is {maximum}")]
2252 InvalidArtifactSize { size: u64, maximum: u64 },
2253 #[error("locked provider artifact digest must be sixty-four lowercase hexadecimal characters")]
2254 InvalidArtifactDigest,
2255 #[error(
2256 "broker provider component {} is {actual} bytes; maximum is {maximum}",
2257 path.display()
2258 )]
2259 ArtifactTooLarge {
2260 path: PathBuf,
2261 actual: u64,
2262 maximum: u64,
2263 },
2264 #[error(
2265 "broker provider component {} is {actual} bytes; provider lock expects {expected}",
2266 path.display()
2267 )]
2268 ArtifactSizeMismatch {
2269 path: PathBuf,
2270 expected: u64,
2271 actual: u64,
2272 },
2273 #[error(
2274 "broker provider component {} has SHA-256 {actual}; provider lock expects {expected}",
2275 path.display()
2276 )]
2277 ArtifactDigestMismatch {
2278 path: PathBuf,
2279 expected: String,
2280 actual: String,
2281 },
2282 #[error(
2283 "broker provider component {} describes provider {actual}; provider lock expects {expected}",
2284 path.display()
2285 )]
2286 ProviderIdentityMismatch {
2287 path: PathBuf,
2288 expected: ProviderId,
2289 actual: ProviderId,
2290 },
2291 #[error("could not inspect broker provider artifact {}", path.display())]
2292 ArtifactMetadata {
2293 path: PathBuf,
2294 #[source]
2295 source: std::io::Error,
2296 },
2297 #[error("no compiled artifact for {} under engine {engine_key}; delete the pod; `provider precompile` repairs it, or set compileOnLoad: true", path.display())]
2298 CompiledArtifactMissing { path: PathBuf, engine_key: String },
2299 #[error("compiled artifact load failed for {}; delete the pod; `provider precompile` repairs it, or set compileOnLoad: true", path.display())]
2300 CompiledArtifact {
2301 path: PathBuf,
2302 #[source]
2303 source: wasmtime::Error,
2304 },
2305 #[error("could not maintain the cwasm cache at {}", path.display())]
2306 CacheMaintenance {
2307 path: PathBuf,
2308 #[source]
2309 source: wasmtime::Error,
2310 },
2311 #[error("precompile worker failed")]
2312 PrecompileWorker {
2313 #[source]
2314 source: dekopon_core::TaskOutcome,
2315 },
2316 #[error(
2317 "guest memory growth exceeds the {maximum}-byte aggregate guest memory ceiling; \
2318 another {requested} bytes cannot be admitted"
2319 )]
2320 MemoryBudgetExhausted { requested: usize, maximum: usize },
2321 #[error("could not compile broker provider component {}", path.display())]
2322 Compile {
2323 path: PathBuf,
2324 #[source]
2325 source: wasmtime::Error,
2326 },
2327 #[error("could not instantiate broker provider component {}", path.display())]
2328 Instantiate {
2329 path: PathBuf,
2330 #[source]
2331 source: wasmtime::Error,
2332 },
2333 #[error("provider component {} attempted a host import during describe", path.display())]
2334 DescribeUsedHostImport { path: PathBuf },
2335 #[error("{report}")]
2336 ConflictingProviders { report: Box<ProviderConflicts> },
2337 #[error("provider {provider} returned an unreadable command run outcome")]
2338 InvalidCommandRun {
2339 provider: ProviderId,
2340 #[source]
2341 source: serde_json::Error,
2342 },
2343 #[error("no loaded provider declares the command word {word:?}")]
2344 UnknownCommandWord { word: String },
2345 #[error(
2346 "provider {provider} declares command words but component {} exports no run-command; \
2347 rebuild it against the dekopon:provider/provider-cli world",
2348 path.display()
2349 )]
2350 MissingCommandExport { provider: ProviderId, path: PathBuf },
2351 #[error(
2352 "provider {provider} exports run-command from component {} as {found}, not the function \
2353 the dekopon:provider package declares",
2354 path.display()
2355 )]
2356 CommandExportSignature {
2357 provider: ProviderId,
2358 path: PathBuf,
2359 found: String,
2360 },
2361 #[error("command input for provider {provider} is {length} bytes; broker maximum is {maximum}")]
2362 CommandInputTooLarge {
2363 provider: ProviderId,
2364 length: usize,
2365 maximum: usize,
2366 },
2367 #[error("provider {provider} failed while running a command word")]
2368 RunCommand {
2369 provider: ProviderId,
2370 #[source]
2371 source: wasmtime::Error,
2372 },
2373 #[error(
2374 "provider component {} attempted a host import during a command run",
2375 path.display()
2376 )]
2377 RunCommandUsedHostImport { path: PathBuf },
2378 #[error("broker provider component {} failed while describing itself", path.display())]
2379 Describe {
2380 path: PathBuf,
2381 #[source]
2382 source: wasmtime::Error,
2383 },
2384 #[error("broker provider component {} returned an invalid manifest", path.display())]
2385 InvalidManifest {
2386 path: PathBuf,
2387 #[source]
2388 source: serde_json::Error,
2389 },
2390 #[error("broker provider component {} has an invalid manifest: {message}", path.display())]
2391 Manifest { path: PathBuf, message: String },
2392 #[error("no broker provider implements authorized capability {capability}")]
2393 UnknownCapability { capability: CapabilityId },
2394 #[error(
2395 "authorization selected provider {authorized} for {capability}, but route selects {routed}"
2396 )]
2397 AuthorizedProviderMismatch {
2398 capability: CapabilityId,
2399 authorized: ProviderId,
2400 routed: ProviderId,
2401 },
2402 #[error("broker provider {provider} does not implement capability {capability}")]
2403 ProviderDoesNotImplement {
2404 provider: ProviderId,
2405 capability: CapabilityId,
2406 },
2407 #[error("input for broker capability {capability} must be a JSON object")]
2408 InputNotObject { capability: CapabilityId },
2409 #[error("could not serialize broker provider input")]
2410 SerializeInput {
2411 #[source]
2412 source: serde_json::Error,
2413 },
2414 #[error("input for {capability} is {length} bytes; broker maximum is {maximum}")]
2415 InputTooLarge {
2416 capability: CapabilityId,
2417 length: usize,
2418 maximum: usize,
2419 },
2420 #[error("broker provider {provider} returned {length} bytes; maximum is {maximum}")]
2421 OutputTooLarge {
2422 provider: String,
2423 length: usize,
2424 maximum: usize,
2425 },
2426 #[error("broker provider operation {operation} exceeded {timeout_ms} ms")]
2427 Timeout { operation: String, timeout_ms: u64 },
2428 #[error("broker rejected host call {reason} from provider {provider} capability {capability}")]
2429 HostCallRejected {
2430 provider: ProviderId,
2431 capability: CapabilityId,
2432 reason: HostCallRejection,
2433 },
2434 #[error(
2435 "broker rejected storage call {reason} from provider {provider} capability {capability}"
2436 )]
2437 StorageCallRejected {
2438 provider: ProviderId,
2439 capability: CapabilityId,
2440 reason: &'static str,
2441 },
2442 #[error("broker provider {provider} failed while invoking {capability}")]
2443 Invoke {
2444 provider: ProviderId,
2445 capability: CapabilityId,
2446 #[source]
2447 source: wasmtime::Error,
2448 },
2449 #[error("broker provider {provider} exited with status {status} from {capability}")]
2450 ProviderFailure {
2451 provider: ProviderId,
2452 capability: CapabilityId,
2453 status: u8,
2454 stderr: String,
2455 },
2456 #[error("broker could not admit an invocation stream")]
2457 StdioAdmission {
2458 #[source]
2459 source: stdio::StdioAdmissionError,
2460 },
2461}
2462
2463#[cfg(test)]
2464mod tests {
2465 use super::{MAX_COMMAND_WORD_HELP_BYTES, bounded_command_word_help};
2466 use wasmtime::ResourceLimiter as _;
2467
2468 #[test]
2469 fn failed_invocation_with_budget_refusal_maps_to_host_memory_budget() {
2470 let mut limiter = super::memory::MemoryLimiter::new(
2471 super::host::StoreLimits {
2472 max_memory_bytes: 4 * 65_536,
2473 ..Default::default()
2474 },
2475 Some(std::sync::Arc::new(super::memory::MemoryBudget::new(
2476 65_536,
2477 ))),
2478 "probe",
2479 );
2480 assert!(!limiter.memory_growing(0, 2 * 65_536, None).unwrap());
2481 let mapped = super::invocation_budget_failure(
2482 super::BrokerHostError::Store {
2483 source: wasmtime::Error::msg("synthetic trap"),
2484 },
2485 limiter.refusal(),
2486 );
2487 assert!(matches!(
2488 mapped,
2489 super::BrokerHostError::MemoryBudgetExhausted {
2490 requested: 131_072,
2491 maximum: 65_536
2492 }
2493 ));
2494 }
2495
2496 #[test]
2497 fn a_page_is_passed_through_at_the_bound_and_cut_at_a_character_boundary_past_it() {
2498 let at_bound = "x".repeat(MAX_COMMAND_WORD_HELP_BYTES);
2499 assert_eq!(bounded_command_word_help(at_bound.clone()), at_bound);
2500
2501 let past_bound = "€".repeat(700);
2504 let bounded = bounded_command_word_help(past_bound.clone());
2505 assert_eq!(&bounded[..2046], &past_bound[..2046]);
2506 assert!(bounded[2046..].starts_with("\n[--help truncated at 2046 bytes]"));
2507 }
2508}