pg_embedded_setup_unpriv/

lib.rs

//! Facilitates preparing an embedded `PostgreSQL` instance while dropping root
//! privileges.
//!
//! The library owns the lifecycle for configuring paths, permissions, and
//! process identity so the bundled `PostgreSQL` binaries can initialize safely
//! under an unprivileged account.

mod bootstrap;
pub mod cache;
mod cleanup_helpers;
mod cluster;
mod env;
mod error;
pub mod extensions;
mod fs;
#[cfg(all(test, feature = "loom-tests"))]
mod loom_model;
pub mod observability;
#[cfg(all(
    unix,
    any(
        target_os = "linux",
        target_os = "android",
        target_os = "freebsd",
        target_os = "openbsd",
        target_os = "dragonfly",
    ),
))]
mod privileges;
#[doc(hidden)]
pub mod test_support;
#[doc(hidden)]
pub mod worker;
pub(crate) mod worker_process;

#[doc(hidden)]
pub mod worker_process_test_api {
    //! Integration test shims for worker process orchestration.

    use crate::worker_process;
    #[cfg(all(
        unix,
        any(
            target_os = "linux",
            target_os = "android",
            target_os = "freebsd",
            target_os = "openbsd",
            target_os = "dragonfly",
        ),
        any(test, doc, feature = "privileged-tests"),
    ))]
    use crate::worker_process::PrivilegeDropGuard as InnerPrivilegeDropGuard;
    pub use crate::{cluster::WorkerOperation, worker_process::WorkerRequestArgs};

    /// Test-visible wrapper around the internal worker request.
    ///
    /// Use this helper when integration tests need to exercise worker process
    /// orchestration without exposing the internals as part of the public API.
    pub struct WorkerRequest<'a>(worker_process::WorkerRequest<'a>);

    impl<'a> WorkerRequest<'a> {
        /// Constructs a worker request for invoking an operation in tests.
        ///
        /// # Examples
        ///
        /// ```ignore
        /// # use std::time::Duration;
        /// # use camino::Utf8Path;
        /// # use postgresql_embedded::Settings;
        /// # use pg_embedded_setup_unpriv::{
        /// #     WorkerOperation,
        /// #     worker_process_test_api::{WorkerRequest, WorkerRequestArgs},
        /// # };
        /// # let worker = Utf8Path::new("/tmp/worker");
        /// # let settings = Settings::default();
        /// # let env_vars: Vec<(String, Option<String>)> = Vec::new();
        /// let args = WorkerRequestArgs {
        ///     worker,
        ///     settings: &settings,
        ///     env_vars: &env_vars,
        ///     operation: WorkerOperation::Setup,
        ///     timeout: Duration::from_secs(1),
        /// };
        /// let request = WorkerRequest::new(args);
        /// # let _ = request;
        /// ```
        #[must_use]
        pub const fn new(args: WorkerRequestArgs<'a>) -> Self {
            Self(worker_process::WorkerRequest::new(args))
        }

        /// Returns a reference to the wrapped worker request.
        pub(crate) const fn inner(&self) -> &worker_process::WorkerRequest<'a> { &self.0 }
    }

    /// Executes a worker request whilst returning crate-level errors.
    pub fn run(request: &WorkerRequest<'_>) -> crate::BootstrapResult<()> {
        worker_process::run(request.inner())
    }

    /// Guard that restores the privilege-drop toggle when tests finish.
    #[cfg(all(
        unix,
        any(
            target_os = "linux",
            target_os = "android",
            target_os = "freebsd",
            target_os = "openbsd",
            target_os = "dragonfly",
        ),
        any(test, doc, feature = "privileged-tests"),
    ))]
    pub struct PrivilegeDropGuard {
        _inner: InnerPrivilegeDropGuard,
    }

    /// Temporarily disables privilege dropping so tests can run deterministic
    /// worker binaries without adjusting file ownership.
    #[cfg(all(
        unix,
        any(
            target_os = "linux",
            target_os = "android",
            target_os = "freebsd",
            target_os = "openbsd",
            target_os = "dragonfly",
        ),
        any(test, doc, feature = "privileged-tests"),
    ))]
    #[must_use]
    pub fn disable_privilege_drop_for_tests() -> PrivilegeDropGuard {
        PrivilegeDropGuard {
            _inner: worker_process::disable_privilege_drop_for_tests(),
        }
    }

    /// Renders a worker failure for assertion-friendly error strings.
    #[must_use]
    pub fn render_failure_for_tests(
        context: &str,
        output: &std::process::Output,
    ) -> crate::BootstrapError {
        worker_process::render_failure_for_tests(context, output)
    }
}

use std::ffi::OsString;

