Struct ZLayerDirs 

pub struct ZLayerDirs { /* private fields */ }

Centralized filesystem path resolution for ZLayer.

All ZLayer crates should use this instead of hardcoding paths.

Implementations

impl ZLayerDirs

pub fn new(data_dir: impl Into<PathBuf>) -> Self

Create from an explicit data directory.

pub fn system_default() -> Self

Create using the platform default data directory.

pub fn default_data_dir() -> PathBuf

Platform-aware default data directory.

• $ZLAYER_DATA_DIR (if set and non-empty) overrides every other source.
• macOS: ~/.zlayer
• Linux (root): /var/lib/zlayer
• Linux (user): ~/.zlayer
• Windows: %ProgramData%\ZLayer (system) or C:\ProgramData\ZLayer fallback. HCS-backed nodes run as SYSTEM so the system-wide ProgramData location is the right default.

pub fn detect_data_dir() -> PathBuf

Detect the data directory of an existing installation.

On Linux, if not root, checks whether /var/lib/zlayer/daemon.json exists (indicating a system-level install) and returns /var/lib/zlayer if so. On Windows, probes %ProgramData%\ZLayer for a daemon.json marker in case the caller lacks the env var but a prior system install is present. Otherwise falls back to [default_data_dir].

pub fn default_run_dir() -> PathBuf

Default runtime directory.

• Linux: /var/run/zlayer
• macOS: {default_data_dir}/run
• Windows: {default_data_dir}\run (i.e. %ProgramData%\ZLayer\run)

pub fn default_run_dir_for(data_dir: &Path) -> PathBuf

Data-dir-aware default run directory.

Returns the platform’s system default (e.g. /var/run/zlayer on Linux) when data_dir matches Self::default_data_dir; otherwise returns {data_dir}/run. This preserves the FHS layout for stock installs while letting --data-dir /tmp/foo get a fully isolated runtime directory.

pub fn default_log_dir() -> PathBuf

Default log directory.

• Linux: /var/log/zlayer
• macOS: {default_data_dir}/logs
• Windows: {default_data_dir}\logs (i.e. %ProgramData%\ZLayer\logs)

pub fn default_log_dir_for(data_dir: &Path) -> PathBuf

Data-dir-aware default log directory.

Returns the platform’s system default (e.g. /var/log/zlayer on Linux) when data_dir matches Self::default_data_dir; otherwise returns {data_dir}/logs. This preserves the FHS layout for stock installs while letting --data-dir /tmp/foo get a fully isolated log directory.

pub fn default_socket_path() -> String

Default Unix socket path.

• Linux: /var/run/zlayer.sock
• macOS: {default_data_dir}/run/zlayer.sock
• Windows: tcp://127.0.0.1:3669

pub fn default_socket_path_for(data_dir: &Path) -> String

Data-dir-aware default daemon socket path.

On Windows always returns tcp://127.0.0.1:3669 regardless of data_dir (the daemon listens on TCP loopback, not a filesystem socket). On Unix, returns the platform’s system default when data_dir matches Self::default_data_dir; otherwise returns {data_dir}/run/zlayer.sock. Stock installs keep their FHS-style path while --data-dir /tmp/foo gets an isolated socket.

pub fn default_overlayd_socket_path_for(data_dir: &Path) -> String

Data-dir-aware default zlayer-overlayd IPC socket path.

zlayer-overlayd is the standalone overlay daemon; the main daemon drives it over this endpoint. Mirrors Self::default_socket_path_for:

• Windows: always \\.\pipe\zlayer-overlayd (named pipe, not a file).
• Unix, default data dir: /var/run/zlayer-overlayd.sock.
• Unix, overridden data dir: {data_dir}/run/zlayer-overlayd.sock (falling back to a length-safe path if that would exceed SUN_PATH).

pub fn default_docker_socket_path() -> String

Default Docker-compatible API socket path.

• Linux (root): /var/run/zlayer/docker.sock
• Linux (user, XDG_RUNTIME_DIR set): {XDG_RUNTIME_DIR}/zlayer/docker.sock
• Linux (user, no XDG_RUNTIME_DIR): {default_data_dir}/run/docker.sock
• macOS: {default_data_dir}/run/docker.sock
• Windows: \\.\pipe\zlayer-docker

pub fn default_binary_dir() -> PathBuf

Preferred system directory for the zlayer binary.

Tries /usr/local/bin first (standard FHS, writable on most systems). Falls back to {data_dir}/bin (/var/lib/zlayer/bin on Linux as root) which is always writable since ZLayer owns that directory.

On macOS and Windows, returns /usr/local/bin or the data-dir bin subdirectory respectively.

pub fn data_dir(&self) -> &Path

Root data directory.

pub fn containers(&self) -> PathBuf

Container state directory ({data}/containers).

