use super::{
DiscoveryCredentials, DiscoveryLimits, DiscoveryManifest, ItemId, MAX_METADATA_BYTES,
MAX_MODULE_PACKAGE_BYTES, ModuleFetchArgs, RefSet, ResolvedOntologyModule, RetryPolicy,
Sha256Digest, Transport, Url, acquire_staging, digest_pin, download_and_resolve_module,
endpoint, ensure_output_available, fetch_document, normalized_id, parse_input_at,
protocol_error, release_staging, validation,
};
use graphforge_discovery::{
ITEM_DESCRIPTOR_MEDIA_TYPE, ITEM_RESOLUTION_ERROR_MAX_BYTES, ItemDescriptor, ItemKind,
has_item_id_shape, parse_item_resolution_refusal,
};
use std::io::Read;
pub(super) struct ItemReference {
pub(super) id: ItemId,
pub(super) version: Option<String>,
}
pub(super) fn parse_reference(
value: &str,
) -> Result<Option<ItemReference>, graphforge_api::GfError> {
if let Ok(id) = ItemId::parse_reference(value) {
return Ok(Some(ItemReference { id, version: None }));
}
if value.contains("://") {
let url = Url::parse(value).map_err(|_| invalid("invalid item or repository URL"))?;
let first = url
.path()
.trim_start_matches('/')
.split('/')
.next()
.unwrap_or_default();
if has_item_id_shape(&first.to_ascii_lowercase()) {
return Err(invalid("item URLs must be canonical GraphForge item URIs"));
}
return Ok(None);
}
let (first, version) = value
.split_once('/')
.map_or((value, None), |(id, version)| (id, Some(version)));
if !has_item_id_shape(&first.to_ascii_lowercase()) {
return Ok(None);
}
let id = ItemId::parse(first).map_err(|_| invalid("unknown or malformed permanent item ID"))?;
if version.is_some_and(str::is_empty) {
return Err(invalid("authored version must not be empty"));
}
Ok(Some(ItemReference {
id,
version: version.map(str::to_owned),
}))
}
fn invalid(message: &str) -> graphforge_api::GfError {
validation("hub.invalid_identity", message)
}
fn mismatch(message: &str) -> graphforge_api::GfError {
validation("hub.integrity_failure", message)
}
struct DescriptorTransport<'a>(&'a dyn Transport);
impl DescriptorTransport<'_> {
fn request(
&self,
url: &Url,
headers: &[(&str, ureq::http::HeaderValue)],
limit: u64,
) -> Result<super::super::HttpResponse, graphforge_api::GfError> {
let mut headers = headers.to_vec();
headers.push((
"accept",
ureq::http::HeaderValue::from_static(ITEM_DESCRIPTOR_MEDIA_TYPE),
));
let mut response = self.0.get_discovery(url, &headers, limit)?;
if response.status == 409 {
let mut bytes = Vec::new();
response
.body
.by_ref()
.take((ITEM_RESOLUTION_ERROR_MAX_BYTES + 1) as u64)
.read_to_end(&mut bytes)
.map_err(|_| {
validation(
"hub.malformed_response",
"item resolution refusal is unreadable",
)
})?;
let error = parse_item_resolution_refusal(409, &bytes).unwrap_or_else(|error| error);
return Err(protocol_error(&error));
}
Ok(response)
}
}
impl Transport for DescriptorTransport<'_> {
fn validate(&self, url: &Url) -> Result<(), graphforge_api::GfError> {
self.0.validate(url)
}
fn get(
&self,
url: &Url,
_range: Option<u64>,
_if_range: Option<&str>,
limit: u64,
) -> Result<super::super::HttpResponse, graphforge_api::GfError> {
self.request(url, &[], limit)
}
fn get_discovery(
&self,
url: &Url,
headers: &[(&str, ureq::http::HeaderValue)],
limit: u64,
) -> Result<super::super::HttpResponse, graphforge_api::GfError> {
self.request(url, headers, limit)
}
}
struct SnapshotTransport<'a> {
inner: &'a dyn Transport,
expected: Url,
}
impl Transport for SnapshotTransport<'_> {
fn validate(&self, url: &Url) -> Result<(), graphforge_api::GfError> {
if url != &self.expected {
return Err(mismatch("retained discovery endpoint changed"));
}
let mut public = url.clone();
public.set_query(None);
self.inner.validate(&public)
}
fn get(
&self,
url: &Url,
range: Option<u64>,
if_range: Option<&str>,
limit: u64,
) -> Result<super::super::HttpResponse, graphforge_api::GfError> {
self.inner.get(url, range, if_range, limit)
}
fn get_discovery(
&self,
url: &Url,
headers: &[(&str, ureq::http::HeaderValue)],
limit: u64,
) -> Result<super::super::HttpResponse, graphforge_api::GfError> {
self.inner.get_discovery(url, headers, limit)
}
}
fn snapshot_document(
transport: &dyn Transport,
base: &Url,
name: &str,
selector: &str,
digest: &Sha256Digest,
credentials: Option<&DiscoveryCredentials>,
retry: &RetryPolicy,
) -> Result<Vec<u8>, graphforge_api::GfError> {
let mut url = endpoint(base, name);
url.query_pairs_mut().append_pair(selector, &digest.0);
let scoped = SnapshotTransport {
inner: transport,
expected: url.clone(),
};
fetch_document(&scoped, &url, credentials, retry)
}
pub(super) fn item_url(
hub: &Url,
id: &ItemId,
version: Option<&str>,
) -> Result<Url, graphforge_api::GfError> {
let mut url = hub.clone();
url.path_segments_mut()
.map_err(|()| invalid("invalid Hub URL"))?
.pop_if_empty()
.push(id.as_str());
if let Some(version) = version {
let prefix = format!("{}/", url.path());
url.path_segments_mut()
.map_err(|()| invalid("invalid Hub URL"))?
.push(version);
if !url.path().starts_with(&prefix) {
return Err(invalid(
"authored version cannot be represented as an item URL segment",
));
}
}
Ok(url)
}
fn validate_descriptor_selection(
descriptor: &ItemDescriptor,
reference: &ItemReference,
version: Option<&str>,
pin: Option<&Sha256Digest>,
) -> Result<(), graphforge_api::GfError> {
if descriptor.id != reference.id.as_str() || descriptor.kind != ItemKind::OntologyModule {
return Err(mismatch("descriptor names a different item"));
}
if version.is_some_and(|version| descriptor.module.version != version) {
return Err(mismatch("descriptor names a different authored version"));
}
if pin.is_some_and(|pin| pin != &descriptor.module.content_digest) {
return Err(mismatch("descriptor disagrees with --digest pin"));
}
Ok(())
}
pub(super) fn fetch(
transport: &dyn Transport,
args: &ModuleFetchArgs,
reference: &ItemReference,
retry: &RetryPolicy,
credential_lookup: impl Fn(&str) -> Result<String, std::env::VarError>,
) -> Result<
(
ResolvedOntologyModule,
Option<graphforge_discovery::RepositoryMoved>,
),
graphforge_api::GfError,
> {
if reference.id.kind() != ItemKind::OntologyModule {
return Err(invalid(
"ontology module fetch does not fetch bridge packages",
));
}
if args
.ontology_id
.as_deref()
.is_some_and(|id| normalized_id(id) != reference.id.to_uri())
{
return Err(invalid("--ontology-id disagrees with the item reference"));
}
let version = match (reference.version.as_deref(), args.version.as_deref()) {
(Some(from_ref), Some(from_flag)) if from_ref != from_flag => {
return Err(invalid("--version disagrees with the item reference"));
}
(from_ref, from_flag) => from_ref.or(from_flag),
};
if version.is_some_and(|version| {
version.is_empty() || version.len() > DiscoveryLimits::default().max_string_bytes
}) {
return Err(invalid(
"authored version is empty or exceeds its byte bound",
));
}
let pin = digest_pin(args)?;
let hub = crate::hub_http::hub_base(args.hub.as_deref())?;
ensure_output_available(&args.output)?;
let url = item_url(&hub, &reference.id, version)?;
let credentials = DiscoveryCredentials::load(
&hub,
None,
args.protection_bypass_env.as_deref(),
credential_lookup,
)?;
let limits = DiscoveryLimits {
max_response_bytes: MAX_METADATA_BYTES,
max_module_package_bytes: MAX_MODULE_PACKAGE_BYTES,
..DiscoveryLimits::default()
};
let descriptor_transport = DescriptorTransport(transport);
let bytes = fetch_document(&descriptor_transport, &url, credentials.as_ref(), retry)?;
let descriptor =
ItemDescriptor::from_json(&bytes, limits).map_err(|error| protocol_error(&error))?;
validate_descriptor_selection(&descriptor, reference, version, pin.as_ref())?;
transport.item_descriptor_verified(&url, &descriptor)?;
let (_, base) = parse_input_at(&descriptor.repository.canonical_name(), Some(hub.as_str()))?;
let refs_bytes = snapshot_document(
transport,
&base,
"refs",
"revision",
&descriptor.discovery.refs_revision,
credentials.as_ref(),
retry,
)?;
let manifest_bytes = snapshot_document(
transport,
&base,
"manifest",
"validator",
&descriptor.discovery.manifest_validator,
credentials.as_ref(),
retry,
)?;
let refs = RefSet::from_json(&refs_bytes, limits).map_err(|error| protocol_error(&error))?;
let manifest = DiscoveryManifest::from_json(&manifest_bytes, limits)
.map_err(|error| protocol_error(&error))?;
descriptor
.bind_snapshot(&refs, &manifest)
.map_err(|error| protocol_error(&error))?;
let (_, _, object) = manifest
.ontology_module_selection(&descriptor.module)
.map_err(|error| protocol_error(&error))?;
let staging = acquire_staging(&args.output)?;
let result = download_and_resolve_module(
transport,
&descriptor.repository,
&descriptor.module,
&manifest_bytes,
&refs_bytes,
object,
limits,
&staging,
retry,
)
.and_then(|resolved| {
if descriptor.version_order != resolved.version_order() {
return Err(mismatch(
"descriptor version order disagrees with verified module",
));
}
Ok(resolved)
});
release_staging(staging);
result.map(|resolved| (resolved, None))
}