Skip to main content

dekopon_broker_host/
lib.rs

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
319// Bounds one word's cached `--help` page: enough for a top-level usage/subcommand listing, not
320// enough for a runaway component to bloat every session's baked-in prompt prefix.
321const 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    // Reads once, capped one byte over the limit, since a second read can't prove it matches what
787    // Cranelift consumed and concurrent growth could otherwise allocate unbounded memory.
788    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        // Checked at load from the component's own type, so a manifest promising command words it
908        // can't run fails immediately rather than mid-session on first use.
909        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        // Check refused host reads before the trap surfaces or their cause is lost.
1032        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        // Reads the actual initial fuel balance rather than assuming the configured budget applies,
1226        // since an unavailable observation must not be treated as zero usage.
1227        let initial_fuel = store.get_fuel().ok();
1228        store
1229            .data_mut()
1230            .limits
1231            .observe_invocation(capability.as_str(), initial_fuel);
1232        // The store outlives the guest on every path, including a timeout dropping the operation
1233        // future, so dispatched-call evidence is harvested exactly once regardless of outcome.
1234        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        // A caught, typed disk failure stays terminal even if later guest work times out or is
1250        // refused; never infer exhaustion from cancellation itself.
1251        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        // Host policy violations win even if the guest catches the error or a failing destructor
1365        // turns it into a trap; check policy before trusting the guest's result.
1366        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    // Check refused host reads before the trap surfaces or their cause is lost.
2065    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        // Each "€" is three bytes, so byte 2048 falls mid-character; the cut lands two bytes
2502        // earlier, at the last complete character, rather than splitting one.
2503        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}