### Installation::install_version

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

Fetches and installs one exact signed release version.

```APIDOC
## pub fn install_version(&self, version: Version) -> Result<ActivationResult>

### Description
Fetch and install one exact signed release version.

### Parameters
- **version** (Version) - The specific version to install.

### Returns
- **Result<ActivationResult>** - The result of the activation process.
```

--------------------------------

### Installation::install

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

Installs the exact package version supplied by the App configuration.

```APIDOC
## pub fn install(&self) -> Result<ActivationResult>

### Description
Install the exact package version supplied by `App::version`.

### Returns
- **Result<ActivationResult>** - The result of the activation process.
```

--------------------------------

### Installation Methods

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Manager.html

Methods for installing, updating, and rolling back software versions.

```APIDOC
## install()

### Description
Install the exact package version supplied by App::version.

## install_current()

### Description
Descriptive alias for install().

## install_version(version: Version)

### Description
Fetch and install one exact signed release version.

## install_exact(version: Version)

### Description
Explicit-version spelling for callers that expose an install --version command.

## update()

### Description
Update a managed installation to the signed latest release. Unmanaged installations are rejected before any download or filesystem mutation.

## update_latest()

### Description
Explicit latest-update spelling for CLI integrations.

## rollback()

### Description
Roll back to install.json.previous using the same pending/pointer/install sequence as an update.

## rollback_previous()

### Description
Explicit previous-version spelling for CLI integrations.

## rollback_to(target: Version)

### Description
Roll back to a specific retained version.
```

--------------------------------

### Installation Struct Definition

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

The primary struct definition for the managed installation manager.

```rust
pub struct Installation<D = UreqDownloader> { /* private fields */ }
```

--------------------------------

### InstallState Struct Definition

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.InstallState.html

The primary data structure for tracking installation state.

```rust
pub struct InstallState {
    pub schema_version: u32,
    pub active: Option<Version>,
    pub previous: Option<Version>,
    pub installation_id: String,
    pub launcher: Option<LauncherOwnership>,
}
```

--------------------------------

### Installation::update

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

Updates a managed installation to the signed latest release.

```APIDOC
## pub fn update(&self) -> Result<ActivationResult>

### Description
Update a managed installation to the signed latest release. Unmanaged installations are rejected before any download or filesystem mutation.

### Returns
- **Result<ActivationResult>** - The result of the update process.
```

--------------------------------

### Installation::check_latest

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

Fetches signed latest metadata and reports the authoritative current pointer.

```APIDOC
## pub fn check_latest(&self) -> Result<CheckResult>

### Description
Fetch only signed latest metadata and report the authoritative current pointer.

### Returns
- **Result<CheckResult>** - The metadata result.
```

--------------------------------

### Installation::rollback

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

Rolls back to the previous version using the retained target.

```APIDOC
## pub fn rollback(&self) -> Result<ActivationResult>

### Description
Roll back to `install.json.previous` using the same pending/pointer/install sequence as an update. The retained target is fully reverified before a pending journal is written.

### Returns
- **Result<ActivationResult>** - The result of the rollback process.
```

--------------------------------

### Auto Trait Implementations for Installation

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

Lists the auto trait implementations for the Installation struct, including thread-safety and pinning traits.

```rust
impl<D = UreqDownloader> !RefUnwindSafe for Installation<D>
```

```rust
impl<D = UreqDownloader> !UnwindSafe for Installation<D>
```

```rust
impl<D> Freeze for Installation<D>
where D: Freeze,
```

```rust
impl<D> Send for Installation<D>
where D: Send,
```

```rust
impl<D> Sync for Installation<D>
where D: Sync,
```

```rust
impl<D> Unpin for Installation<D>
where D: Unpin,
```

```rust
impl<D> UnsafeUnpin for Installation<D>
where D: UnsafeUnpin,
```

--------------------------------

### Installation::recover

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

Recovers an interrupted activation.

```APIDOC
## pub fn recover(&self) -> Result<bool>

### Description
Recover an interrupted activation, returning whether managed state was found.

### Returns
- **Result<bool>** - True if managed state was found and recovered.
```

--------------------------------

### FromIterator Implementation Examples

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Demonstrates collecting Results into a container, showing short-circuiting behavior on error.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

--------------------------------

### Unwrap or Else Example

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Demonstrates using unwrap_or_else to provide a fallback value.

```rust
assert_eq!(Ok(2).unwrap_or_else(count), 2);
assert_eq!(Err("foo").unwrap_or_else(count), 3);
```

--------------------------------

### Copying Result Contents

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Examples of copying or cloning the contents of an Ok variant from a reference.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### IntoIterator Implementation Examples

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Demonstrates converting a Result into an iterator that yields the contained value if Ok.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);

