Files
crank/apps/admin-api/src/service/imports/verified_preview.rs
T
bsodfather 1b6db09bd1
CI / Rust Checks (push) Successful in 25m54s
CI / UI Checks (push) Successful in 5s
CI / Community Image Smoke (push) Successful in 1m47s
CI / Frontend E2E (push) Successful in 10m12s
CI / Deploy (push) Successful in 1m22s
fix(import): единая идентичность внешних URI (#96)
Единая transport-canonical идентичность внешних документов; normalizer v6 с immutable historical replay; matrix 1.0.4 / corpus 1.0.5. PR CI run840 success, локальная приёмка и independent review выполнены.

Co-authored-by: bsodfather <bsodfather@gmail.com>
2026-10-11 06:19:16 +00:00

406 lines
17 KiB
Rust

use super::*;
/// Revalidates the verified source/dependency snapshots and the persisted
/// replay contract of a stored job without mutating the job. Both the
/// legacy Apply and the ImportPlan creation derive from this result, so
/// the legacy failure-text code travels with the outcome.
impl AdminService {
pub(super) async fn resolve_verified_openapi_preview(
&self,
workspace_id: &WorkspaceId,
job: &ImportJob,
locale: OpenApiUploadLocale,
) -> Result<ResolvedOpenApiPreview, ImportPreviewResolution> {
let source = match import_job_source(&job.preview_payload, locale) {
Ok(source) => source,
Err(error) => {
return Err(ImportPreviewResolution::Fatal(
"import_source_verification_failed",
error,
));
}
};
let verified = match self
.registry
.read_artifact_source(
std::sync::Arc::clone(&self.artifact_store),
workspace_id,
&source.source_id,
)
.await
{
Ok(verified) => verified,
Err(
error @ (RegistryError::SourceNotFound { .. } | RegistryError::SourceUnavailable),
) => {
return Err(ImportPreviewResolution::Fatal(
"import_source_verification_failed",
openapi_source_error(locale, error),
));
}
Err(error @ RegistryError::SourceIntegrity) => {
return Err(ImportPreviewResolution::Fatal(
"import_source_verification_failed",
openapi_source_error(locale, error),
));
}
Err(error) => {
return Err(ImportPreviewResolution::NonFatal(openapi_source_error(
locale, error,
)));
}
};
if verified.source.blob.artifact_ref != source.digest {
return Err(ImportPreviewResolution::Fatal(
"import_source_verification_failed",
ApiError::openapi_upload(locale, "source_integrity"),
));
}
let replay_contract = match import_replay_contract(&job.preview_payload, locale) {
Ok(contract) => contract,
Err(error) => {
return Err(ImportPreviewResolution::Fatal(
"import_replay_verification_failed",
error,
));
}
};
let (preview, normalizer_version, projection_version, ir_fingerprint) =
match replay_contract {
ImportReplayContract::PersistedV2(replay) => (
replay.preview.preview,
replay.normalizer_version,
replay.projection_version,
replay.preview.ir_fingerprint,
),
ImportReplayContract::LegacyV1 | ImportReplayContract::Current => {
let legacy_v1 = matches!(replay_contract, ImportReplayContract::LegacyV1);
let dependency_snapshots = self
.read_import_job_dependencies(workspace_id, &job.preview_payload, locale)
.await
.map_err(|error| {
ImportPreviewResolution::Fatal(
"import_dependency_verification_failed",
error,
)
})?;
let normalization_config = import_job_normalization_config(
&job.preview_payload,
&self.external_reference_normalization,
legacy_v1,
locale,
)
.map_err(|error| {
ImportPreviewResolution::Fatal("import_replay_verification_failed", error)
})?;
let parsed = parse_verified_preview(
verified.bytes,
source.digest.digest_hex().to_owned(),
dependency_snapshots,
normalization_config,
locale,
legacy_v1,
)
.await
.map_err(|error| {
ImportPreviewResolution::Fatal("import_replay_verification_failed", error)
})?;
if let Err(error) =
verify_preview_contract(&job.preview_payload, &parsed, locale)
{
return Err(ImportPreviewResolution::Fatal(
"import_replay_verification_failed",
error,
));
}
if legacy_v1 {
(parsed.preview, String::new(), String::new(), String::new())
} else {
(
parsed.preview,
NORMALIZER_VERSION.to_owned(),
PROJECTION_VERSION.to_owned(),
parsed.ir_fingerprint,
)
}
}
};
Ok(ResolvedOpenApiPreview {
source,
preview,
fingerprint: json!({
"normalizer_version": if normalizer_version.is_empty() { Value::Null } else { Value::String(normalizer_version) },
"projection_version": if projection_version.is_empty() { Value::Null } else { Value::String(projection_version) },
"ir_fingerprint": if ir_fingerprint.is_empty() { Value::Null } else { Value::String(ir_fingerprint) },
"preview_digest": job.preview_payload.get("preview_digest").and_then(Value::as_str).map(|digest| Value::String(digest.to_owned())).unwrap_or(Value::Null),
}),
})
}
}
pub(super) struct ParsedOpenApiPreview {
pub(super) preview: crank_import::rest::ImportPreview,
pub(super) ir_fingerprint: String,
}
/// Verified job preview material shared by the legacy Apply path and the
/// ImportPlan creation: the replay contract has held, no job mutation
/// happened.
pub(super) struct ResolvedOpenApiPreview {
pub(super) source: ImportJobSourceEnvelope,
pub(super) preview: crank_import::rest::ImportPreview,
pub(super) fingerprint: Value,
}
/// Outcome of a failed preview revalidation. `Fatal` codes are the same
/// stable failure texts the legacy path records on a failed job; the plan
/// path must surface the same material as a bounded re-preview conflict
/// without touching the job, because other stored plans may anchor to it.
pub(super) enum ImportPreviewResolution {
Fatal(&'static str, ApiError),
NonFatal(ApiError),
}
struct PersistedOpenApiReplay {
preview: ParsedOpenApiPreview,
normalizer_version: String,
projection_version: String,
}
enum ImportReplayContract {
LegacyV1,
PersistedV2(Box<PersistedOpenApiReplay>),
Current,
}
fn import_replay_contract(
payload: &serde_json::Value,
locale: OpenApiUploadLocale,
) -> Result<ImportReplayContract, ApiError> {
let Some(normalization) = payload.get("normalization") else {
return Ok(ImportReplayContract::LegacyV1);
};
let normalizer = normalization
.get("normalizer_version")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| ApiError::openapi_upload(locale, "source_integrity"))?;
let projection = normalization
.get("projection_version")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| ApiError::openapi_upload(locale, "source_integrity"))?;
let ir_fingerprint = normalization
.get("ir_fingerprint")
.and_then(serde_json::Value::as_str)
.filter(|value| is_lower_sha256(value))
.ok_or_else(|| ApiError::openapi_upload(locale, "source_integrity"))?;
let expected_preview_digest = payload
.get("preview_digest")
.and_then(serde_json::Value::as_str)
.filter(|value| is_lower_sha256(value))
.ok_or_else(|| ApiError::openapi_upload(locale, "source_integrity"))?;
if normalizer == NORMALIZER_VERSION && projection == PROJECTION_VERSION {
return Ok(ImportReplayContract::Current);
}
// Historical preview payloads are replayed as their persisted projection.
// They must never be parsed again with current normalization semantics.
if !matches!(
(normalizer, projection),
("normalized-ir-v2", "preview-v2")
| ("normalized-ir-v3", "preview-v3")
| ("normalized-ir-v4", "preview-v4")
| ("normalized-ir-v5", "preview-v5")
// The v5/preview-v6 pair predates the shared external-URI identity
// (normalized-ir-v6). Its saved projection is authoritative and is
// replayed verbatim, never reparsed under the current normalizer.
| ("normalized-ir-v5", "preview-v6")
) {
return Err(ApiError::openapi_upload(locale, "source_integrity"));
}
let preview_value = payload
.get("preview")
.cloned()
.ok_or_else(|| ApiError::openapi_upload(locale, "source_integrity"))?;
if preview_digest(&preview_value)? != expected_preview_digest {
return Err(ApiError::openapi_upload(locale, "source_integrity"));
}
let preview = serde_json::from_value(preview_value)
.map_err(|_| ApiError::openapi_upload(locale, "source_integrity"))?;
Ok(ImportReplayContract::PersistedV2(Box::new(
PersistedOpenApiReplay {
preview: ParsedOpenApiPreview {
preview,
ir_fingerprint: ir_fingerprint.to_owned(),
},
normalizer_version: normalizer.to_owned(),
projection_version: projection.to_owned(),
},
)))
}
fn is_lower_sha256(value: &str) -> bool {
value.len() == 64
&& value
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}
pub(super) async fn parse_verified_preview(
bytes: Vec<u8>,
digest: String,
snapshots: Vec<crank_import::rest::ExternalDocumentSnapshot>,
normalization_config: crank_import::rest::NormalizationConfig,
locale: OpenApiUploadLocale,
legacy_v1: bool,
) -> Result<ParsedOpenApiPreview, ApiError> {
let started = tokio::time::Instant::now();
let permit = tokio::time::timeout(OPENAPI_PARSE_DEADLINE, OPENAPI_PARSE_SLOTS.acquire())
.await
.map_err(|_| ApiError::openapi_upload(locale, "parser_unavailable"))?
.map_err(|_| ApiError::openapi_upload(locale, "parser_unavailable"))?;
let parsing = tokio::task::spawn_blocking(move || {
// Keep the permit inside the blocking task. Timing out the caller
// cannot cancel CPU work already running, but abandoned parsers remain
// globally bounded and release capacity when they actually finish.
let _permit = permit;
let document = std::str::from_utf8(&bytes)
.map_err(|_| ApiError::openapi_upload(locale, "invalid_utf8"))?;
if legacy_v1 {
return crank_import::rest::preview_document_legacy_v1(document)
.map(|preview| ParsedOpenApiPreview {
preview,
ir_fingerprint: String::new(),
})
.map_err(|_| ApiError::openapi_upload(locale, "invalid_document"));
}
let digest = crank_import::rest::SourceDigest::parse(digest)
.map_err(|_| ApiError::openapi_upload(locale, "source_integrity"))?;
let ir = crank_import::rest::normalize_verified_bundle(
document,
digest,
&snapshots,
&normalization_config,
)
.map_err(|error| match error {
crank_import::rest::ImportParseError::NoMethods => {
ApiError::openapi_upload(locale, "no_methods")
}
_ => ApiError::openapi_upload(locale, "invalid_document"),
})?;
let ir_fingerprint = preview_digest(
&serde_json::to_value(&ir)
.map_err(|_| ApiError::openapi_upload(locale, "invalid_document"))?,
)?;
Ok::<_, ApiError>(ParsedOpenApiPreview {
preview: crank_import::rest::preview_from_ir(&ir),
ir_fingerprint,
})
});
let remaining = OPENAPI_PARSE_DEADLINE
.checked_sub(started.elapsed())
.unwrap_or(std::time::Duration::ZERO);
tokio::time::timeout(remaining, parsing)
.await
.map_err(|_| ApiError::openapi_upload(locale, "parser_unavailable"))?
.map_err(|_| ApiError::openapi_upload(locale, "parser_unavailable"))?
}
pub(super) fn artifact_error(locale: OpenApiUploadLocale, error: ArtifactError) -> ApiError {
match error {
ArtifactError::EmptySource => ApiError::openapi_upload(locale, "empty_file"),
ArtifactError::SourceTooLarge => ApiError::openapi_upload(locale, "file_too_large"),
ArtifactError::Integrity => ApiError::openapi_upload(locale, "source_integrity"),
ArtifactError::Storage
| ArtifactError::NotFound
| ArtifactError::InvalidReference
| ArtifactError::UnsafeRoot => ApiError::openapi_upload(locale, "storage_unavailable"),
}
}
pub(super) fn openapi_source_error(locale: OpenApiUploadLocale, error: RegistryError) -> ApiError {
match error {
RegistryError::SourceNotFound { .. } | RegistryError::SourceUnavailable => {
ApiError::openapi_upload(locale, "source_unavailable")
}
RegistryError::SourceIntegrity => ApiError::openapi_upload(locale, "source_integrity"),
other => ApiError::from(other),
}
}
pub(super) fn preview_digest(preview: &serde_json::Value) -> Result<String, ApiError> {
let canonical =
serde_json::to_vec(preview).map_err(|error| ApiError::internal(error.to_string()))?;
Ok(format!("{:x}", Sha256::digest(canonical)))
}
fn verify_preview_contract(
payload: &serde_json::Value,
parsed: &ParsedOpenApiPreview,
locale: OpenApiUploadLocale,
) -> Result<(), ApiError> {
// Pre-fingerprint jobs are legacy rolling-upgrade records. They retain the
// old reparse behavior; new jobs fail closed if parser output drifts or a
// persisted preview has been changed.
let expected = payload
.get("preview_digest")
.and_then(serde_json::Value::as_str);
if payload.get("normalization").is_some() && expected.is_none() {
return Err(ApiError::openapi_upload(locale, "source_integrity"));
}
let Some(expected) = expected else {
return Ok(());
};
let actual = preview_digest(
&serde_json::to_value(&parsed.preview)
.map_err(|error| ApiError::internal(error.to_string()))?,
)?;
if actual == expected {
if let Some(normalization) = payload.get("normalization") {
let normalizer = normalization
.get("normalizer_version")
.and_then(serde_json::Value::as_str);
let projection = normalization
.get("projection_version")
.and_then(serde_json::Value::as_str);
let fingerprint = normalization
.get("ir_fingerprint")
.and_then(serde_json::Value::as_str);
if normalizer != Some(NORMALIZER_VERSION)
|| projection != Some(PROJECTION_VERSION)
|| fingerprint != Some(parsed.ir_fingerprint.as_str())
{
return Err(ApiError::openapi_upload(locale, "source_integrity"));
}
}
Ok(())
} else {
Err(ApiError::openapi_upload(locale, "source_integrity"))
}
}
pub(super) fn preview_has_blocker(
preview: &crank_import::rest::ImportPreview,
selected_operation_keys: &BTreeSet<String>,
) -> bool {
preview
.findings
.iter()
.any(|finding| finding.severity == ImportFindingSeverity::Error)
|| preview
.groups
.iter()
.flat_map(|group| group.operations.iter())
.filter(|operation| selected_operation_keys.contains(&operation.key))
.any(|operation| {
operation
.findings
.iter()
.any(|finding| finding.severity == ImportFindingSeverity::Error)
|| (!operation.security_requirements.alternatives.is_empty()
&& !operation.security_requirements.alternatives.iter().any(
|alternative| alternative.supported && alternative.schemes.is_empty(),
))
})
}