Struct PluginArtifact 

pub struct PluginArtifact { /* private fields */ }

One file a consumer installs into a harness.

The destination is expressed as components relative to the user’s home directory rather than an absolute path, for the same reason crate::launch recipes never pick a location in the user’s home: the crate states where within a home the harness looks, and the consumer supplies the home it is installing into — which is also what makes the whole thing testable against a temporary directory.

Implementations

impl PluginArtifact

pub const fn file_name(&self) -> &'static str

The file name to write, without any directory part.

pub const fn install_dir_components(&self) -> &'static [&'static str]

The install directory’s path components, relative to the user’s home.

Exposed so an installer can describe the destination — in a dry run, say — without having a home directory to resolve against.

pub const fn contents(&self) -> &'static str

The asset’s full contents, embedded at compile time.

pub fn install_dir(&self, home: &Path) -> PathBuf

The directory this artifact installs into, beneath home.

pub fn install_path(&self, home: &Path) -> PathBuf

The full path this artifact installs to, beneath home.

pub const fn superseded_file_names(&self) -> &'static [&'static str]

File names in this artifact’s own install directory that a previous release of some client wrote, and that installing this artifact must remove.

Only meaningful for a harness that loads a directory rather than a file: there a superseded copy is not merely stale, it is a second reader, and it keeps running the behaviour this artifact replaced. pi is that harness, and its list names a file another client shipped — which is the whole reason the list is crate-owned. A client can be expected to know what it used to install; it cannot be expected to know what its competitor did, and removing only one’s own leaves the collision intact from the other direction.

This is the one place a vendor’s name may appear in this module. It is not carried into anything installed — it names bytes being deleted, not bytes being written — and the vendor-neutrality bar on PluginArtifact::contents is unaffected.

pub fn superseded_paths(&self, home: &Path) -> Vec<PathBuf>

The paths Self::install removes, beneath home.

Exposed for a consumer that owns its own write path — a content-keyed refresh, say — and needs the removal without the write.

pub fn install(&self, home: &Path) -> Result<PathBuf>

Write this artifact beneath home, creating its directory and removing every superseded sibling. Returns the path written.

The removal is not tidiness. A harness that auto-discovers a whole directory loads a superseded copy alongside this one, and two copies of a capture extension in one process destroy each other’s attribution — which means an install that only wrote would leave an upgrading user exactly as broken as before, with the new bytes on disk to prove the fix had shipped. Writing and removing therefore belong to one operation, not to each consumer’s good intentions.

Belonging to one operation is a claim about the failures too, and it constrains the order — because the state that must never be reached is both files present, and writing first reaches it the moment a removal fails. So the bytes are staged first under a name the harness’s glob cannot match, the superseded siblings are removed second, and the staged file is renamed onto its final name last. Each way that can fail leaves at most one extension where the harness looks:

• staging fails — nothing on disk changed;
• a superseded sibling exists and cannot be removed — the staged bytes are discarded and the error returned, so the user is left with the old copy still working rather than with a second reader;
• the rename fails — the superseded copy is gone and the new file never arrived, so capture is off, loudly, instead of on and silently unattributed.

Staging under a non-matching name buys a second thing: a harness reads that directory every time it starts a session, not once when an installer runs, so a session starting mid-write must not be able to find a half-written file spelled like something it loads.

A superseded file that is absent is not an error. One that exists and cannot be removed is: the caller has to know that the harness will still load it, and is better placed than this crate to decide whether that fails the launch or warns.

Errors

Any I/O failure creating the directory, staging the bytes, removing a superseded sibling that exists, or renaming the staged file into place. An error after staging takes the staged file with it, so a failed install never leaves debris in a directory the harness reads — but a rename that failed has already removed the superseded copies, and the caller is being told that nothing is installed.

Trait Implementations

impl Clone for PluginArtifact

fn clone(&self) -> PluginArtifact

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for PluginArtifact

impl Debug for PluginArtifact

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

Formats the value using the given formatter.

impl Eq for PluginArtifact

impl PartialEq for PluginArtifact

fn eq(&self, other: &PluginArtifact) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PluginArtifact