let x: Result<u32, &str> = Err("nothing!");
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);
```

--------------------------------

### Unchecked Unwrap Examples

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Demonstrates unsafe methods to extract values from Result without runtime checks.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### Result Type Definition

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

The core type alias definition for the installation result.

```rust
pub type Result<T> = Result<T, InstallError>;
```

--------------------------------

### Get Result References with as_ref

Source: https://docs.rs/relswap/0.0.2/relswap/release/type.Result.html

Converts a Result reference into a Result containing references.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Blanket Trait Implementations

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.Installation.html

Standard blanket trait implementations available for the Installation struct.

```rust
impl<T> Any for T
where T: 'static + ?Sized,
```

```rust
fn type_id(&self) -> TypeId
```

```rust
impl<T> Borrow<T> for T
where T: ?Sized,
```

```rust
fn borrow(&self) -> &T
```

```rust
impl<T> BorrowMut<T> for T
where T: ?Sized,
```

```rust
fn borrow_mut(&mut self) -> &mut T
```

```rust
impl<T> From<T> for T
```

```rust
fn from(t: T) -> T
```

```rust
impl<T, U> Into<U> for T
where U: From<T>,
```

```rust
fn into(self) -> U
```

```rust
impl<T> Same for T
```

```rust
type Output = T
```

```rust
impl<T, U> TryFrom<U> for T
where U: Into<T>,
```

```rust
type Error = Infallible
```

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

```rust
impl<T, U> TryInto<U> for T
where U: TryFrom<T>,
```

```rust
type Error = <U as TryFrom<T>>::Error
```

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### pub fn read_symlink(path: &Path) -> Result<Option<PathBuf>>

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.read_symlink.html

Reads a Unix selector symlink without following it. On Windows, this function returns None, as managed installations use the UTF-8 'active' file instead.

```APIDOC
## read_symlink

### Signature
`pub fn read_symlink(path: &Path) -> Result<Option<PathBuf>>`

### Description
Reads a Unix selector symlink without following it. On Windows this returns `None`; managed installations use the UTF-8 `active` file instead.

### Parameters
- **path** (&Path) - The path to the symlink to be read.

### Returns
- **Result<Option<PathBuf>>** - Returns the path the symlink points to if successful, None if on Windows or if the symlink cannot be read.
```

--------------------------------

### Unchecked Error Unwrap Examples

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Demonstrates unsafe methods to extract error values from Result without runtime checks.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
```

--------------------------------

### LauncherInfo::new

Source: https://docs.rs/relswap/0.0.2/relswap/release/manifest/struct.LauncherInfo.html

Creates a new instance of the LauncherInfo struct.

```APIDOC
## pub fn new(path: impl Into<String>, protocol: u32, size: u64, sha256: impl Into<String>) -> Self

### Description
Constructs a new `LauncherInfo` instance with the specified path, protocol, size, and SHA256 hash.

### Parameters
- **path** (impl Into<String>) - The file path for the launcher.
- **protocol** (u32) - The protocol identifier.
- **size** (u64) - The size of the launcher file.
- **sha256** (impl Into<String>) - The SHA256 hash of the launcher file.
```

--------------------------------

### Product implementation for Result

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Demonstrates using the product method on an iterator of Results, which short-circuits on the first Err encountered.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### UreqDownloader::new

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/struct.UreqDownloader.html

Creates a new instance of UreqDownloader.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new instance of the UreqDownloader configured for production operations.

### Returns
- **Self** - A new instance of UreqDownloader.
```

--------------------------------

### create_new_file

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.create_new_file.html

Creates a regular file without replacing an existing path, writes it fully, and syncs it. This is primarily used for the Windows launcher.

```APIDOC
## Function: create_new_file

### Description
Creates a regular file without replacing an existing path, writes it fully, and syncs it. This is used for the Windows launcher, whose ownership contract forbids self-updating an existing launcher.

### Signature
`pub fn create_new_file(path: &Path, bytes: &[u8], mode: Option<u32>) -> Result<()>`

### Parameters
- **path** (&Path) - The file system path where the new file should be created.
- **bytes** (&[u8]) - The content to be written to the file.
- **mode** (Option<u32>) - Optional file permissions mode.

### Returns
- **Result<()>** - Returns Ok(()) on success, or an error if the file could not be created or written.
```

--------------------------------

### verify_manifest

Source: https://docs.rs/relswap/0.0.2/relswap/release/signature/fn.verify_manifest.html

Verifies a manifest using the consumer's App::trust_anchor. An empty key set fails closed.

```APIDOC
## Function: verify_manifest

### Description
Verifies a manifest using the consumer's `App::trust_anchor`. An empty key set fails closed.

### Signature
`pub fn verify_manifest(app: &App, manifest_bytes: &[u8], signature_bytes: &[u8]) -> Result<VerifiedSignature>`

### Parameters
- **app** (&App) - Required - The application context containing the trust anchor.
- **manifest_bytes** (&[u8]) - Required - The raw bytes of the manifest to verify.
- **signature_bytes** (&[u8]) - Required - The raw bytes of the signature to verify against.

