Skip to content
calternal docs

calternal_plugin::media_sandbox

Process controls shared by Plugins that decode untrusted media.

Native tools must still be launched through calternal-media-sandbox. These helpers bound process groups and streams for Files and Voice (#619, #779, #852). Startup and retry diagnostics retain fixed categories and at most 4 KiB (#988). Document launcher failures remain retryable (#1045, DESIGN §39). One bounded blocking sink keeps filesystem callbacks off Tokio workers.

Source: crates/calternal-plugin/src/media_sandbox.rs

Structs

Section titled “Structs”

MediaHealth

Section titled “MediaHealth”
pub struct MediaHealth

Startup decode result and later infrastructure failures, without native stderr (#988).

Fields

  • pub available: Option<bool>: None until the startup decode completes.
  • pub failure: Option<MediaFailure>

Implements: Clone, Debug, Default, Serialize, ToSchema

Source: crates/calternal-plugin/src/media_sandbox.rs:102

Enums

Section titled “Enums”

MediaFailure

Section titled “MediaFailure”
pub enum MediaFailure

Fixed failure categories keep User content and native stderr out of logs (#988).

Variants

  • Launch
  • NamespaceResources
  • NamespaceDenied
  • RuntimeMissing
  • DecoderRejected
  • Deadline
  • OutputLimit
  • Io

Implements: Clone, Copy, Debug, Eq, PartialEq, Serialize, ToSchema

MediaFailure::infrastructure

Section titled “MediaFailure::infrastructure”
pub fn infrastructure(self) -> bool

Only launcher/runtime failures affect Instance health; bad inputs do not (#988).

Source: crates/calternal-plugin/src/media_sandbox.rs:79

Functions

Section titled “Functions”

classify_media_failure

Section titled “classify_media_failure”
pub fn classify_media_failure(stderr: &[u8]) -> MediaFailure

Classify only known launcher messages. All other bytes stay private (#988).

Source: crates/calternal-plugin/src/media_sandbox.rs:150

media_health

Section titled “media_health”
pub fn media_health() -> MediaHealth

Read the cheap Admin health snapshot; reads never start a decoder (#988).

Source: crates/calternal-plugin/src/media_sandbox.rs:112

media_sandbox_command

Section titled “media_sandbox_command”
pub fn media_sandbox_command(mode: &str) -> Command

Build the fixed runtime wrapper command used by every native media caller.

Source: crates/calternal-plugin/src/media_sandbox.rs:69

run_media_command

Section titled “run_media_command”
pub async fn run_media_command(
    mut command: Command,
    wall_limit: Duration,
    byte_limit: Option<usize>,
) -> Result<Vec<u8>, MediaFailure>

Shared command runner preserves the same deadline for output, stderr and exit (#988).

Source: crates/calternal-plugin/src/media_sandbox.rs:224

run_media_output

Section titled “run_media_output”
pub async fn run_media_output(
    command: Command,
    wall_limit: Duration,
    byte_limit: usize,
) -> Option<Vec<u8>>

Capture bounded output with concurrent stderr draining and process-group cleanup. Cancellation and the deadline kill every launcher/decoder layer (DESIGN §39, #988).

Source: crates/calternal-plugin/src/media_sandbox.rs:196

run_media_output_retryable

Section titled “run_media_output_retryable”
pub async fn run_media_output_retryable(
    command: Command,
    wall_limit: Duration,
    byte_limit: usize,
) -> Result<Option<Vec<u8>>, String>

Retain per-command infrastructure and pipe I/O errors for durable retries (#988, #1045). A different concurrent decoder’s health cannot change this input’s terminal state. Jobs can reach User clients; fixed diagnostic categories stay in Admin health and logs.

Source: crates/calternal-plugin/src/media_sandbox.rs:209

run_media_process

Section titled “run_media_process”
pub async fn run_media_process(command: Command, wall_limit: Duration) -> bool

Run a decoder without output capture, retaining bounded failure diagnostics (#988).

Source: crates/calternal-plugin/src/media_sandbox.rs:190

run_media_stream

Section titled “run_media_stream”
pub async fn run_media_stream<F, M>(
    mut command: Command,
    wall_limit: Duration,
    metadata_limit: usize,
    sink: F,
    metadata_sink: M,
) -> Option<Vec<u8>>
where
    F: FnMut(&[u8]) -> bool + Send + 'static,
    M: FnMut(&[u8]) -> bool + Send + 'static,

Stream native output into a server-owned bounded sink (#779 / DESIGN §39). Tokio readers send bounded owned frames to one blocking worker. This keeps synchronous storage and playlist callbacks off runtime threads while applying backpressure when the sink cannot keep up (#852). A separate capped metadata pipe carries length-framed playlist updates; no decoder gets a writable cache handle. Timeout, refusal and cancellation kill the same process group as header probes, and every observed exit is reaped.

Source: crates/calternal-plugin/src/media_sandbox.rs:303

set_media_health

Section titled “set_media_health”
pub fn set_media_health(health: MediaHealth)

Publish the fixed startup health result and report a cause once (#988).

Source: crates/calternal-plugin/src/media_sandbox.rs:138