Struct PocketIcStartupConfig 

pub struct PocketIcStartupConfig { /* private fields */ }

Explicit bounded source and policy for one PocketIC startup.

Implementations

impl PocketIcStartupConfig

pub fn from_env(timeout: Duration) -> Result<Self, PocketIcStartupError>

Select the shared environment contract without discovery or downloads.

IC_TESTKIT_POCKET_IC_URL takes precedence over POCKET_IC_BIN. An explicitly empty or invalid selected value fails rather than falling back. URL mode never launches a version probe or claims server ownership. Binary mode resolves the explicit path and checks --version against pocket_ic::LATEST_SERVER_VERSION using the shared bounded capture engine. This is version qualification, not executable-byte admission; prepare and verify the binary with make install-tools / tools-check. The probe has its own timeout; subsequent startup has the same budget.

pub fn spawn(server_binary: impl Into<PathBuf>, timeout: Duration) -> Self

Spawn and monitor one exact PocketIC server binary.

Startup allocates a unique private temporary directory while leaving the --port-file path absent for PocketIC to create.

pub fn connect(server_url: impl Into<String>, timeout: Duration) -> Self

Connect to a caller-owned existing PocketIC server.

The URL is applied to the builder explicitly, so this mode never lets the upstream builder spawn a hidden server child.

pub const fn with_server_hard_ttl(self, hard_ttl: Duration) -> Self

Set the hard lifetime passed to an ic-testkit-managed server.

pub fn with_server_output_files( self, stdout: impl Into<PathBuf>, stderr: impl Into<PathBuf>, ) -> Self

Capture complete raw server streams in two caller-owned new files.

Requires spawn mode. Both parent directories must exist and remain under caller control; relative paths resolve at startup. Existing files, symlinks and special files are refused, without truncating them. New files have Unix mode 0600. Created output survives success, startup failure, cancellation and server teardown, including a partially prepared pair. The caller owns retention, disk budget and path presentation. Without this selection, output remains temporary and is removed during cleanup. Public output/error excerpts still read at most 16 KiB per stream.

pub const fn timeout(&self) -> Duration

Complete startup deadline.

pub const fn server_hard_ttl(&self) -> Option<Duration>

Explicit managed server hard lifetime, or None when disabled.

pub fn server_binary(&self) -> Option<&Path>

Managed server binary, when this configuration spawns one.

pub fn server_url(&self) -> Option<&str>

Existing caller-owned server URL, when configured.

pub fn start_managed_server( self, ) -> Result<PocketIcManagedServer, PocketIcStartupError>

Start a caller-owned managed server without constructing an instance.

This requires a configuration created by Self::spawn. Readiness is bounded by Self::timeout. No hard TTL is passed by default; an explicit Self::with_server_hard_ttl value is passed to the child. Readiness requires a nonzero decimal port followed by a newline in a regular UTF-8 file of at most 64 bytes; oversized files fail with bounded diagnostics. Non-regular port files fail with PocketIcStartupError::Io and io::ErrorKind::InvalidData without waiting for a FIFO writer. The returned handle terminates the child on drop; use its URL with Self::connect to construct bounded instances.

pub fn run_command( self, command: &mut Command, cancelled: impl FnMut() -> bool, ) -> Result<ExitStatus, PocketIcStartupError>

Run a command with IC_TESTKIT_POCKET_IC_URL set to this server.

Spawn mode retains the managed server until command completion; connect mode borrows the external server and never terminates it. The command’s IO and other environment selections remain caller-owned. Cancellation is polled after bounded startup and every 20 ms while the command runs. It returns an io::ErrorKind::Interrupted error after cleanup. If the owned server exits while the command is pending, the command is terminated and the server’s status and bounded diagnostics are returned as PocketIcStartupError::ServerExited. External servers are not monitored.

On Unix the command starts in a new owned process group. Completion, cancellation and observation failures terminate remaining group members before reaping the leader, using the same lifecycle engine as managed servers. This does not impose a command deadline or sandbox descendants that deliberately leave the owned group. Other hosts own the direct child.

Trait Implementations

impl Clone for PocketIcStartupConfig

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PocketIcStartupConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for PocketIcStartupConfig

impl PartialEq for PocketIcStartupConfig

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PocketIcStartupConfig