### Returns
- **Result<VerifiedSignature>** - Returns a `VerifiedSignature` on success, or an error if verification fails.
```

--------------------------------

### ActivationBoundary Enum Variants

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.ActivationBoundary.html

The ActivationBoundary enum defines the specific fault points available during installation.

```rust
pub enum ActivationBoundary {
    LockAcquired,
    StagingCreated,
    PayloadWritten,
    Verified,
    StagingSynced,
    VersionRenamed,
    SelfTested,
    PendingWritten,
    PointerSwitched,
    InstallWritten,
    PendingRemoved,
    ParentsSynced,
}
```

--------------------------------

### Function Signature for run_windows_launcher

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.run_windows_launcher.html

The function signature for executing a Windows launcher artifact.

```rust
pub fn run_windows_launcher(payload_name: &str) -> Result<i32>
```

--------------------------------

### Manager Type Alias Definition

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Manager.html

Defines the Manager type alias as an alias for the Installation struct with a default UreqDownloader.

```rust
pub type Manager<D = UreqDownloader> = Installation<D>;
```

--------------------------------

### fn fetch(&self, url: &Url, max_bytes: usize) -> Result<DownloadResponse>

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/trait.Downloader.html

Fetches content from a specified URL up to a maximum byte limit.

```APIDOC
## fn fetch(&self, url: &Url, max_bytes: usize) -> Result<DownloadResponse>

### Description
Fetches data from the provided URL. The operation is constrained by a maximum byte limit to prevent excessive memory usage.

### Parameters
- **url** (&Url) - Required - The target URL to fetch data from.
- **max_bytes** (usize) - Required - The maximum number of bytes to download.

### Returns
- **Result<DownloadResponse>** - Returns a DownloadResponse on success, or an error if the fetch operation fails.
```

--------------------------------

### SignatureEnvelope::new

Source: https://docs.rs/relswap/0.0.2/relswap/release/signature/struct.SignatureEnvelope.html

Creates a new SignatureEnvelope instance with the provided signatures.

```APIDOC
## pub fn new(signatures: Vec<SignatureEntry>) -> Self

### Description
Creates a new instance of `SignatureEnvelope` containing the specified list of signatures.

### Parameters
- **signatures** (Vec<SignatureEntry>) - The list of signature entries to include in the envelope.
```

--------------------------------

### Define FaultPoint Enum

Source: https://docs.rs/relswap/0.0.2/relswap/install/enum.FaultPoint.html

The FaultPoint enum lists various stages of the installation process used for fault injection modeling.

```rust
pub enum FaultPoint {
    LockAcquired,
    StagingCreated,
    PayloadWritten,
    Verified,
    StagingSynced,
    VersionRenamed,
    SelfTested,
    PendingWritten,
    PointerSwitched,
    InstallWritten,
    PendingRemoved,
    ParentsSynced,
}
```

--------------------------------

### fetch_version_metadata_with_keys

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.fetch_version_metadata_with_keys.html

Retrieves release metadata for a given version, verifying it against a list of trusted keys.

```APIDOC
## Function: fetch_version_metadata_with_keys

### Description
Fetches the release metadata for a specified version from a repository. The function requires a downloader implementation and a list of trusted keys to validate the metadata.

### Signature
`pub fn fetch_version_metadata_with_keys<D: Downloader>(app: &App, downloader: &D, repository: &Url, version: &Version, trusted_keys: &[TrustedKey]) -> Result<ReleaseMetadata>`

### Parameters
- **app** (&App) - The application context.
- **downloader** (&D) - An implementation of the Downloader trait used to fetch the data.
- **repository** (&Url) - The URL of the repository to fetch from.
- **version** (&Version) - The specific version to retrieve metadata for.
- **trusted_keys** (&[TrustedKey]) - A slice of trusted keys used for verification.

### Returns
- **Result<ReleaseMetadata>** - Returns the ReleaseMetadata on success, or an error if the fetch or verification fails.
```

--------------------------------

### UreqDownloader::fetch

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/struct.UreqDownloader.html

Fetches content from a specified URL with a byte limit.

```APIDOC
## pub fn fetch(&self, url: &Url, max_bytes: usize) -> Result<DownloadResponse>

### Description
Fetches data from the provided URL, enforcing a maximum byte limit for the download.

### Parameters
- **url** (&Url) - The URL to download from.
- **max_bytes** (usize) - The maximum number of bytes to download.

### Returns
- **Result<DownloadResponse>** - A result containing the download response or an error if the fetch fails.
```

--------------------------------

### verify_manifest_with_keys

Source: https://docs.rs/relswap/0.0.2/relswap/release/signature/fn.verify_manifest_with_keys.html

Verifies a manifest against a set of trusted keys.

```APIDOC
## verify_manifest_with_keys

### Description
Verify using explicitly supplied trusted keys. This is the injection seam for deterministic tests and release tooling that owns a key set separately from the application binary.

### Signature
`pub fn verify_manifest_with_keys(manifest_bytes: &[u8], signature_bytes: &[u8], trusted_keys: &[TrustedKey]) -> Result<VerifiedSignature>`

### Parameters
- **manifest_bytes** (&[u8]) - The raw bytes of the manifest to verify.
- **signature_bytes** (&[u8]) - The raw bytes of the signature.
- **trusted_keys** (&[TrustedKey]) - A slice of trusted keys to use for verification.

### Returns
- **Result<VerifiedSignature>** - Returns a VerifiedSignature on success, or an error if verification fails.
```

--------------------------------

### fetch_version_metadata_with_keys function signature

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.fetch_version_metadata_with_keys.html

The function signature for fetching version metadata using a downloader and trusted keys.

```rust
pub fn fetch_version_metadata_with_keys<D: Downloader>(
    app: &App,
    downloader: &D,
    repository: &Url,
    version: &Version,
    trusted_keys: &[TrustedKey],
) -> Result<ReleaseMetadata>
```

--------------------------------

### pub fn current_exe() -> Result<PathBuf>

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.current_exe.html

Retrieves the path of the current executable, resolving launcher symlinks. It ensures the returned path points to a regular file.

```APIDOC
## Function: current_exe

