vers-like-specifier

A Rust library for parsing and validating VERS-like Specifiers (vls) as defined in CSAF 2.0 and CSAF 2.1.

VERS-like specifier is the <constraints> portion of a VERS URL without the vers:<type>/ prefix.

It represents a |-separated list of constraints each consisting of an implicit or explicit comparator and a version string.

Due to the undefined / unknown VERS type, it is nearly impossible for tools to reliably determine whether a given version is in the range or not. vls is a fallback option and SHOULD NOT be used unless really necessary.

Minimum Supported Rust Version (MSRV)

1.88.0

Installation

Add vers-like-specifier to your Cargo.toml. The package is published on https://crates.io/crates/vers-like-specifier:

[dependencies]
vers-like-specifier = "0.1"

Usage

use vers_like_specifier::{Vls, Comparator, Containment};

let vls: Vls = ">=1.0.0|<2.0.0".parse().unwrap();
assert_eq!(vls.constraints().len(), 2);
assert_eq!(vls.to_string(), ">=1.0.0|<2.0.0");


let constraints = vls.constraints();
assert_eq!(constraints[0].comparator(), &Comparator::GreaterThanOrEqual);
assert_eq!(constraints[0].version().to_string(), "1.0.0");
assert_eq!(constraints[1].comparator(), &Comparator::LessThan);
assert_eq!(constraints[1].version().to_string(), "2.0.0");

// Because the VERS type is unknown, `contains` can only resolve a definite
// answer when a version exactly matches a constraint; otherwise it is `Undetermined`.
assert_eq!(vls.contains("1.0.0"), Containment::Contained);
assert_eq!(vls.contains("2.0.0"), Containment::NotContained);
assert_eq!(vls.contains("1.5.0"), Containment::Undetermined);

// The one exception: a vls containing only exact-match comparators (equal, not equal) is always decidable, since
// containment then reduces to a plain string comparison if there is a constraint with that version. If there isn't a
// constraint with the version, it is not contained by default. 
let exact_only: Vls = "1.0.0|!=2.0.0".parse().unwrap();
assert_eq!(exact_only.contains("1.0.0"), Containment::Contained);
assert_eq!(exact_only.contains("2.0.0"), Containment::NotContained);
assert_eq!(exact_only.contains("3.0.0"), Containment::NotContained);

JavaScript / WASM Usage

import init, { Vls, Constraint, Comparator, Containment } from "@csaf-rs/vers-like-specifier";

await init();

const vls = Vls.parse(">=1.0.0|<2.0.0");
const constraint = new Constraint(Comparator.GreaterThanOrEqual, "1.0.0");
console.log(constraint.version); // "1.0.0"

console.log(vls.contains("1.0.0") === Containment.Contained); // true (matches the >= constraint exactly)
console.log(vls.contains("2.0.0") === Containment.NotContained); // true (2.0.0 < 2.0.0 is always false)
console.log(vls.contains("1.5.0") === Containment.Undetermined); // true (can't be resolved; VERS type is unknown)

try {
  Vls.parse("*");
} catch (e) {
  console.error(e); // Error: '*' (VERS syntax for matching all versions) is not allowed as a vls string
}

License

Licensed under the Apache License, Version 2.0.