pub fn rootfs(&self) -> PathBuf

Unpacked image rootfs directory ({data}/rootfs).

pub fn bundles(&self) -> PathBuf

OCI bundle directory ({data}/bundles).

pub fn cache(&self) -> PathBuf

Image/blob cache directory ({data}/cache).

pub fn volumes(&self) -> PathBuf

Named volumes directory ({data}/volumes).

pub fn projects(&self) -> PathBuf

Project git clones directory ({data}/projects). Persistent state — per-project working copies live at {data}/projects/{project_id}.

pub fn wasm(&self) -> PathBuf

WASM module cache directory ({data}/wasm).

pub fn wasm_compiled(&self) -> PathBuf

AOT-compiled WASM cache directory ({data}/wasm/compiled).

pub fn secrets(&self) -> PathBuf

Encrypted secrets store directory ({data}/secrets).

pub fn certs(&self) -> PathBuf

TLS certificate storage directory ({data}/certs).

pub fn raft(&self) -> PathBuf

Raft consensus data directory ({data}/raft).

pub fn admin_password(&self) -> PathBuf

Admin password file path ({data}/admin_password).

pub fn admin_bearer_path(&self) -> PathBuf

Path to the persisted local-admin bearer token file.

On Linux/macOS this file is informational — the daemon’s UDS middleware already injects the bearer into UDS-originated requests. On Windows the DaemonClient reads this file on connect to authenticate against the loopback TCP listener (which has no socket-path-based local-admin bypass).

Default: <data_dir>/admin_bearer.token

On Windows this resolves under %ProgramData%\ZLayer so the file inherits the parent ACL (SYSTEM + Administrators write, Users read), which is adequate for the local-admin bearer.

pub fn daemon_json(&self) -> PathBuf

Daemon metadata file path ({data}/daemon.json).

pub fn agent_ipam_state(&self) -> PathBuf

Path to the agent’s local IPAM (per-node slice allocator) state file.

pub fn agent_network_state(&self) -> PathBuf

Path to the agent’s managed-network marker file ({data}/agent_network.json).

Records the host-level networks ZLayer creates (e.g. the Windows HCN overlay network) so they can be reused across daemon restarts/updates and torn down only on a full uninstall (daemon uninstall --purge), not on every restart/reinstall.

pub fn logs(&self) -> PathBuf

Logs subdirectory under data_dir ({data}/logs). Used on macOS where logs live under the user data dir.

pub fn vms(&self) -> PathBuf

macOS VM state directory ({data}/vms).

pub fn images(&self) -> PathBuf

OCI image storage directory ({data}/images).

pub fn bin(&self) -> PathBuf

Local binary directory ({data}/bin).

pub fn buildd_bin(&self) -> PathBuf

Canonical install path for the zlayer-buildd sidecar binary: {data}/bin/zlayer-buildd. Resolved by the buildah-sidecar backend’s discovery logic and written by the zlayer install --sidecar installer.

pub fn buildd(&self) -> PathBuf

Directory holding sidecar mTLS material: {data}/buildd. Contains ca.pem, cert.pem, and key.pem consumed by both ends of the zlayer-buildd gRPC channel.

pub fn toolchain_cache(&self) -> PathBuf

Toolchain download cache directory ({data}/toolchain-cache).

pub fn tmp(&self) -> PathBuf

Temporary build directory ({data}/tmp).

pub fn scratch_dir(&self, prefix: &str) -> Result<Scratch>

Create a uniquely-named scratch directory under {data}/tmp.

Returns a zlayer_types::Scratch RAII guard — the directory is removed when the guard is dropped. Use this instead of tempfile::tempdir() so scratch data lives on the configured data filesystem rather than /tmp, which is tmpfs (RAM-backed) on most modern Linux distros and risks OOM for large scratch data (build contexts, image tarballs, layer staging, etc.).

Errors

Returns the underlying filesystem error if {data}/tmp can’t be created or the unique subdirectory can’t be allocated.

pub fn scratch_file(&self, prefix: &str) -> Result<ScratchFile>

Create a uniquely-named scratch file under {data}/tmp.

Returns a zlayer_types::ScratchFile RAII guard. Same rationale as Self::scratch_dir.

Errors

Returns the underlying filesystem error if {data}/tmp can’t be created or the unique file can’t be allocated.

pub fn wireguard(&self) -> PathBuf

Data-dir-aware WireGuard UAPI socket directory.

When data_dir == Self::default_data_dir(), returns /var/run/wireguard (FHS default — also where wg(8) looks). Otherwise returns {data_dir}/run/wireguard so an isolated install (e.g. --data-dir /tmp/foo) does not collide with a system install on the same host.

macOS / Windows: always returns {data_dir}/run/wireguard since the FHS path doesn’t apply.