### Description
Returns the executable that started the current process, after resolving a launcher symlink when the platform can do so. A regular file is required; the function ensures that directories, FIFOs, or other indirections are not returned as the payload.

### Signature
`pub fn current_exe() -> Result<PathBuf>`

### Returns
- **Result<PathBuf>** - A Result containing the PathBuf to the executable on success, or an error if the path could not be resolved or is not a regular file.
```

--------------------------------

### into_ok

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Returns the contained Ok value without panicking.

```APIDOC
### pub const fn into_ok(self) -> T

Returns the contained `Ok` value, but never panics. This is a nightly-only experimental API.
```

--------------------------------

### run_windows_launcher

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.run_windows_launcher.html

Executes the Windows launcher artifact for a given payload name.

```APIDOC
## run_windows_launcher

### Signature
`pub fn run_windows_launcher(payload_name: &str) -> Result<i32>`

### Description
Executes the Windows launcher artifact. This function is intended for Windows environments; on other platforms, it acts as a stub to allow build checks to proceed without attempting execution.

### Parameters
- **payload_name** (&str) - Required - The name of the binary or payload to be launched.

### Returns
- **Result<i32>** - Returns the exit code of the process on success, or an error if the execution fails.
```

--------------------------------

### sign_manifest_multi

Source: https://docs.rs/relswap/0.0.2/relswap/release/signature/fn.sign_manifest_multi.html

Signs a manifest with multiple keys and returns a signature envelope.

```APIDOC
## Function: sign_manifest_multi

### Description
Signs the provided manifest bytes using a collection of key-pair references.

### Signature
`pub fn sign_manifest_multi<K: AsRef<str>>(manifest_bytes: &[u8], keys: &[(K, &SigningKey)]) -> SignatureEnvelope`

### Parameters
- **manifest_bytes** (&[u8]) - The raw bytes of the manifest to be signed.
- **keys** (&[(K, &SigningKey)]) - A slice of tuples, where each tuple contains a key identifier (K) and a reference to a SigningKey.

### Returns
- **SignatureEnvelope** - The resulting signature envelope containing the signed manifest data.
```

--------------------------------

### pub fn sync_dir(path: &Path) -> Result<()>

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.sync_dir.html

Synchronizes a directory after a rename or replacement. On Unix, this performs a directory fsync. On Windows, it relies on the atomic-replacement path as the platform does not provide a portable directory handle contract.

```APIDOC
## Function: sync_dir

### Description
Syncs a directory after a rename or replacement operation. This ensures that changes are persisted to the underlying storage.

### Signature
`pub fn sync_dir(path: &Path) -> Result<()>`

### Parameters
- **path** (&Path) - The path to the directory that needs to be synchronized.

### Platform Behavior
- **Unix**: Performs a directory fsync.
- **Windows**: Does not provide a portable directory handle contract; relies on `MOVEFILE_WRITE_THROUGH` and the synced file to cover the atomic-replacement path.
```

--------------------------------

### Re-exporting the Windows launcher

Source: https://docs.rs/relswap/0.0.2/relswap/launcher/index.html

The module re-exports the run_windows_launcher function from the crate's fs::executable module as run.

```rust
pub use crate::fs::executable::run_windows_launcher as run;
```

--------------------------------

### Define LauncherInfo Struct

Source: https://docs.rs/relswap/0.0.2/relswap/release/manifest/struct.LauncherInfo.html

The structure definition for LauncherInfo, containing fields for path, hash, size, and protocol.

```rust
pub struct LauncherInfo {
    pub path: String,
    pub sha256: String,
    pub size: u64,
    pub protocol: u32,
}
```

--------------------------------

### ReleaseManifest Struct Definition

Source: https://docs.rs/relswap/0.0.2/relswap/release/manifest/struct.ReleaseManifest.html

The core data structure for release metadata.

```rust
pub struct ReleaseManifest {
    pub schema_version: u32,
    pub version: Version,
    pub published_at: String,
    pub expires_at: String,
    pub targets: BTreeMap<Target, ReleaseAsset>,
}
```

--------------------------------

### pub fn current_executable() -> Result<PathBuf>

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.current_executable.html

Retrieves the path to the current executable as a Result containing a PathBuf.

```APIDOC
## Function: current_executable

### Description
Returns the path to the current executable. This is a descriptive alias for the standard `current_exe` function.

### Signature
`pub fn current_executable() -> Result<PathBuf>`

### Returns
- **Result<PathBuf>** - Returns the path to the current executable on success, or an error if the path cannot be determined.
```

--------------------------------

### Check and Recovery Methods

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Manager.html

Methods for checking the latest version and recovering interrupted activations.

```APIDOC
## check_latest()

### Description
Fetch only signed latest metadata and report the authoritative current pointer.

## check()

### Description
Descriptive alias for check_latest().

## recover_if_managed()