pub use bootstrap::{
    CleanupMode,
    ExecutionMode,
    ExecutionPrivileges,
    PasswordReuseOutcome,
    TestBootstrapEnvironment,
    TestBootstrapSettings,
    bootstrap_for_tests,
    default_paths_under,
    detect_execution_privileges,
    find_timezone_dir,
    reuse_existing_password,
    run,
    stored_cluster_password,
};
use camino::Utf8PathBuf;
#[cfg(any(doc, test, feature = "cluster-unit-tests", feature = "dev-worker"))]
#[doc(hidden)]
pub use cluster::WorkerInvoker;
#[cfg(any(test, feature = "cluster-unit-tests"))]
#[doc(hidden)]
pub use cluster::WorkerOperation;
pub use cluster::{
    ClusterGuard,
    ClusterHandle,
    ConnectionMetadata,
    DatabaseName,
    TemporaryDatabase,
    TestCluster,
    TestClusterConnection,
};
use color_eyre::eyre::{Context, eyre};
#[doc(hidden)]
pub use error::BootstrapResult;
pub use error::{
    BootstrapError,
    BootstrapErrorKind,
    PgEmbeddedError as Error,
    PgEmbeddedError,
    PrivilegeError,
    PrivilegeResult,
    Result,
};
use ortho_config::OrthoConfig;
use postgresql_embedded::{Settings, VersionReq};
#[cfg(feature = "privileged-tests")]
#[cfg(all(
    unix,
    any(
        target_os = "linux",
        target_os = "android",
        target_os = "freebsd",
        target_os = "openbsd",
        target_os = "dragonfly",
    ),
))]
#[expect(
    deprecated,
    reason = "with_temp_euid() remains exported for backward compatibility whilst deprecated"
)]
pub use privileges::with_temp_euid;
#[cfg(all(
    unix,
    any(
        target_os = "linux",
        target_os = "android",
        target_os = "freebsd",
        target_os = "openbsd",
        target_os = "dragonfly",
    ),
))]
pub use privileges::{
    default_paths_for,
    default_root_for,
    make_data_dir_private,
    make_dir_accessible,
    nobody_uid,
};
use serde::{Deserialize, Serialize};

#[doc(hidden)]
pub use crate::env::ScopedEnv;
use crate::error::{ConfigError, ConfigResult};
/// Resolves a path to an ambient directory handle paired with the relative path component.
///
/// This function provides capability-based filesystem access by opening paths relative to
/// ambient authority. Absolute paths are opened relative to their parent directory; relative
/// paths reuse the current working directory.
///
/// # Returns
///
/// Returns a tuple containing:
/// - A [`cap_std::fs::Dir`] handle for the parent directory
/// - A [`camino::Utf8PathBuf`] with the relative component
///
/// For absolute paths like `/foo/bar`, returns `(Dir("/foo"), "bar")`.
/// For relative paths like `baz/qux`, returns `(Dir("."), "baz/qux")`.
/// For root paths like `/`, returns `(Dir("/"), "")` with an empty relative component.
///
/// # Errors
///
/// Returns an error if the path cannot be opened as a directory or if path operations fail.
///
/// # Examples
///
/// ```no_run
/// use camino::Utf8Path;
/// use pg_embedded_setup_unpriv::ambient_dir_and_path;
///
/// # fn main() -> color_eyre::Result<()> {
/// let (dir, relative) = ambient_dir_and_path(Utf8Path::new("./data"))?;
/// // Use dir handle for capability-based operations on relative path
/// # Ok(())
/// # }
/// ```
pub use crate::fs::ambient_dir_and_path;

