Struct HyperProcess 

pub struct HyperProcess { /* private fields */ }

A running Hyper server instance.

This struct manages the lifecycle of a local Hyper server process using a callback connection for reliable shutdown. The server is automatically shut down when this object is dropped.

Callback Connection (Dead Man’s Switch)

Unlike traditional process management that relies on signals, HyperProcess maintains a TCP connection to the Hyper server. When this connection is closed (either explicitly or because the client process exits), Hyper automatically shuts down gracefully.

This provides several benefits:

• No orphan processes: If your application crashes, Hyper shuts down automatically
• Graceful shutdown: Hyper can flush data and clean up properly
• Cross-platform: Works reliably on macOS, Linux, and Windows

Example

use hyperdb_api::{HyperProcess, Result};

fn main() -> Result<()> {
    // Start a Hyper server (auto-detect hyperd location)
    let hyper = HyperProcess::new(None, None)?;

    println!("Hyper server running at: {}", hyper.endpoint().unwrap());

    // Server automatically shuts down when `hyper` goes out of scope
    // via the callback connection mechanism
    Ok(())
}

Implementations

impl HyperProcess

pub fn new( hyper_path: Option<&Path>, parameters: Option<&Parameters>, ) -> Result<Self>

Starts a new Hyper server instance.

This method:

1. Creates a callback listener on an ephemeral port
2. Starts the hyperd process with the callback connection address
3. Waits for Hyper to connect back and provide its listen endpoint

Arguments

• hyper_path - Optional path to the hyperd executable. If None, searches in common locations (HYPERD_PATH env var, then known build output paths).
• parameters - Optional parameters for the server.

Errors

Returns an error if:

• The hyperd executable cannot be found
• The callback listener cannot be created
• The server fails to start
• Hyper doesn’t connect back within the timeout (30 seconds)

Example

use hyperdb_api::{HyperProcess, Result};
use std::path::Path;

fn main() -> Result<()> {
    // Auto-detect hyperd location
    let hyper = HyperProcess::new(None, None)?;

    // Or specify explicit path
    let hyper2 = HyperProcess::new(
        Some(Path::new("/path/to/hyperd")),
        None,
    )?;
    Ok(())
}

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

Returns the libpq endpoint for connecting to this instance.

The endpoint is in the format “host:port” (e.g., “localhost:54321”).

Returns None if the process was started in gRPC-only mode. Use grpc_endpoint for gRPC connections.

pub fn require_endpoint(&self) -> Result<&str>

Returns the libpq endpoint, or an error if not available.

This is a convenience method to avoid unwrap() calls when you need the endpoint and want proper error handling.

Errors

Returns an error if this process was started in gRPC-only mode.

Example

use hyperdb_api::{HyperProcess, Result};

fn main() -> Result<()> {
    let hyper = HyperProcess::new(None, None)?;
    let endpoint = hyper.require_endpoint()?; // No unwrap() needed!
    println!("Server running at: {}", endpoint);
    Ok(())
}

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

Returns the gRPC endpoint for connecting to this instance.

The endpoint is in the format “host:port” (e.g., “127.0.0.1:7484”).

Returns None if the process was started in libpq-only mode.

pub fn require_grpc_endpoint(&self) -> Result<&str>

Returns the gRPC endpoint, or an error if not available.

This is a convenience method to avoid unwrap() calls when you need the gRPC endpoint and want proper error handling.

Errors

Returns an error if this process was started in libpq-only mode.

pub fn grpc_url(&self) -> Option<String>

Returns the gRPC endpoint as a full URL suitable for gRPC clients.

Returns the endpoint prefixed with “http://” (e.g., “http://127.0.0.1:7484”). Returns None if the process was started in libpq-only mode.

pub fn require_grpc_url(&self) -> Result<String>

Returns the gRPC URL, or an error if not available.

This is a convenience method to avoid unwrap() calls when you need the gRPC URL and want proper error handling.

Errors

Returns an error if this process was started in libpq-only mode.

pub fn listen_mode(&self) -> ListenMode

Returns the listen mode this process was started with.

pub fn transport_mode(&self) -> TransportMode

Returns the transport mode this process was started with.

pub fn connection_endpoint(&self) -> Option<&ConnectionEndpoint>

Returns the connection endpoint for this process.

This returns a ConnectionEndpoint that can be used to connect to this Hyper instance via TCP, Unix Domain Socket, or Named Pipe.

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

Returns the log directory where hyperd writes its log files.

The log file is typically hyperd.log within this directory. Returns None if the log directory could not be determined (e.g., default parameters were disabled and no log_dir was specified).

This is useful for setting up QueryStatsProvider implementations that parse the Hyper log file.

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

Returns the socket directory used for UDS connections (Unix only).

Returns None if the process is using TCP or if no socket directory was created.

pub fn pid(&self) -> Option<u32>

Returns the process ID of the Hyper server.

pub fn is_running(&self) -> bool

Returns whether the Hyper server process is still running.

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

Shuts down the Hyper server gracefully with a timeout.

This closes the callback connection, which signals Hyper to shut down gracefully. If Hyper doesn’t exit within the timeout, it will be forcefully terminated.

Arguments

• timeout - Maximum time to wait for graceful shutdown before force-killing.

Errors

Returns an error if the shutdown fails.

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

Shuts down the Hyper server gracefully, waiting indefinitely.

This closes the callback connection and waits for Hyper to exit. Use shutdown_timeout if you need a timeout.

Errors

Returns an error if the shutdown fails.

Trait Implementations

impl Debug for HyperProcess

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

Formats the value using the given formatter.

impl Drop for HyperProcess

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for HyperProcess