### Description
Recover an interrupted activation if the installation root already exists.

## recover()

### Description
Recover an interrupted activation, returning whether managed state was found.
```

--------------------------------

### verify_manifest_with_keys function signature

Source: https://docs.rs/relswap/0.0.2/relswap/release/signature/fn.verify_manifest_with_keys.html

The function signature for verifying manifest signatures with explicit trusted keys.

```rust
pub fn verify_manifest_with_keys(
    manifest_bytes: &[u8],
    signature_bytes: &[u8],
    trusted_keys: &[TrustedKey],
) -> Result<VerifiedSignature>
```

--------------------------------

### fetch_latest_metadata_with_keys

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.fetch_latest_metadata_with_keys.html

Retrieves the latest release metadata using a provided downloader and a set of trusted keys.

```APIDOC
## Function: fetch_latest_metadata_with_keys

### Description
Injects trusted keys while resolving the latest metadata. This function is intended as a deterministic test or tooling seam.

### Signature
`pub fn fetch_latest_metadata_with_keys<D: Downloader>(app: &App, downloader: &D, repository: &Url, trusted_keys: &[TrustedKey]) -> Result<ReleaseMetadata>`

### Parameters
- **app** (&App) - The application context.
- **downloader** (&D) - The downloader implementation to use.
- **repository** (&Url) - The URL of the repository to fetch metadata from.
- **trusted_keys** (&[TrustedKey]) - A slice of trusted keys used for verification.

### Returns
- **Result<ReleaseMetadata>** - Returns the release metadata if successful, or an error if the operation fails.
```

--------------------------------

### pub fn atomic_replace_file(path: &Path, bytes: &[u8]) -> Result<()>

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.atomic_replace_file.html

Replaces a regular file at the specified path with the provided bytes atomically and durably. It creates a temporary file, writes the data, and syncs it before performing the final replacement.

```APIDOC
## Function: atomic_replace_file

### Description
Replace a regular file atomically and durably. The temporary file is created beside the destination, written and synced before the final replace, so a crash exposes either the old complete file or the new complete file.

### Signature
`pub fn atomic_replace_file(path: &Path, bytes: &[u8]) -> Result<()>`

### Parameters
- **path** (&Path) - The destination path of the file to be replaced.
- **bytes** (&[u8]) - The content to write to the file.

### Returns
- **Result<()>** - Returns Ok(()) on success, or an error if the operation fails.
```

--------------------------------

### set_executable

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.set_executable.html

Changes a file at the specified path into an executable without following links.

```APIDOC
## set_executable

### Description
Changes a payload into an executable without following a link.

### Signature
`pub fn set_executable(path: &Path) -> Result<()>`

### Parameters
- **path** (&Path) - Required - The file system path to the file that should be made executable.
```

--------------------------------

### pub fn atomic_replace_file_with_mode

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.atomic_replace_file_with_mode.html

Replaces the content of a file at the specified path atomically, with an optional Unix mode for the new file.

```APIDOC
## Function: atomic_replace_file_with_mode

### Description
Replaces the content of a file at a given path with the provided bytes in an atomic operation. Allows for an optional Unix mode to be set on the newly created file.

### Signature
`pub fn atomic_replace_file_with_mode(path: &Path, bytes: &[u8], mode: Option<u32>) -> Result<()>`

### Parameters
- **path** (&Path) - The filesystem path to the file to be replaced.
- **bytes** (&[u8]) - The data to write to the file.
- **mode** (Option<u32>) - An optional Unix file mode to apply to the file.

### Returns
- **Result<()>** - Returns Ok(()) on success, or an error if the operation fails.
```

--------------------------------

### fetch_exact_metadata Function Signature

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.fetch_exact_metadata.html

The function signature for fetching specific release metadata using a provided downloader.

```rust
pub fn fetch_exact_metadata<D: Downloader>(
    app: &App,
    downloader: &D,
    repository: &Url,
    version: &Version,
) -> Result<ReleaseMetadata>
```

--------------------------------

### LauncherMetadata Struct Definition

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.LauncherMetadata.html

The structure definition for LauncherMetadata, containing fields for path, SHA256 hash, file size, and protocol version.

```rust
pub struct LauncherMetadata {
    pub path: String,
    pub sha256: String,
    pub size: u64,
    pub protocol: u32,
}
```

--------------------------------

### fetch_exact_metadata

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.fetch_exact_metadata.html

Fetches and verifies a specific release version without consulting the moving latest endpoint.

```APIDOC
## Function: fetch_exact_metadata

### Description
Fetch and verify a specific release version without consulting the moving `latest` endpoint.

### Signature
`pub fn fetch_exact_metadata<D: Downloader>(app: &App, downloader: &D, repository: &Url, version: &Version) -> Result<ReleaseMetadata>`

### Parameters
- **app** (&App) - The application context.
- **downloader** (&D) - The downloader implementation.
- **repository** (&Url) - The URL of the repository.
- **version** (&Version) - The specific version to fetch.