/// Captures `PostgreSQL` settings supplied via environment variables.
#[derive(Debug, Clone, Serialize, Deserialize, OrthoConfig, Default)]
#[ortho_config(prefix = "PG")]
///
/// # Examples
/// ```
/// use pg_embedded_setup_unpriv::PgEnvCfg;
///
/// let cfg = PgEnvCfg::default();
/// assert!(cfg.port.is_none());
/// ```
pub struct PgEnvCfg {
    /// Optional semver requirement that constrains the `PostgreSQL` version.
    pub version_req: Option<String>,
    /// Port assigned to the embedded `PostgreSQL` server.
    pub port: Option<u16>,
    /// Name of the administrative user created for the cluster.
    pub superuser: Option<String>,
    /// Password provisioned for the administrative user.
    pub password: Option<String>,
    /// Directory used for `PostgreSQL` data files when provided.
    pub data_dir: Option<Utf8PathBuf>,
    /// Directory containing the `PostgreSQL` binaries when provided.
    pub runtime_dir: Option<Utf8PathBuf>,
    /// Locale applied to `initdb` when specified.
    pub locale: Option<String>,
    /// Encoding applied to `initdb` when specified.
    pub encoding: Option<String>,
    /// Directory for sharing downloaded `PostgreSQL` binaries across test runs.
    ///
    /// When `Some`, this explicit path is used directly by `TestCluster`, bypassing
    /// the automatic resolution chain. When `None`, the cache directory is resolved
    /// in the following order:
    ///
    /// 1. `PG_BINARY_CACHE_DIR` environment variable (if set and non-empty)
    /// 2. `$XDG_CACHE_HOME/pg-embedded/binaries` (if `XDG_CACHE_HOME` is set)
    /// 3. `$HOME/.cache/pg-embedded/binaries` (if `HOME` is set)
    /// 4. `/tmp/pg-embedded/binaries` (final fallback)
    pub binary_cache_dir: Option<Utf8PathBuf>,
    /// Base directory under which the default `install` and `data`
    /// directories are created (`PG_EMBED_ROOT`).
    ///
    /// When unset the base is `/var/tmp/pg-embed-{uid}`, which every project
    /// on a host shares per user. Set it to give a project or a test run its
    /// own tree. `PG_RUNTIME_DIR` and `PG_DATA_DIR` still override the two
    /// leaves individually.
    pub embed_root: Option<Utf8PathBuf>,
    /// `max_connections` for the server (`PG_MAX_CONNECTIONS`).
    ///
    /// Test clusters default to 20; set this when parallel test runners need
    /// more. Applied to every bootstrap, test or not. Values below
    /// [`MIN_MAX_CONNECTIONS`] are rejected when the settings are built.
    pub max_connections: Option<u32>,
    /// Comma-separated extension names to install before the server starts
    /// (`PG_EXTENSIONS`, for example `vector`). Empty or unset disables the
    /// extension hook.
    pub extensions: Option<String>,
    /// Location of the extension manifest (`PG_EXTENSIONS_MANIFEST`): an
    /// `https://` URL, a loopback `http://` URL, or a filesystem path, which
    /// is the rule the archives it names go through. Required when
    /// `extensions` is set.
    pub extensions_manifest: Option<String>,
    /// Lower-case hex SHA-256 of the manifest bytes
    /// (`PG_EXTENSIONS_MANIFEST_SHA256`). Required for a URL manifest,
    /// loopback included; optional for a filesystem path.
    pub extensions_manifest_sha256: Option<String>,
    /// Directory holding verified extension archives between runs
    /// (`PG_EXTENSIONS_CACHE_DIR`). Defaults to
    /// `$XDG_CACHE_HOME/pg-embedded/extensions` with the same fallbacks as
    /// [`binary_cache_dir`](Self::binary_cache_dir).
    pub extensions_cache_dir: Option<Utf8PathBuf>,
}

impl PgEnvCfg {
    /// Loads configuration from environment variables without parsing CLI arguments.
    ///
    /// # Errors
    /// Returns an error when environment parsing fails or derived configuration
    /// cannot be represented using UTF-8 paths.
    pub fn load() -> ConfigResult<Self> {
        let args = [OsString::from("pg-embedded-setup-unpriv")];
        Self::load_from_iter(args).map_err(|err| ConfigError::from(eyre!(err)))
    }

    /// Converts the configuration into a complete `postgresql_embedded::Settings` object.
    ///
    /// Applies version, connection, path, and locale settings from the current configuration.
    /// Returns an error if the version requirement is invalid. This variant does not apply
    /// test-specific worker limits.
    ///
    /// # Examples
    /// ```no_run
    /// use pg_embedded_setup_unpriv::PgEnvCfg;
    ///
    /// let cfg = PgEnvCfg::default();
    /// let settings = cfg.to_settings()?;
    /// # Ok::<(), pg_embedded_setup_unpriv::Error>(())
    /// ```
    ///
    /// # Returns
    /// A fully configured `Settings` instance on success, or an error if configuration fails.
    ///
    /// # Errors
    /// Returns an error when the semantic version requirement cannot be parsed,
    /// or when `PG_MAX_CONNECTIONS` is below [`MIN_MAX_CONNECTIONS`].
    pub fn to_settings(&self) -> Result<Settings> { self.to_settings_with_context(false) }

    /// Converts the configuration into `Settings`, applying test-only worker limits.
    ///
    /// Use this helper for ephemeral test clusters where resource limits are desirable.
    ///
    /// # Examples
    /// ```no_run
    /// use pg_embedded_setup_unpriv::PgEnvCfg;
    ///
    /// let cfg = PgEnvCfg::default();
    /// let settings = cfg.to_settings_for_tests()?;
    /// # Ok::<(), pg_embedded_setup_unpriv::Error>(())
    /// ```
    ///
    /// # Errors
    /// Returns an error when the semantic version requirement cannot be parsed,
    /// or when `PG_MAX_CONNECTIONS` is below [`MIN_MAX_CONNECTIONS`].
    pub fn to_settings_for_tests(&self) -> Result<Settings> { self.to_settings_with_context(true) }

