Struct BackendHandle 

pub struct BackendHandle {
    pub service_name: String,
    pub service_version: String,
    pub daemon_process: DaemonProcess,
    /* private fields */
}

A verified handle to a running backend daemon.

The handle carries the daemon identity needed to defend against stale manifests and PID recycling before consumers connect to the IPC endpoint.

A handle is created only through one of the probe* constructors. The constructor performs all identity checks first; successful callers may then use Self::is_alive for a cheap liveness check or Self::connect to open a fresh local-socket connection.

Fields

service_name: String

Logical service name from the manifest or direct probe caller.

service_version: String

Service version from the manifest or direct probe caller.

daemon_process: DaemonProcess

Verified daemon process identity.

Implementations

impl BackendHandle

pub fn probe(endpoint: &Endpoint, expected: &DaemonProcess) -> Option<Self>

Connect to an existing backend by endpoint and verify process identity.

This probe verifies the endpoint identity tuple, requires the endpoint to answer the nonce-based IPC identity probe, then verifies current boot ID, process liveness, executable path, and executable SHA-256. It returns None for stale manifests, dead PIDs, mismatched daemon binaries, or endpoints that do not answer as the expected backend.

Use this when the caller already has service metadata elsewhere and only needs to know whether the daemon identity is still valid.

BLOCKING. Performs synchronous IPC up to probe::DEFAULT_ENDPOINT_PROBE_TIMEOUT (500 ms). From a tokio task, call from spawn_blocking or switch to [Self::probe_async] (requires the client-async feature).

use running_process::broker::backend_handle::{BackendHandle, DaemonProcess};
use running_process::broker::protocol::Endpoint;

if let Some(handle) = BackendHandle::probe(&endpoint, &expected) {
    assert!(handle.is_alive());
}

pub fn probe_with_service( service_name: impl Into<String>, service_version: impl Into<String>, endpoint: &Endpoint, expected: &DaemonProcess, ) -> Result<Self>

Probe an existing backend and attach service metadata to the handle.

This is the preferred constructor for direct-daemon consumers because it preserves the logical service tuple alongside the verified process identity.

BLOCKING. Performs synchronous IPC up to probe::DEFAULT_ENDPOINT_PROBE_TIMEOUT (500 ms). From a tokio task, call from spawn_blocking or use [Self::probe_with_service_async] (requires the client-async feature) instead — calling this directly from an async context will block the runtime worker thread.

use running_process::broker::backend_handle::{BackendHandle, DaemonProcess};
use running_process::broker::protocol::Endpoint;

BackendHandle::probe_with_service("zccache", "0.8.0", &endpoint, &expected)

pub fn probe_manifest(manifest: &CacheManifest) -> Option<Self>

Probe the current_daemon recorded in a cache manifest.

Returns None when the manifest has no daemon entry or when the daemon entry no longer matches a live process on the current boot.

use running_process::broker::backend_handle::BackendHandle;
use running_process::broker::protocol::CacheManifest;

match BackendHandle::probe_manifest(manifest) {
    Some(handle) if handle.is_alive() => {
        // Reuse the verified backend.
    }
    _ => {
        // Spawn or discover a replacement backend.
    }
}

pub fn try_from_manifest(manifest: &CacheManifest) -> Result<Option<Self>>

Fallible variant of Self::probe_manifest that preserves parse errors.

Use this in maintenance tools and diagnostics where malformed manifest identities should be reported separately from a normal cache miss.

pub fn is_alive(&self) -> bool

Check liveness without opening a new IPC connection.

On platforms with an owned process-handle primitive, this checks the handle captured during probing. Otherwise it falls back to opening the process ID again.

pub async fn connect(&self) -> Result<Connection>

Open a fresh IPC connection to this backend.

The process identity is verified when the handle is created. Callers that cache handles for a long time should call Self::is_alive or reprobe from the latest manifest before opening a connection.

use running_process::broker::backend_handle::BackendHandle;

async fn connect_to_verified_backend(
    handle: &BackendHandle,
) -> running_process::broker::backend_handle::Result<()> {
    let connection = handle.connect().await?;
    let _stream = connection.into_inner();
    Ok(())
}

pub async fn shutdown(self, timeout: Duration) -> Result<()>

Send a graceful shutdown signal and wait until the process exits.

On Windows this foundation returns GracefulTerminateUnsupported until the broker shutdown request protocol lands.

Dropping the handle without calling this method leaves the backend running.

pub fn force_kill(self) -> Result<()>

Force-kill the daemon process.

This is the last-resort teardown path for a daemon that ignored graceful shutdown or whose IPC protocol is unavailable.