### Returns
- **Result<ReleaseMetadata>** - Returns the release metadata if successful, or an error.
```

--------------------------------

### DownloadedArchive Struct Definition

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/struct.DownloadedArchive.html

The structure definition for DownloadedArchive, containing the target, name, and byte content.

```rust
pub struct DownloadedArchive {
    pub target: Target,
    pub name: String,
    pub bytes: Vec<u8>,
}
```

--------------------------------

### App Struct Definition

Source: https://docs.rs/relswap/0.0.2/relswap/app/struct.App.html

The primary configuration structure for the application, requiring static references for all fields.

```rust
pub struct App {
    pub name: &'static str,
    pub version: &'static str,
    pub repository_url: &'static str,
    pub trust_anchor: &'static [u8],
    pub activation: ActivationStrategy,
    pub self_test: Option<SelfTest>,
}
```

--------------------------------

### Unwrap Result or Default

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Returns the Ok value or the default value of the type if the result is Err.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### pub fn sha256_file(path: &Path) -> Result<String>

Source: https://docs.rs/relswap/0.0.2/relswap/release/fn.sha256_file.html

Computes the SHA-256 hash of a file at the specified path. This implementation is memory-efficient as it does not load the entire file content into memory at once.

```APIDOC
## sha256_file

### Signature
`pub fn sha256_file(path: &Path) -> Result<String>`

### Description
Hashes a file without loading it into memory as a whole.

### Parameters
- **path** (&Path) - The path to the file to be hashed.

### Returns
- **Result<String>** - Returns a Result containing the SHA-256 hash string on success, or an error if the file cannot be read.
```

--------------------------------

### verify_manifest function signature

Source: https://docs.rs/relswap/0.0.2/relswap/release/signature/fn.verify_manifest.html

The function signature for verifying a manifest with an App instance, manifest bytes, and signature bytes.

```rust
pub fn verify_manifest(
    app: &App,
    manifest_bytes: &[u8],
    signature_bytes: &[u8],
) -> Result<VerifiedSignature>
```

--------------------------------

### pub fn write_private_file(path: &Path, bytes: &[u8]) -> Result<()>

Source: https://docs.rs/relswap/0.0.2/relswap/fs/security/fn.write_private_file.html

Writes the provided bytes to a new file at the specified path with restricted permissions. It ensures parent directories are created as private and uses create_new to prevent overwriting existing files.

```APIDOC
## Function: write_private_file

### Description
Writes `bytes` to a new file with mode `0600` (Unix) or an inherited private ACL (Windows). This function creates parent directories as private if they are missing and uses `create_new` to ensure that an existing path is never truncated.

### Signature
`pub fn write_private_file(path: &Path, bytes: &[u8]) -> Result<()>`

### Parameters
- **path** (&Path) - The destination file path.
- **bytes** (&[u8]) - The data to be written to the file.

### Returns
- **Result<()>** - Returns `Ok(())` on success, or an error if the file creation fails.
```

--------------------------------

### fetch_latest_metadata Function Signature

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.fetch_latest_metadata.html

The function signature for fetching and verifying release metadata, requiring an App, a Downloader, and a repository URL.

```rust
pub fn fetch_latest_metadata<D: Downloader>(
    app: &App,
    downloader: &D,
    repository: &Url,
) -> Result<ReleaseMetadata>
```

--------------------------------

### pub fn download_archive<D: Downloader>

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.download_archive.html

Downloads and verifies a selected target archive after metadata resolution.

```APIDOC
## Function: download_archive

### Description
Download and verify one selected target archive after metadata resolution.

### Signature
`pub fn download_archive<D: Downloader>(app: &App, downloader: &D, metadata: &ReleaseMetadata, target: Target) -> Result<DownloadedArchive>`

### Parameters
- **app** (&App) - The application context.
- **downloader** (&D) - The downloader implementation (must implement the Downloader trait).
- **metadata** (&ReleaseMetadata) - The release metadata used for resolution.
- **target** (Target) - The specific target to download.

### Returns
- **Result<DownloadedArchive>** - Returns a Result containing the DownloadedArchive on success, or an error if the download or verification fails.
```

--------------------------------

### download_archive function signature

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.download_archive.html

The function signature for downloading and verifying a target archive.

```rust
pub fn download_archive<D: Downloader>(
    app: &App,
    downloader: &D,
    metadata: &ReleaseMetadata,
    target: Target,
) -> Result<DownloadedArchive>
```

--------------------------------

### unwrap

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Returns the contained Ok value, consuming the self value. Panics if the value is an Err.

```APIDOC
### pub fn unwrap(self) -> T

Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`, with a panic message provided by the `Err`’s value.
```

--------------------------------

### create_new_file function signature

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.create_new_file.html

The function signature for creating a new file with specified path, content, and optional mode.

```rust
pub fn create_new_file(
    path: &Path,
    bytes: &[u8],
    mode: Option<u32>,
) -> Result<()>
```

--------------------------------

### fetch_latest_metadata_with_keys function signature

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.fetch_latest_metadata_with_keys.html

The function signature for fetching metadata with trusted keys, requiring a downloader implementation and repository URL.

```rust
pub fn fetch_latest_metadata_with_keys<D: Downloader>(
    app: &App,
    downloader: &D,
    repository: &Url,
    trusted_keys: &[TrustedKey],
) -> Result<ReleaseMetadata>
```

--------------------------------

### pub fn unwrap(self) -> T