    /// Converts the configuration into `Settings`, optionally applying test limits.
    ///
    /// Set `for_tests` to `true` to apply the worker limits intended for ephemeral
    /// test clusters.
    ///
    /// # Examples
    /// ```no_run
    /// use pg_embedded_setup_unpriv::PgEnvCfg;
    ///
    /// let cfg = PgEnvCfg::default();
    /// let settings = cfg.to_settings_with_context(true)?;
    /// # Ok::<(), pg_embedded_setup_unpriv::Error>(())
    /// ```
    ///
    /// # Errors
    /// Returns an error when the semantic version requirement cannot be parsed,
    /// or when `PG_MAX_CONNECTIONS` is below [`MIN_MAX_CONNECTIONS`].
    pub fn to_settings_with_context(&self, for_tests: bool) -> Result<Settings> {
        // Disable the internal postgresql_embedded timeout. This crate wraps lifecycle
        // operations with tokio::time::timeout using setup_timeout/start_timeout from
        // TestBootstrapSettings, providing consistent timeout behaviour for both
        // privileged (subprocess) and unprivileged (in-process) execution paths.
        // The default 5-second timeout is too short for initdb on slower systems.
        let mut s = Settings {
            timeout: None,
            ..Settings::default()
        };

        self.apply_version(&mut s)?;
        self.apply_connection(&mut s);
        self.apply_paths(&mut s);
        self.apply_locale(&mut s);
        if for_tests {
            Self::apply_worker_limits(&mut s);
        }
        self.apply_max_connections(&mut s)?;

        Ok(s)
    }

    fn apply_version(&self, settings: &mut Settings) -> ConfigResult<()> {
        if let Some(ref vr) = self.version_req {
            settings.version =
                VersionReq::parse(vr).context("PG_VERSION_REQ invalid semver spec")?;
        }
        Ok(())
    }

    fn apply_connection(&self, settings: &mut Settings) {
        if let Some(p) = self.port {
            settings.port = p;
        }
        if let Some(ref u) = self.superuser {
            settings.username.clone_from(u);
        }
        if let Some(ref pw) = self.password {
            settings.password.clone_from(pw);
        }
    }

    fn apply_paths(&self, settings: &mut Settings) {
        if let Some(ref dir) = self.data_dir {
            settings.data_dir = dir.clone().into_std_path_buf();
        }
        if let Some(ref dir) = self.runtime_dir {
            settings.installation_dir = dir.clone().into_std_path_buf();
        }
    }

    /// Applies locale and encoding settings to the `PostgreSQL` configuration if specified
    /// in the environment.
    ///
    /// Inserts the `locale` and `encoding` values into the settings configuration map when
    /// present in the environment configuration.
    fn apply_locale(&self, settings: &mut Settings) {
        if let Some(ref loc) = self.locale {
            settings.configuration.insert("locale".into(), loc.clone());
        }
        if let Some(ref enc) = self.encoding {
            settings
                .configuration
                .insert("encoding".into(), enc.clone());
        }
    }

    /// Applies an explicit `max_connections`, replacing the test default of 20.
    ///
    /// `PostgreSQL` keeps `superuser_reserved_connections` (3 by default) below
    /// `max_connections`, so anything under [`MIN_MAX_CONNECTIONS`] would make
    /// the server refuse to start; reject it here with a clear message.
    fn apply_max_connections(&self, settings: &mut Settings) -> ConfigResult<()> {
        let Some(limit) = self.max_connections else {
            return Ok(());
        };
        if limit < MIN_MAX_CONNECTIONS {
            return Err(ConfigError::from(eyre!(
                "PG_MAX_CONNECTIONS must be at least {MIN_MAX_CONNECTIONS} (got {limit}); \
                 PostgreSQL reserves three superuser slots below max_connections"
            )));
        }
        settings
            .configuration
            .insert("max_connections".into(), limit.to_string());
        Ok(())
    }

    fn apply_worker_limits(settings: &mut Settings) {
        for (key, value) in WORKER_LIMIT_DEFAULTS {
            settings
                .configuration
                .entry(key.to_owned())
                .or_insert_with(|| value.to_owned());
        }
    }
}

/// Smallest `PG_MAX_CONNECTIONS` the helper accepts: one ordinary slot above
/// `PostgreSQL`'s default of three reserved superuser connections.
pub const MIN_MAX_CONNECTIONS: u32 = 4;
const WORKER_LIMIT_DEFAULTS: [(&str, &str); 8] = [
    ("max_connections", "20"),
    ("max_worker_processes", "2"),
    ("max_parallel_workers", "0"),
    ("max_parallel_workers_per_gather", "0"),
    ("max_parallel_maintenance_workers", "0"),
    ("autovacuum", "off"),
    ("max_wal_senders", "0"),
    ("max_replication_slots", "0"),
];