Trait QueryVersion

pub trait QueryVersion<Ref, Id, C, T, R>: QueryStore<Ref, T>
where
    C: FromIterator<UnpackedRef<Id, R>> + IntoIterator<Item = UnpackedRef<Id, R>>,
    Ref: UnpackRef<Id, R> + Debug,
    Self: Debug,
    T: Send,
{
    // Provided methods
    fn process_atoms(refs: Vec<Ref>) -> <C as IntoIterator>::IntoIter { ... }
    fn get_atoms(
        &self,
        transport: Option<&mut T>,
    ) -> Result<<C as IntoIterator>::IntoIter, <Self as QueryStore<Ref, T>>::Error> { ... }
    fn process_highest_match(
        atoms: <C as IntoIterator>::IntoIter,
        label: &Label,
        req: &VersionReq,
    ) -> Option<(Version, Id)> { ... }
    fn get_highest_match(
        &self,
        label: &Label,
        req: &VersionReq,
        transport: Option<&mut T>,
    ) -> Option<(Version, Id)> { ... }
    fn remote_atoms(
        &self,
        transport: Option<&mut T>,
    ) -> HashMap<Label, (Version, Id)> { ... }
}

A trait for querying version information about atoms in remote stores.

This trait extends QueryStore to provide high-level operations for working with atom versions. It enables efficient querying and filtering of atom versions based on labels and semantic version requirements.

Key Features

• Atom Discovery: Automatically discovers all atoms in the store using the standard reference pattern
• Version Filtering: Find atoms matching specific label and version requirements
• Semantic Versioning: Full support for semantic version constraints and comparison
• Type Safety: Strongly typed atom identifiers and version information

Architecture

The trait builds on top of QueryStore to provide:

1. Low-level reference querying (from QueryStore)
2. Atom reference parsing and unpacking
3. Version-based filtering and selection
4. Semantic version constraint matching

Use Cases

• Dependency Resolution: Find the highest version of an atom matching version requirements
• Atom Discovery: Enumerate all available atoms in a store
• Version Management: Check for atom updates and new versions
• Lock File Generation: Resolve atom versions for reproducible builds

Examples

use atom::Label;
use atom::store::{QueryStore, QueryVersion};
use gix::Url;
use semver::VersionReq;

// Query for atoms in a remote store
let url = gix::url::parse("https://github.com/example/atoms.git".into())?;

// Get all available atoms
let atoms = url.get_atoms(None)?;
for atom in atoms {
    println!(
        "Atom: {} v{} -> {}",
        atom.id.label(),
        atom.version,
        atom.rev
    );
}

// Find the highest version matching a requirement
let req = VersionReq::parse(">=1.0.0,<2.0.0")?;

if let Some((version, id)) = url.get_highest_match(&Label::try_from("mylib")?, &req, None) {
    println!("Selected version {} with id {}", version, id);
}

Provided Methods

fn process_atoms(refs: Vec<Ref>) -> <C as IntoIterator>::IntoIter

Processes an iterator of references, unpacking and collecting them into an iterator of atom information.

fn get_atoms( &self, transport: Option<&mut T>, ) -> Result<<C as IntoIterator>::IntoIter, <Self as QueryStore<Ref, T>>::Error>

Retrieves all atoms available in the remote store.

This method queries the store for all atom references using the standard refs/atoms/* pattern and unpacks them into structured atom information.

Returns

An iterator over all discovered atoms, where each atom contains:

• Label: The atom’s identifying name
• Version: The semantic version of the atom
• Id: The unique identifier for this atom version

Errors

Returns an error if the reference query fails or if reference parsing fails.

fn process_highest_match( atoms: <C as IntoIterator>::IntoIter, label: &Label, req: &VersionReq, ) -> Option<(Version, Id)>

Processes an iterator of atoms to find the highest version matching the given label and version requirement.

fn get_highest_match( &self, label: &Label, req: &VersionReq, transport: Option<&mut T>, ) -> Option<(Version, Id)>

Finds the highest version of an atom matching the given version requirement.

This method searches through all available atom versions for a specific label and returns the highest version that satisfies the provided version requirement. Uses semantic version comparison to determine “highest” version.

Arguments

• label - The atom label to search for (e.g., “mylib”, “database”)
• req - The version requirement to match (e.g., “>=1.0.0”, “~2.1.0”)

Returns

The highest matching version and its identifier, or None if no versions match.

Examples

use atom::Label;
use atom::store::QueryVersion;
use semver::VersionReq;

let url = gix::url::parse("https://example.com/my-repo.git".into())?;
let req = VersionReq::parse(">=1.0.0,<2.0.0")?;
let result = url.get_highest_match(&Label::try_from("mylib")?, &req, None);

fn remote_atoms( &self, transport: Option<&mut T>, ) -> HashMap<Label, (Version, Id)>

Retrieves all atoms from the remote store and maps them by their label.

This method provides a convenient way to get a comprehensive overview of all atoms available in the remote store, organized by their unique Label. If an atom has multiple versions, only the highest version is returned.

Returns

A HashMap where:

• The key is the Label, representing the unique identifier of the atom.
• The value is a tuple containing the Version and Id of the atom.

If the remote store cannot be reached or if there are no atoms, an empty HashMap is returned.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl QueryVersion<Ref, ObjectId, Vec<UnpackedRef<ObjectId, Root>>, Box<dyn Transport + Send>, Root> for Url

impl<'repo> QueryVersion<Ref, ObjectId, Vec<UnpackedRef<ObjectId, Root>>, Box<dyn Transport + Send>, Root> for Remote<'repo>

Implementors