Source: https://docs.rs/relswap/0.0.2/relswap/release/type.Result.html

Returns the contained Ok value, consuming the self value. Panics if the value is an Err.

```APIDOC
## pub fn unwrap(self) -> T

### Description
Returns the contained `Ok` value, consuming the `self` value. Because this function may panic, its use is generally discouraged.

### Parameters
- **self** (Result<T, E>) - The Result instance to unwrap.

### Returns
- **T** - The contained `Ok` value.

### Panics
Panics if the value is an `Err`, with a panic message provided by the `Err`’s value.
```

--------------------------------

### pub fn inspect_archive

Source: https://docs.rs/relswap/0.0.2/relswap/release/archive/fn.inspect_archive.html

Inspects every archive member, verifies the selected payload and optional launcher, and returns their bytes without writing any unrelated member to disk.

```APIDOC
## inspect_archive

### Description
Inspect every archive member, verify the selected payload and optional launcher, and return their bytes without writing any unrelated member to disk.

### Signature
`pub fn inspect_archive(app: &App, bytes: &[u8], asset: &ReleaseAsset) -> Result<ExtractedRelease>`

### Parameters
- **app** (&App) - The application context.
- **bytes** (&[u8]) - The raw bytes of the archive.
- **asset** (&ReleaseAsset) - The release asset to inspect.

### Returns
- **Result<ExtractedRelease>** - Returns an ExtractedRelease object on success, or an error if inspection or verification fails.
```

--------------------------------

### sign_manifest

Source: https://docs.rs/relswap/0.0.2/relswap/release/signature/fn.sign_manifest.html

Signs manifest bytes with an Ed25519 key.

```APIDOC
## Function: sign_manifest

### Description
Signs manifest bytes with one Ed25519 key for release tooling.

### Signature
`pub fn sign_manifest(manifest_bytes: &[u8], key_id: impl Into<String>, signing_key: &SigningKey) -> SignatureEnvelope`

### Parameters
- **manifest_bytes** (&[u8]) - The raw bytes of the manifest to be signed.
- **key_id** (impl Into<String>) - The identifier for the signing key.
- **signing_key** (&SigningKey) - The Ed25519 signing key used to generate the signature.

### Returns
- **SignatureEnvelope** - The resulting signature envelope containing the signed data.
```

--------------------------------

### pub fn and_then<U, F>(self, op: F) -> Result<U, E>

Source: https://docs.rs/relswap/0.0.2/relswap/release/type.Result.html

Calls op if the result is Ok, otherwise returns the Err value of self.

```APIDOC
## pub fn and_then<U, F>(self, op: F) -> Result<U, E>

### Description
Calls `op` if the result is `Ok`, otherwise returns the `Err` value of `self`. This function can be used for control flow based on `Result` values.

### Parameters
- **self** (Result<T, E>) - The Result instance.
- **op** (F) - A function that takes the `Ok` value and returns a new `Result`.

### Returns
- **Result<U, E>** - The result of the operation or the original error.
```

--------------------------------

### Provide default value with unwrap_or

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Returns the contained Ok value or a provided default value. Arguments are eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### Define MAX_REDIRECTS constant

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/constant.MAX_REDIRECTS.html

Represents the maximum number of redirects permitted, set to 8.

```rust
pub const MAX_REDIRECTS: u32 = 8;
```

--------------------------------

### fetch_latest_metadata

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.fetch_latest_metadata.html

Fetches and verifies the latest release metadata from a repository.

```APIDOC
## fetch_latest_metadata

### Description
Fetches and verifies the latest release metadata. This function does not download the archive.

### Signature
`pub fn fetch_latest_metadata<D: Downloader>(app: &App, downloader: &D, repository: &Url) -> Result<ReleaseMetadata>`

### Parameters
- **app** (&App) - The application context.
- **downloader** (&D) - The downloader implementation.
- **repository** (&Url) - The URL of the repository to fetch metadata from.

### Returns
- **Result<ReleaseMetadata>** - The release metadata if successful, or an error.
```

--------------------------------

### Define PendingActivation struct

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.PendingActivation.html

The structure used for the activation journal, where a null 'from' field indicates a first-install transaction.

```rust
pub struct PendingActivation {
    pub schema_version: u32,
    pub from: Option<Version>,
    pub to: Version,
    pub transaction_id: String,
}
```

--------------------------------

### unwrap_or_default

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Returns the contained Ok value or a default value if the result is Err.

```APIDOC
### pub fn unwrap_or_default(self) -> T

Consumes the `self` argument then, if `Ok`, returns the contained value, otherwise if `Err`, returns the default value for that type.
```

--------------------------------

### pub fn verify_archive_file

Source: https://docs.rs/relswap/0.0.2/relswap/release/archive/fn.verify_archive_file.html

Reads and verifies an archive file before parsing it.

```APIDOC
## Function: verify_archive_file

### Description
Reads and verifies an archive file before parsing it.

### Signature
`pub fn verify_archive_file(app: &App, path: &Path, asset: &ReleaseAsset) -> Result<()>`

### Parameters
- **app** (&App) - Reference to the application instance.
- **path** (&Path) - The file system path to the archive file.
- **asset** (&ReleaseAsset) - The release asset metadata associated with the archive.

### Returns
- **Result<()>** - Returns Ok(()) if the verification is successful, or an error if the file is invalid or cannot be read.
```

