Struct ArtifactId

Source

pub struct ArtifactId<H: HashAlgorithm> { /* private fields */ }

Expand description

A universally reproducible software identifier.

This is a content-based unique identifier for any software artifact.

It is built around, per the specification, any supported hash algorithm. Currently, only SHA-256 is supported, but others may be added in the future.

Implementations§

Source §

impl<H: HashAlgorithm> ArtifactId<H>

Source

pub fn builder<P: HashProvider<H>>(provider: P) -> ArtifactIdBuilder<H, P>

Get a builder based on the chosen hash provider.

Source

pub fn try_from_url(url: Url) -> Result<ArtifactId<H>, ArtifactIdError>

Construct an ArtifactId from a gitoid-scheme Url.

This validates that the provided URL has a hashing scheme which matches the one selected for your ArtifactId (today, only sha256 is supported), and has the blob object type. It also validates that the provided hash is a valid hash for the specified hashing scheme. If any of these checks fail, the function returns an ArtifactIdError.

Note that this expects a gitoid-scheme URL, as defined by IANA. This method does not expect an HTTP or HTTPS URL to access, retrieve contents, and hash those contents to produce an identifier.

§Example

let url = Url::parse("gitoid:blob:sha256:fee53a18d32820613c0527aa79be5cb30173c823a9b448fa4817767cc84c6f03").unwrap();
let id: ArtifactId<Sha256> = ArtifactId::try_from_url(url).unwrap();
println!("Artifact ID: {}", id);

Source

pub fn try_from_safe_name(s: &str) -> Result<ArtifactId<H>, ArtifactIdError>

Try to construct an ArtifactId from a filesystem-safe representation.

Source

pub fn url(&self) -> Url

Get the Url representation of the ArtifactId.

This returns a gitoid-scheme URL for the ArtifactId.

§Example

let id: ArtifactId<Sha256> = ArtifactIdBuilder::with_rustcrypto().identify_string("hello, world");
println!("Artifact ID URL: {}", id.url());

Source

pub fn as_file_name(&self) -> PathBuf

Get a filesystem-safe representation of the ArtifactId.

This is a conservative method that tries to use only characters which can be expected to work broadly cross-platform.

What that means for us is that the : separator character is replaced with _.

Source

pub fn as_bytes(&self) -> &[u8] ⓘ

Get the underlying bytes of the ArtifactId hash.

This slice is the raw underlying buffer of the ArtifactId, exactly as produced by the hasher.

§Example

let id: ArtifactId<Sha256> = ArtifactIdBuilder::with_rustcrypto().identify_string("hello, world");
println!("Artifact ID bytes: {:?}", id.as_bytes());

Source

pub fn as_hex(&self) -> String

Get the bytes of the ArtifactId hash as a hexadecimal string.

This returns a String rather than str because the string must be constructed on the fly, as we do not store a hexadecimal representation of the hash data.

§Example

let id: ArtifactId<Sha256> = ArtifactIdBuilder::with_rustcrypto().identify_string("hello, world");
println!("Artifact ID bytes as hex: {}", id.as_hex());

Source

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

Get the name of the hash algorithm used in the ArtifactId as a string.

For Sha256, this is the string "sha256".

§Example

let id: ArtifactId<Sha256> = ArtifactIdBuilder::with_rustcrypto().identify_string("hello, world");
println!("Artifact ID hash algorithm: {}", id.hash_algorithm());

Source

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

Get the object type used in the ArtifactId as a string.

For all ArtifactIds this is "blob", but the method is provided for completeness nonetheless.

§Example

let id: ArtifactId<Sha256> = ArtifactIdBuilder::with_rustcrypto().identify_string("hello, world");
println!("Artifact ID object type: {}", id.object_type());

Source

pub fn hash_len(&self) -> usize

Get the length in bytes of the hash used in the ArtifactId.

In the future this method will be const, but is not able to be today due to limitations in the Rust cryptography crates we use internally.

§Example

let id: ArtifactId<Sha256> = ArtifactIdBuilder::with_rustcrypto().identify_string("hello, world");
println!("Artifact ID hash length in bytes: {}", id.hash_len());