--------------------------------

### sync_dir function signature

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.sync_dir.html

The function signature for synchronizing a directory path.

```rust
pub fn sync_dir(path: &Path) -> Result<()>
```

--------------------------------

### Define ReleaseAsset structure

Source: https://docs.rs/relswap/0.0.2/relswap/release/manifest/type.Asset.html

The ReleaseAsset struct contains fields for archive metadata, payload information, and optional launcher details.

```rust
pub struct Asset {
    pub archive: String,
    pub archive_sha256: String,
    pub archive_size: u64,
    pub payload: PayloadInfo,
    pub launcher: Option<LauncherInfo>,
}
```

--------------------------------

### pub fn rename_new(source: &Path, destination: &Path) -> Result<()>

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.rename_new.html

Renames a newly-created directory without intentionally replacing a prior version. This function helps prevent race conditions by ensuring the operation does not silently overwrite existing files.

```APIDOC
## Function: rename_new

### Description
Renames a newly-created directory without intentionally replacing a prior version. Callers should check for existence first; the platform-specific no-replace operation prevents ordinary races from silently merging or overwriting a retained version.

### Signature
`pub fn rename_new(source: &Path, destination: &Path) -> Result<()>`

### Parameters
- **source** (&Path) - The path to the source directory.
- **destination** (&Path) - The path to the destination directory.

### Returns
- **Result<()>** - Returns Ok(()) on success, or an error if the operation fails.
```

--------------------------------

### Expect Value with expect

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Returns the Ok value or panics with the provided message if the result is Err.

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### ReleaseManifest Structure Definition

Source: https://docs.rs/relswap/0.0.2/relswap/release/manifest/type.Manifest.html

The underlying structure for Manifest, containing schema version, versioning, timestamps, and target assets.

```rust
pub struct Manifest {
    pub schema_version: u32,
    pub version: Version,
    pub published_at: String,
    pub expires_at: String,
    pub targets: BTreeMap<Target, ReleaseAsset>,
}
```

--------------------------------

### exact_metadata_url

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/fn.exact_metadata_url.html

Constructs the exact metadata URL for a specific application version within a repository.

```APIDOC
## Function: exact_metadata_url

### Description
Constructs the exact metadata URL for a given application, repository, and version.

### Signature
`pub fn exact_metadata_url(app: &App, repository: &Url, version: &Version) -> Result<Url>`

### Parameters
- **app** (&App) - The application instance.
- **repository** (&Url) - The base URL of the repository.
- **version** (&Version) - The specific version to target.

### Returns
- **Result<Url>** - Returns the constructed URL on success, or an error if the URL cannot be formed.
```

--------------------------------

### set_executable function signature

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.set_executable.html

The function signature for setting executable permissions on a given path.

```rust
pub fn set_executable(path: &Path) -> Result<()>
```

--------------------------------

### atomic_switch_symlink

Source: https://docs.rs/relswap/0.0.2/relswap/fs/executable/fn.atomic_switch_symlink.html

Atomically switch a Unix selector symlink to an absolute target. This function is specific to Unix-like systems and is not available on Windows.

```APIDOC
## Function: atomic_switch_symlink

### Description
Atomically switch a Unix selector symlink to an absolute target. This is not available on Windows because the managed selector there is a regular UTF-8 file.

### Signature
`pub fn atomic_switch_symlink(path: &Path, target: &Path) -> Result<()>`

### Parameters
- **path** (&Path) - The path to the symlink to be updated.
- **target** (&Path) - The absolute path to which the symlink should point.

### Returns
- **Result<()>** - Returns Ok(()) on success, or an error if the operation fails.
```

--------------------------------

### DownloadResponse Struct Definition

Source: https://docs.rs/relswap/0.0.2/relswap/release/download/struct.DownloadResponse.html

The primary data structure used to store download results, including URL metadata and raw bytes.

```rust
pub struct DownloadResponse {
    pub requested_url: Url,
    pub final_url: Url,
    pub redirect_history: Vec<Url>,
    pub bytes: Vec<u8>,
}
```

--------------------------------

### Define ActivationStrategy Enum

Source: https://docs.rs/relswap/0.0.2/relswap/app/enum.ActivationStrategy.html

The enum structure defining strategies for Unix and Windows environments.

```rust
pub enum ActivationStrategy {
    UnixSymlink,
    WindowsLauncher {
        launcher_name: &'static str,
        protocol: u32,
    },
}
```

--------------------------------

### LauncherOwnership Struct Definition

Source: https://docs.rs/relswap/0.0.2/relswap/install/struct.LauncherOwnership.html

The primary data structure used to track launcher ownership state.

```rust
pub struct LauncherOwnership {
    pub owned: bool,
    pub path: String,
    pub sha256: String,
    pub size: u64,
    pub protocol: u32,
}
```

--------------------------------

### Fallback to alternative Result with or

Source: https://docs.rs/relswap/0.0.2/relswap/install/type.Result.html

Returns the current Result if it is Ok, otherwise returns the provided alternative Result. Note that arguments are eagerly evaluated.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```