feat(import): complete OpenAPI onboarding and verify delivery
CI / Rust Checks (pull_request) Failing after 1s
CI / UI Checks (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Deploy (pull_request) Skipped

This commit is contained in:
bsodfather committed 2026-10-09 17:50:38 +03:00
1 parent bb3e376767
commit e93de7015a
244 files changed
+57020 -5139

No files matched your search

+28 -2
View File
@@ -27,12 +27,18 @@ use crate::{
},
auth_profiles::{create_auth_profile, get_auth_profile, list_auth_profiles},
capabilities::get_capabilities,
imports::{create_openapi_import, preview_openapi_import},
imports::{
apply_openapi_import_plan, create_openapi_import, create_openapi_import_plan,
preview_openapi_import, revalidate_openapi_import_plan,
},
observability::{
approve_approval, deny_approval, export_logs_csv, export_usage_csv, get_agent_usage,
get_approval, get_log, get_operation_usage, get_usage, list_approvals, list_logs,
},
onboarding::{get_onboarding, record_onboarding_event, reset_onboarding_selection},
onboarding::{
get_onboarding, record_onboarding_event, register_onboarding_import_context,
reset_onboarding_selection, select_onboarding_import_draft,
},
operations::{
analyze_operation_quality, archive_operation, create_operation, create_version,
delete_operation, export_operation, generate_draft, get_operation,
@@ -58,6 +64,18 @@ pub fn build_app(state: AppState) -> Router {
"/imports/openapi/{job_id}/create",
post(create_openapi_import),
)
.route(
"/imports/openapi/{job_id}/plans",
post(create_openapi_import_plan).layer(DefaultBodyLimit::max(16 * 1024 * 1024)),
)
.route(
"/imports/openapi/plans/{plan_id}",
get(revalidate_openapi_import_plan),
)
.route(
"/imports/openapi/{plan_id}/apply",
post(apply_openapi_import_plan).layer(DefaultBodyLimit::max(16 * 1024)),
)
.route(
"/operations/analyze-quality",
post(analyze_operation_quality),
@@ -158,6 +176,14 @@ pub fn build_app(state: AppState) -> Router {
.route(
"/onboarding/reset-selection",
post(reset_onboarding_selection),
)
.route(
"/onboarding/import-context",
post(register_onboarding_import_context).layer(DefaultBodyLimit::max(16 * 1024)),
)
.route(
"/onboarding/select-draft",
post(select_onboarding_import_draft).layer(DefaultBodyLimit::max(16 * 1024)),
);
let workspace_root_router = Router::new()
+13
View File
@@ -186,6 +186,19 @@ async fn run() -> Result<ExitCode, CliError> {
})
.collect::<Vec<_>>();
let plan = json!({ "schema_version": 1, "sequence": sequence });
if option == Some("--target-version") {
let target_version = plan["sequence"]
.as_array()
.and_then(|sequence| sequence.last())
.and_then(|migration| migration["version"].as_i64())
.ok_or(CliError::new(
"migration_sequence_invalid",
"plan.target_version",
"contact_operator",
))?;
println!("{target_version}");
return Ok(ExitCode::SUCCESS);
}
if option == Some("--check") {
let bytes = std::fs::read("docs/schemas/migration-sequence.json")
.map_err(|_| CliError::new("contract_drift", "plan.read", "contact_operator"))?;
+151 -21
View File
@@ -353,6 +353,35 @@ pub struct OnboardingResponse {
pub platform_api_key_id: Option<String>,
pub mcp_endpoint: Option<String>,
pub first_call: Option<OnboardingFirstCallEvidence>,
pub import_context: Option<OnboardingImportContextView>,
}
#[derive(Clone, Debug, Serialize)]
pub struct OnboardingImportChoiceView {
pub key: String,
pub name: String,
pub outcome: String,
pub operation_id: Option<String>,
pub version: Option<u32>,
pub reason: Option<String>,
pub selectable: bool,
}
#[derive(Clone, Debug, Serialize)]
pub struct OnboardingImportDriftView {
pub reason: String,
pub current_operation_version: Option<u32>,
}
#[derive(Clone, Debug, Serialize)]
pub struct OnboardingImportContextView {
pub application_idempotency_key: String,
pub plan_digest: String,
pub report: Value,
pub choices: Vec<OnboardingImportChoiceView>,
pub selected_operation_id: Option<String>,
pub selected_operation_version: Option<u32>,
pub drift: Option<OnboardingImportDriftView>,
}
#[derive(Clone, Debug, Serialize)]
@@ -375,6 +404,38 @@ pub struct ResetOnboardingSelectionResponse {
pub onboarding: OnboardingResponse,
}
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RegisterOnboardingImportContextPayload {
pub application_idempotency_key: String,
pub plan_digest: String,
pub expected_revision: i64,
}
#[derive(Clone, Debug, Serialize)]
pub struct RegisterOnboardingImportContextResponse {
pub registered: bool,
#[serde(flatten)]
pub onboarding: OnboardingResponse,
}
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SelectOnboardingImportDraftPayload {
pub application_idempotency_key: String,
pub plan_digest: String,
pub operation_id: String,
pub operation_version: u32,
pub expected_revision: i64,
}
#[derive(Clone, Debug, Serialize)]
pub struct SelectOnboardingImportDraftResponse {
pub selected: bool,
#[serde(flatten)]
pub onboarding: OnboardingResponse,
}
#[derive(Clone, Debug, Serialize)]
pub struct WorkspaceCatalogSnapshotResponse {
pub kind: String,
@@ -542,48 +603,34 @@ pub struct OpenApiImportPreviewResponse {
pub job_id: String,
pub expires_at: String,
pub preview: crank_import::rest::ImportPreview,
/// Compatible Auth Profiles visible to the current workspace, grouped by
/// operation and security alternative. Profile credentials are never
/// included.
pub auth_profile_choices: Vec<OpenApiAuthProfileChoice>,
#[serde(default)]
pub security_profile_choices: Vec<OpenApiImportSecurityProfileChoice>,
}
#[derive(Clone, Debug, Serialize)]
pub struct OpenApiAuthProfileChoice {
pub struct OpenApiImportSecurityProfileChoice {
pub operation_key: String,
pub alternative_index: usize,
pub scheme_names: Vec<String>,
pub supported: bool,
pub profiles: Vec<OpenApiAuthProfileOption>,
pub schemes: Vec<String>,
pub profiles: Vec<OpenApiImportAuthProfileChoice>,
}
#[derive(Clone, Debug, Serialize)]
pub struct OpenApiAuthProfileOption {
pub struct OpenApiImportAuthProfileChoice {
pub id: String,
pub name: String,
pub kind: AuthKind,
pub kind: crank_core::AuthKind,
}
#[derive(Clone, Debug, Deserialize)]
pub struct OpenApiImportCreatePayload {
pub selected_operation_keys: Vec<String>,
#[serde(default)]
pub auth_mappings: Vec<OpenApiAuthMapping>,
#[serde(default)]
pub server_url: Option<String>,
#[serde(default = "default_openapi_conflict_mode")]
pub conflict_mode: String,
}
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct OpenApiAuthMapping {
pub operation_key: String,
pub alternative_index: usize,
/// `None` is an explicit unresolved mapping. It is never actionable for a
/// required authentication alternative.
pub auth_profile_id: Option<String>,
}
#[derive(Clone, Debug, Serialize)]
pub struct OpenApiImportCreateResponse {
pub created: Vec<OpenApiImportCreatedOperation>,
@@ -606,6 +653,89 @@ pub struct OpenApiImportSkippedOperation {
pub reason: String,
}
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OpenApiImportPlanCreatePayload {
#[serde(default = "default_openapi_plan_selection_mode")]
pub selection_mode: String,
#[serde(default)]
pub selected_operation_keys: Vec<String>,
#[serde(default)]
pub server_url: Option<String>,
#[serde(default)]
pub decisions: Vec<OpenApiImportPlanDecision>,
}
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OpenApiImportPlanApplyPayload {
pub plan_digest: String,
pub idempotency_key: String,
}
fn default_openapi_plan_selection_mode() -> String {
"full".to_owned()
}
#[derive(Clone, Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct OpenApiImportPlanDecision {
pub operation_key: String,
pub action: String,
#[serde(default)]
pub target_operation_id: Option<String>,
#[serde(default)]
pub confirmed_name: Option<String>,
#[serde(default)]
pub auth_profile_id: Option<String>,
#[serde(default)]
pub security_alternative_index: Option<usize>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
pub struct OpenApiImportPlanCounts {
pub selected: usize,
pub excluded: usize,
pub actionable: usize,
pub blocked: usize,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct OpenApiImportPlanCandidateView {
pub key: String,
pub name: String,
pub state: String,
pub action: Option<String>,
pub target_operation_id: Option<String>,
pub confirmed_name: Option<String>,
pub auth_profile_id: Option<String>,
pub security_alternative_index: Option<usize>,
pub reason: Option<String>,
}
#[derive(Clone, Debug, Serialize)]
pub struct OpenApiImportPlanCreateResponse {
pub plan_reference: String,
pub plan_digest: String,
pub catalog_revision: String,
pub support_matrix_version: String,
pub expires_at: String,
pub selection_mode: String,
pub counts: OpenApiImportPlanCounts,
pub candidates: Vec<OpenApiImportPlanCandidateView>,
}
#[derive(Clone, Debug, Serialize)]
pub struct OpenApiImportPlanRevalidationResponse {
pub plan_reference: String,
pub plan_digest: String,
pub revalidation_status: String,
pub revalidation_required: bool,
pub reason: Option<String>,
pub counts: OpenApiImportPlanCounts,
pub candidates: Vec<OpenApiImportPlanCandidateView>,
}
#[derive(Clone, Debug, Serialize)]
pub struct CreatedOperationResponse {
pub operation_id: String,
+111 -51
View File
@@ -135,41 +135,6 @@ impl ApiError {
"OpenAPI document is invalid or unsupported"
}
}
(_, "literal_credentials_rejected") => {
if russian {
"документ OpenAPI содержит literal credential и отклонён"
} else {
"OpenAPI document contains literal credential material and was rejected"
}
}
(_, "auth_mapping_required") => {
if russian {
"для требования аутентификации выберите доступный профиль"
} else {
"an available Auth Profile mapping is required for this authentication requirement"
}
}
(_, "auth_mapping_unsupported") => {
if russian {
"это требование аутентификации не поддерживается импортом"
} else {
"this authentication requirement is not supported by import"
}
}
(_, "auth_mapping_invalid") => {
if russian {
"привязка аутентификации в запросе импорта некорректна"
} else {
"OpenAPI import authentication mapping is invalid"
}
}
(_, "auth_binding_unavailable") => {
if russian {
"выбранный профиль аутентификации недоступен для этого импорта"
} else {
"selected Auth Profile is unavailable for this import"
}
}
(_, "no_methods") => {
if russian {
"документ OpenAPI не содержит поддерживаемых методов"
@@ -230,18 +195,6 @@ impl ApiError {
}
}
pub(crate) fn openapi_auth_binding_unavailable(locale: OpenApiUploadLocale) -> Self {
let message = if locale == OpenApiUploadLocale::Ru {
"выбранный профиль аутентификации недоступен для этого импорта"
} else {
"selected Auth Profile is unavailable for this import"
};
Self::unprocessable_with_context(
message,
json!({ "error_code": "openapi_auth_binding_unavailable" }),
)
}
pub(crate) fn rate_limited_with_context(message: impl Into<String>, context: Value) -> Self {
Self::RateLimited {
message: message.into(),
@@ -711,6 +664,29 @@ impl From<RegistryError> for ApiError {
"onboarding domain steps are not complete",
json!({"error_code":"onboarding_incomplete"}),
),
RegistryError::OnboardingImportDraftUnavailable => Self::unprocessable_with_context(
"the requested operation is not an actionable imported Draft",
json!({
"error_code":"onboarding_import_draft_unavailable",
"recovery":"reload_import_report"
}),
),
RegistryError::OnboardingImportApplicationUnavailable => {
Self::unprocessable_with_context(
"no committed import apply report matches the requested application",
json!({
"error_code":"onboarding_import_application_unavailable",
"recovery":"reload_import_report"
}),
)
}
RegistryError::OnboardingImportContextUnavailable => Self::unprocessable_with_context(
"the workspace has no durable import context for the requested application",
json!({
"error_code":"onboarding_import_context_unavailable",
"recovery":"register_import_context"
}),
),
RegistryError::InvalidEnumRepresentation { field } => Self::validation_with_context(
format!("unsupported enum representation for field {field}"),
json!({ "field": field }),
@@ -722,10 +698,6 @@ impl From<RegistryError> for ApiError {
"value": value,
}),
),
RegistryError::ImportAuthBindingUnavailable => Self::unprocessable_with_context(
"selected Auth Profile is unavailable for this import",
json!({ "error_code": "openapi_auth_binding_unavailable" }),
),
RegistryError::YamlImportJobNotFound { job_id } => Self::validation_with_context(
format!("yaml import job {job_id} was not found"),
json!({ "job_id": job_id }),
@@ -738,6 +710,94 @@ impl From<RegistryError> for ApiError {
format!("import job {job_id} was already applied with different parameters"),
json!({ "job_id": job_id }),
),
RegistryError::InvalidImportPlan { field } => Self::validation_with_context(
format!("invalid import plan input for field {field}"),
json!({
"field": field,
"error_code": "import_plan_invalid_input"
}),
),
RegistryError::ImportPlanConflict { plan_id } => Self::conflict_with_context(
format!("import plan {plan_id} already exists with different material"),
json!({
"plan_id": plan_id,
"error_code": "import_plan_conflict",
"recovery": "repreview_required"
}),
),
RegistryError::ImportPlanJobUnavailable { job_id } => Self::not_found_with_context(
format!("import job {job_id} is unavailable for planning"),
json!({ "job_id": job_id, "error_code": "import_plan_job_unavailable" }),
),
RegistryError::ImportPlanJobTerminal { job_id }
| RegistryError::ImportPlanJobExpired { job_id } => Self::conflict_with_context(
format!("import job {job_id} is not in planning state"),
json!({
"job_id": job_id,
"error_code": "import_plan_job_terminal",
"recovery": "repreview_required",
"repreview_required": true
}),
),
RegistryError::ImportPlanNotFound { .. } => Self::not_found_with_context(
"import plan was not found in this workspace",
json!({ "error_code": "import_plan_not_found" }),
),
RegistryError::ImportPlanExpired { .. } => Self::conflict_with_context(
"import plan has expired; create a fresh preview",
json!({
"error_code": "import_plan_expired",
"recovery": "repreview_required",
"repreview_required": true
}),
),
RegistryError::ImportPlanPayloadCorrupt { .. } => Self::conflict_with_context(
"import plan is invalid; create a fresh preview",
json!({
"error_code": "import_plan_payload_invalid",
"recovery": "repreview_required",
"repreview_required": true
}),
),
RegistryError::ImportPlanFingerprintStale { .. } => Self::conflict_with_context(
"import plan no longer matches the verified preview; create a fresh preview",
json!({
"error_code": "import_plan_fingerprint_stale",
"recovery": "repreview_required",
"repreview_required": true
}),
),
RegistryError::ImportPlanKeyDigestConflict { .. } => Self::conflict_with_context(
"idempotency key was already committed for different plan material",
json!({
"error_code": "import_plan_key_digest_conflict",
"recovery": "repreview_required",
"repreview_required": true
}),
),
RegistryError::ImportPlanNameConflict { .. } => Self::conflict_with_context(
"an operation name changed after the plan was created",
json!({
"error_code": "import_plan_name_conflict",
"recovery": "confirm_skip_rename_or_new_version"
}),
),
RegistryError::ImportPlanTargetStale { .. } => Self::conflict_with_context(
"an operation changed after the plan was created; create a fresh preview",
json!({
"error_code": "import_plan_target_stale",
"recovery": "repreview_required",
"repreview_required": true
}),
),
RegistryError::ImportPlanAuthUnavailable { .. } => Self::conflict_with_context(
"an authentication profile is unavailable; create a fresh preview",
json!({
"error_code": "import_plan_auth_unavailable",
"recovery": "repreview_required",
"repreview_required": true
}),
),
RegistryError::SourceNotFound { .. } => Self::not_found_with_context(
"artifact source was not found",
json!({
+73 -1
View File
@@ -10,7 +10,10 @@ use serde_json::{Value, json};
use crate::{
error::ApiError,
service::{OpenApiImportCreatePayload, OpenApiUpload, OpenApiUploadLocale},
service::{
OpenApiImportCreatePayload, OpenApiImportPlanApplyPayload, OpenApiImportPlanCreatePayload,
OpenApiUpload, OpenApiUploadLocale,
},
state::AppState,
};
@@ -25,6 +28,12 @@ pub struct WorkspaceImportPath {
pub job_id: String,
}
#[derive(Deserialize)]
pub struct WorkspacePlanPath {
pub workspace_id: String,
pub plan_id: String,
}
pub async fn preview_openapi_import(
Path(path): Path<WorkspacePath>,
State(state): State<AppState>,
@@ -198,6 +207,69 @@ pub async fn create_openapi_import(
Ok(Json(json!(imported)))
}
pub async fn create_openapi_import_plan(
Path(path): Path<WorkspaceImportPath>,
State(state): State<AppState>,
headers: HeaderMap,
Json(payload): Json<OpenApiImportPlanCreatePayload>,
) -> Result<Json<Value>, ApiError> {
let plan = state
.service
.create_openapi_import_plan_with_locale(
&path.workspace_id.as_str().into(),
&path.job_id.as_str().into(),
payload,
openapi_upload_locale(&headers),
)
.await?;
Ok(Json(json!(plan)))
}
pub async fn revalidate_openapi_import_plan(
Path(path): Path<WorkspacePlanPath>,
State(state): State<AppState>,
headers: HeaderMap,
) -> Result<Json<Value>, ApiError> {
let plan = state
.service
.revalidate_openapi_import_plan_with_locale(
&path.workspace_id.as_str().into(),
&path.plan_id.as_str().into(),
openapi_upload_locale(&headers),
)
.await?;
Ok(Json(json!(plan)))
}
pub async fn apply_openapi_import_plan(
Path(path): Path<WorkspacePlanPath>,
State(state): State<AppState>,
headers: HeaderMap,
Json(payload): Json<OpenApiImportPlanApplyPayload>,
) -> Result<impl IntoResponse, ApiError> {
let report = state
.service
.apply_openapi_import_plan_with_locale(
&path.workspace_id.as_str().into(),
&path.plan_id.as_str().into(),
payload,
openapi_upload_locale(&headers),
)
.await?;
let status = if report.status == crank_registry::ImportPlanApplyStatus::Rejected {
axum::http::StatusCode::CONFLICT
} else {
axum::http::StatusCode::OK
};
Ok((
status,
Json(
serde_json::to_value(report)
.map_err(|_| ApiError::internal("could not serialize import plan report"))?,
),
))
}
#[cfg(test)]
mod tests {
use axum::http::{HeaderMap, HeaderValue};
+28
View File
@@ -7,7 +7,9 @@ use crate::{
error::ApiError,
service::{
OnboardingEventPayload, OnboardingEventResponse, OnboardingResponse,
RegisterOnboardingImportContextPayload, RegisterOnboardingImportContextResponse,
ResetOnboardingSelectionPayload, ResetOnboardingSelectionResponse,
SelectOnboardingImportDraftPayload, SelectOnboardingImportDraftResponse,
},
state::AppState,
};
@@ -57,3 +59,29 @@ pub async fn record_onboarding_event(
.await?,
))
}
pub async fn register_onboarding_import_context(
Path(path): Path<WorkspaceOnboardingPath>,
State(state): State<AppState>,
Json(payload): Json<RegisterOnboardingImportContextPayload>,
) -> Result<Json<RegisterOnboardingImportContextResponse>, ApiError> {
Ok(Json(
state
.service
.register_onboarding_import_context(&path.workspace_id.as_str().into(), payload)
.await?,
))
}
pub async fn select_onboarding_import_draft(
Path(path): Path<WorkspaceOnboardingPath>,
State(state): State<AppState>,
Json(payload): Json<SelectOnboardingImportDraftPayload>,
) -> Result<Json<SelectOnboardingImportDraftResponse>, ApiError> {
Ok(Json(
state
.service
.select_onboarding_import_draft(&path.workspace_id.as_str().into(), payload)
.await?,
))
}
+342 -464
View File
@@ -2,20 +2,22 @@ use std::collections::{BTreeMap, BTreeSet};
use crank_artifacts::{ArtifactError, MAX_ARTIFACT_BYTES};
use crank_core::{
ExecutionConfig, OperationSecurityLevel, Protocol, ToolQualityFinding, ToolQualitySeverity,
WorkspaceId,
AuthProfileId, ExecutionConfig, OperationId, OperationSecurityLevel, OperationStatus, Protocol,
SecretStatus, ToolQualityFinding, ToolQualitySeverity, WorkspaceId,
};
use crank_import::rest::{
ImportFinding, ImportFindingSeverity, ImportOperationCandidate, NORMALIZER_VERSION,
PROJECTION_VERSION, operation_draft_from_candidate,
ImportFinding, ImportFindingSeverity, ImportNameConflict, ImportOperationCandidate,
NORMALIZER_VERSION, PROJECTION_VERSION, operation_draft_from_candidate,
validate_document_source_safe,
};
use crank_registry::{
ApplyImportJobRequest, ArtifactSourceId, ArtifactSourceSensitivity,
CreateArtifactSourceRequest, CreateImportJobRequest, FinishImportJobRequest,
ImportAuthRequirement, ImportConflictMode, ImportJobApplyResult, ImportJobId, ImportJobKind,
ImportJobSourceEnvelope, ImportJobStatus, ImportOperationDraft, RegistryError,
CreateArtifactSourceRequest, CreateImportJobRequest, CreateImportPlanRequest,
FinishImportJobRequest, ImportConflictMode, ImportJob, ImportJobApplyResult, ImportJobId,
ImportJobKind, ImportJobSourceEnvelope, ImportJobStatus, ImportOperationDraft, ImportPlanId,
RegistryError, RegistryOperation,
};
use serde_json::json;
use serde_json::{Value, json};
use sha2::{Digest, Sha256};
use time::{Duration, OffsetDateTime, format_description::well_known::Rfc3339};
use tracing::{info, instrument};
@@ -23,26 +25,170 @@ use tracing::{info, instrument};
use crate::{
error::ApiError,
service::{
AdminService, OpenApiAuthMapping, OpenApiImportCreatePayload, OpenApiImportCreateResponse,
OpenApiImportCreatedOperation, OpenApiImportPreviewResponse, OpenApiImportSkippedOperation,
OpenApiUpload, OpenApiUploadLocale, OperationPayload, new_prefixed_id,
AdminService, OpenApiImportAuthProfileChoice, OpenApiImportCreatePayload,
OpenApiImportCreateResponse, OpenApiImportCreatedOperation, OpenApiImportPlanApplyPayload,
OpenApiImportPlanCandidateView, OpenApiImportPlanCounts, OpenApiImportPlanCreatePayload,
OpenApiImportPlanCreateResponse, OpenApiImportPlanDecision,
OpenApiImportPlanRevalidationResponse, OpenApiImportPreviewResponse,
OpenApiImportSecurityProfileChoice, OpenApiImportSkippedOperation, OpenApiUpload,
OpenApiUploadLocale, OperationPayload, new_prefixed_id,
},
};
mod external_references;
mod import_plan;
mod job_contract;
mod security;
mod plan_apply;
mod verified_preview;
use external_references::ImportReplayContext;
use import_plan::import_plan_repreview_error;
use job_contract::{
SourceDetachGuard, import_job_dependencies, import_job_normalization_config, import_job_source,
};
use verified_preview::{
ImportPreviewResolution, artifact_error, openapi_source_error, parse_verified_preview,
preview_digest, preview_has_blocker,
};
const IMPORT_JOB_TTL_HOURS: i64 = 24;
const OPENAPI_PARSE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(30);
const OPENAPI_PARSE_CONCURRENCY: usize = 4;
const MAX_IMPORT_PLAN_KEYS: usize = 2_000;
const OPENAPI_SUPPORT_MATRIX_VERSION: &str = "1.0.3";
const MAX_IMPORT_PLAN_KEY_BYTES: usize = 4_096;
const MAX_IMPORT_PLAN_SERVER_URL_BYTES: usize = 8_192;
const MAX_IMPORT_PLAN_NAME_BYTES: usize = 256;
const MAX_IMPORT_PLAN_ID_REF_BYTES: usize = 128;
static OPENAPI_PARSE_SLOTS: tokio::sync::Semaphore =
tokio::sync::Semaphore::const_new(OPENAPI_PARSE_CONCURRENCY);
fn preview_name_conflicts(
preview: &crank_import::rest::ImportPreview,
catalog_names: &[String],
) -> Vec<ImportNameConflict> {
let operations = preview
.groups
.iter()
.flat_map(|group| group.operations.iter())
.collect::<Vec<_>>();
let mut operation_ids = BTreeMap::<&str, usize>::new();
for candidate in &operations {
if let Some(id) = candidate.operation_id.as_deref() {
*operation_ids.entry(id).or_default() += 1;
}
}
let occupied = catalog_names
.iter()
.map(String::as_str)
.collect::<BTreeSet<_>>();
let mut proposals = catalog_names.iter().cloned().collect::<BTreeSet<_>>();
proposals.extend(
operations
.iter()
.map(|candidate| candidate.suggested_name.clone()),
);
let mut conflicts = Vec::new();
for candidate in operations {
let duplicate = candidate
.operation_id
.as_deref()
.is_some_and(|id| operation_ids.get(id).is_some_and(|count| *count > 1));
let invalid = candidate.operation_id.as_deref().is_some_and(|id| {
id.is_empty()
|| id.len() > MAX_IMPORT_PLAN_NAME_BYTES
|| !id.bytes().enumerate().all(|(index, ch)| {
ch.is_ascii_alphabetic() || ch == b'_' || (index > 0 && ch.is_ascii_digit())
})
});
let taken = occupied.contains(candidate.suggested_name.as_str());
if !duplicate && !invalid && !taken {
continue;
}
let base = candidate
.suggested_name
.chars()
.take(240)
.collect::<String>();
let proposal = next_available_name(&base, &mut proposals);
for conflict_type in [
duplicate.then_some("duplicate_name"),
invalid.then_some("invalid_name"),
taken.then_some("taken_name"),
]
.into_iter()
.flatten()
{
conflicts.push(ImportNameConflict {
operation_key: candidate.key.clone(),
conflict_type: conflict_type.to_owned(),
proposed_name: proposal.clone(),
source_location: candidate.source_location.as_ref().map(|location| {
crank_import::rest::SourceLocation {
pointer: if candidate.operation_id.is_some() {
format!("{}/operationId", location.pointer)
} else {
location.pointer.clone()
},
}
}),
});
}
}
conflicts
}
fn next_available_name(base: &str, occupied: &mut BTreeSet<String>) -> String {
// A catalog may contain more names than the preview candidate cap. With
// occupied.len() + 1 suffixes, at least one candidate must be free.
(2..=occupied.len() + 2)
.map(|index| format!("{base}_{index}"))
.find(|name| occupied.insert(name.clone()))
.expect("finite occupied names always leave a free suffix")
}
fn attach_preview_readiness(
preview: &mut crank_import::rest::ImportPreview,
choices: &[OpenApiImportSecurityProfileChoice],
) {
let document_blocked = preview.findings.iter().any(|finding| {
finding.severity == ImportFindingSeverity::Error && finding.operation_key.is_none()
});
for candidate in preview
.groups
.iter_mut()
.flat_map(|group| group.operations.iter_mut())
{
let blocked = document_blocked
|| candidate
.findings
.iter()
.any(|finding| finding.severity == ImportFindingSeverity::Error);
let alternatives = &candidate.security_requirements.alternatives;
let public = alternatives.is_empty()
|| alternatives
.iter()
.any(|alternative| alternative.supported && alternative.schemes.is_empty());
candidate.status = if blocked {
"blocked"
} else if public {
"actionable"
} else if alternatives.iter().enumerate().any(|(index, alternative)| {
alternative.supported
&& choices.iter().any(|choice| {
choice.operation_key == candidate.key
&& choice.alternative_index == index
&& !choice.profiles.is_empty()
})
}) {
"unresolved"
} else {
"blocked"
}
.to_owned();
}
}
impl AdminService {
#[instrument(skip(self, upload), fields(workspace_id = %workspace_id.as_str()))]
pub async fn preview_openapi_import(
@@ -53,29 +199,53 @@ impl AdminService {
self.ensure_workspace_exists(workspace_id).await?;
validate_openapi_upload(&upload)?;
let literal_findings = crank_import::rest::scan_secret_literals(&upload.bytes)
.map_err(|_| ApiError::openapi_upload(upload.locale, "invalid_document"))?;
if !literal_findings.is_empty() {
return Err(ApiError::openapi_upload(
upload.locale,
"literal_credentials_rejected",
));
}
let OpenApiUpload {
bytes,
bytes: raw_bytes,
mime_type,
locale,
} = upload;
let store = self.artifact_store.clone();
let artifact = tokio::task::spawn_blocking(move || store.put_registered(&bytes))
.await
.map_err(|_| ApiError::openapi_upload(locale, "storage_unavailable"))?
.map_err(|error| artifact_error(locale, error))?;
let raw_document = std::str::from_utf8(&raw_bytes)
.map_err(|_| ApiError::openapi_upload(locale, "invalid_utf8"))?;
validate_document_source_safe(raw_document, &self.external_reference_normalization)
.map_err(|_| ApiError::openapi_upload(locale, "invalid_document"))?;
let now = OffsetDateTime::now_utc();
let mut dependencies = self
.materialize_external_reference_snapshots(workspace_id, &raw_bytes, now)
.await;
if dependencies.unsafe_source {
return Err(ApiError::openapi_upload(locale, "invalid_document"));
}
let source_digest =
crank_import::rest::SourceDigest::parse(format!("{:x}", Sha256::digest(&raw_bytes)))
.map_err(|_| ApiError::openapi_upload(locale, "invalid_document"))?;
if crank_import::rest::validate_resolved_bundle_source_safe(
raw_document,
source_digest,
&dependencies.snapshots,
&self.external_reference_normalization,
)
.is_err()
{
dependencies.detach_all().await;
return Err(ApiError::openapi_upload(locale, "invalid_document"));
}
let bytes = raw_bytes;
let store = self.artifact_store.clone();
let artifact_result = tokio::task::spawn_blocking(move || store.put_registered(&bytes))
.await
.map_err(|_| ApiError::openapi_upload(locale, "storage_unavailable"))
.and_then(|result| result.map_err(|error| artifact_error(locale, error)));
let artifact = match artifact_result {
Ok(artifact) => artifact,
Err(error) => {
dependencies.detach_all().await;
return Err(error);
}
};
let expires_at = now + Duration::hours(IMPORT_JOB_TTL_HOURS);
let job_id = ImportJobId::new(new_prefixed_id("imp"));
let source_id = ArtifactSourceId::new(new_prefixed_id("src_openapi"));
let source = self
let source_result = self
.registry
.create_artifact_source(CreateArtifactSourceRequest {
workspace_id,
@@ -85,7 +255,14 @@ impl AdminService {
sensitivity: ArtifactSourceSensitivity::Internal,
created_at: now,
})
.await?;
.await;
let source = match source_result {
Ok(source) => source,
Err(error) => {
dependencies.detach_all().await;
return Err(ApiError::from(error));
}
};
let mut detach_guard = SourceDetachGuard::new(
self.registry.clone(),
workspace_id.clone(),
@@ -111,17 +288,6 @@ impl AdminService {
detach_guard.detach_now().await;
return Err(ApiError::openapi_upload(locale, "source_integrity"));
}
let mut dependencies = self
.materialize_external_reference_snapshots(workspace_id, &verified.bytes, now)
.await;
if dependencies.secret_literal_rejected {
dependencies.detach_all().await;
detach_guard.detach_now().await;
return Err(ApiError::openapi_upload(
locale,
"literal_credentials_rejected",
));
}
let parsed = match parse_verified_preview(
verified.bytes,
artifact.artifact_ref().digest_hex().to_owned(),
@@ -149,8 +315,22 @@ impl AdminService {
detach_guard.detach_now().await;
return Err(ApiError::openapi_upload(locale, "no_methods"));
}
let auth_profile_choices = match self
.openapi_auth_profile_choices(workspace_id, &parsed.preview)
let candidate_count: usize = parsed
.preview
.groups
.iter()
.map(|group| group.operations.len())
.sum();
if candidate_count > MAX_IMPORT_PLAN_KEYS {
dependencies.detach_all().await;
detach_guard.detach_now().await;
return Err(ApiError::validation_with_context(
"OpenAPI preview has too many candidates",
json!({ "error_code": "openapi_preview_too_many_candidates", "limit": MAX_IMPORT_PLAN_KEYS }),
));
}
let security_profile_choices = match self
.security_profile_choices(workspace_id, &parsed.preview)
.await
{
Ok(choices) => choices,
@@ -160,6 +340,14 @@ impl AdminService {
return Err(error);
}
};
let catalog_names = match self.registry.list_import_catalog_names(workspace_id).await {
Ok(names) => names,
Err(error) => {
dependencies.detach_all().await;
detach_guard.detach_now().await;
return Err(ApiError::from(error));
}
};
let source_envelope = ImportJobSourceEnvelope {
source_id,
digest: artifact.artifact_ref().clone(),
@@ -207,16 +395,92 @@ impl AdminService {
dependencies.disarm();
detach_guard.disarm();
let mut response_preview = parsed.preview;
response_preview.conflicts = preview_name_conflicts(&response_preview, &catalog_names);
attach_preview_readiness(&mut response_preview, &security_profile_choices);
Ok(OpenApiImportPreviewResponse {
job_id: job_id.as_str().to_owned(),
expires_at: expires_at
.format(&Rfc3339)
.map_err(|error| ApiError::internal(error.to_string()))?,
auth_profile_choices,
preview: parsed.preview,
preview: response_preview,
security_profile_choices,
})
}
async fn security_profile_choices(
&self,
workspace_id: &WorkspaceId,
preview: &crank_import::rest::ImportPreview,
) -> Result<Vec<OpenApiImportSecurityProfileChoice>, ApiError> {
let profiles = self.registry.list_auth_profiles(workspace_id).await?;
let mut available = Vec::new();
for profile in profiles {
if profile.kind != profile.config.kind() {
continue;
}
let mut usable = true;
for secret_id in profile.config.secret_ids() {
let Some(secret) = self.registry.get_secret(workspace_id, secret_id).await? else {
usable = false;
break;
};
if secret.secret.status != SecretStatus::Active
|| self
.registry
.get_current_secret_version(workspace_id, secret_id)
.await?
.is_none()
{
usable = false;
break;
}
}
if usable {
available.push(profile);
}
}
let mut choices = Vec::new();
for operation in preview
.groups
.iter()
.flat_map(|group| group.operations.iter())
{
for (alternative_index, alternative) in operation
.security_requirements
.alternatives
.iter()
.enumerate()
{
if !alternative.supported || alternative.schemes.len() != 1 {
continue;
}
let Some(scheme) = operation.security_schemes.get(&alternative.schemes[0]) else {
continue;
};
let profiles = available
.iter()
.filter(|profile| {
import_plan::auth_config_matches_scheme(&profile.config, scheme)
})
.map(|profile| OpenApiImportAuthProfileChoice {
id: profile.id.as_str().to_owned(),
name: profile.name.clone(),
kind: profile.kind,
})
.collect::<Vec<_>>();
choices.push(OpenApiImportSecurityProfileChoice {
operation_key: operation.key.clone(),
alternative_index,
schemes: alternative.schemes.clone(),
profiles,
});
}
}
Ok(choices)
}
#[instrument(skip(self, payload), fields(workspace_id = %workspace_id.as_str(), job_id = %job_id.as_str()))]
pub async fn create_openapi_import(
&self,
@@ -259,7 +523,11 @@ impl AdminService {
)
})?;
if job.expires_at <= OffsetDateTime::now_utc() {
return Err(ApiError::validation("import preview has expired"));
let message = match locale {
OpenApiUploadLocale::Ru => "срок действия preview импорта истёк",
OpenApiUploadLocale::En => "import preview has expired",
};
return Err(ApiError::validation(message));
}
if job.kind != ImportJobKind::OpenApi {
return Err(ApiError::validation("import job kind is not openapi"));
@@ -276,15 +544,6 @@ impl AdminService {
));
}
let finished_at = OffsetDateTime::now_utc();
let mut auth_mappings = BTreeMap::new();
for mapping in &payload.auth_mappings {
if auth_mappings
.insert(mapping.operation_key.clone(), mapping)
.is_some()
{
return Err(ApiError::openapi_upload(locale, "auth_mapping_invalid"));
}
}
let application_key = openapi_application_key(&payload)?;
let conflict_mode = if payload.conflict_mode == "skip" {
ImportConflictMode::Skip
@@ -314,141 +573,20 @@ impl AdminService {
return Ok(openapi_import_response(applied));
}
let source = match import_job_source(&job.preview_payload, locale) {
Ok(source) => source,
Err(error) => {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_source_verification_failed",
error,
)
.await;
}
};
let verified = match self
.registry
.read_artifact_source(
std::sync::Arc::clone(&self.artifact_store),
workspace_id,
&source.source_id,
)
let resolved_preview = match self
.resolve_verified_openapi_preview(workspace_id, &job, locale)
.await
{
Ok(verified) => verified,
Err(
error @ (RegistryError::SourceNotFound { .. } | RegistryError::SourceUnavailable),
) => {
Ok(resolved) => resolved,
Err(ImportPreviewResolution::Fatal(error_code, error)) => {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_source_verification_failed",
openapi_source_error(locale, error),
)
.fail_openapi_import_or_replay(&replay_context, error_code, error)
.await;
}
Err(error @ RegistryError::SourceIntegrity) => {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_source_verification_failed",
openapi_source_error(locale, error),
)
.await;
}
Err(error) => return Err(openapi_source_error(locale, error)),
Err(ImportPreviewResolution::NonFatal(error)) => return Err(error),
};
if verified.source.blob.artifact_ref != source.digest {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_source_verification_failed",
ApiError::openapi_upload(locale, "source_integrity"),
)
.await;
}
let replay_contract = match import_replay_contract(&job.preview_payload, locale) {
Ok(contract) => contract,
Err(error) => {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_replay_verification_failed",
error,
)
.await;
}
};
let parsed = match replay_contract {
ImportReplayContract::PersistedV2(parsed) => parsed,
ImportReplayContract::LegacyV1 | ImportReplayContract::Current => {
let legacy_v1 = matches!(replay_contract, ImportReplayContract::LegacyV1);
let dependency_snapshots = match self
.read_import_job_dependencies(workspace_id, &job.preview_payload, locale)
.await
{
Ok(snapshots) => snapshots,
Err(error) => {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_dependency_verification_failed",
error,
)
.await;
}
};
let normalization_config = match import_job_normalization_config(
&job.preview_payload,
&self.external_reference_normalization,
legacy_v1,
locale,
) {
Ok(config) => config,
Err(error) => {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_replay_verification_failed",
error,
)
.await;
}
};
let parsed = match parse_verified_preview(
verified.bytes,
source.digest.digest_hex().to_owned(),
dependency_snapshots,
normalization_config,
locale,
legacy_v1,
)
.await
{
Ok(parsed) => parsed,
Err(error) => {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_replay_verification_failed",
error,
)
.await;
}
};
if let Err(error) = verify_preview_contract(&job.preview_payload, &parsed, locale) {
return self
.fail_openapi_import_or_replay(
&replay_context,
"import_replay_verification_failed",
error,
)
.await;
}
parsed
}
};
if preview_has_blocker(&parsed.preview, &selected) {
let preview = resolved_preview.preview;
if preview_has_blocker(&preview, &selected) {
return self
.fail_openapi_import_or_replay(
&replay_context,
@@ -458,25 +596,11 @@ impl AdminService {
.await;
}
let mut candidates = BTreeMap::new();
for group in &parsed.preview.groups {
for group in &preview.groups {
for operation in &group.operations {
candidates.insert(operation.key.clone(), operation);
}
}
if auth_mappings.iter().any(|(operation_key, mapping)| {
!selected.contains(operation_key)
|| candidates.get(operation_key).is_none_or(|candidate| {
mapping.alternative_index >= candidate.security_requirements.alternatives.len()
})
}) {
return self
.fail_openapi_import_or_replay(
&replay_context,
"auth_mapping_invalid",
ApiError::openapi_upload(locale, "auth_mapping_invalid"),
)
.await;
}
let mut skipped = Vec::new();
let mut operations = Vec::new();
@@ -490,26 +614,6 @@ impl AdminService {
});
continue;
};
let (auth_profile_ref, auth_requirement) = match self
.resolve_openapi_auth_binding(
workspace_id,
candidate,
auth_mappings.get(&operation_key).copied(),
locale,
)
.await
{
Ok(binding) => binding,
Err(error) => {
return self
.fail_openapi_import_or_replay(
&replay_context,
"auth_binding_unavailable",
error,
)
.await;
}
};
let mut draft =
operation_draft_from_candidate(candidate, payload.server_url.as_deref());
attach_import_findings(&mut draft, candidate);
@@ -531,7 +635,7 @@ impl AdminService {
idempotency: None,
safety: None,
approval_policy: None,
auth_profile_ref,
auth_profile_ref: None,
headers: BTreeMap::new(),
},
tool_description: draft.tool_description,
@@ -540,7 +644,6 @@ impl AdminService {
operations.push(ImportOperationDraft {
operation_key: candidate.key.clone(),
operation,
auth_requirement,
});
}
@@ -555,13 +658,7 @@ impl AdminService {
pre_skipped: &skipped,
finished_at: &finished_at,
})
.await
.map_err(|error| match error {
RegistryError::ImportAuthBindingUnavailable => {
ApiError::openapi_auth_binding_unavailable(locale)
}
error => error.into(),
})?;
.await?;
Ok(openapi_import_response(applied))
}
@@ -611,6 +708,7 @@ fn openapi_import_response(applied: ImportJobApplyResult) -> OpenApiImportCreate
operation.name
),
operation_key: Some(operation.operation_key.clone()),
source_location: None,
})
})
.collect::<Vec<_>>();
@@ -629,6 +727,7 @@ fn openapi_import_response(applied: ImportJobApplyResult) -> OpenApiImportCreate
format!("Операция {name} уже существует и была пропущена.")
},
operation_key: Some(operation.operation_key.clone()),
source_location: None,
});
OpenApiImportSkippedOperation {
operation_key: operation.operation_key.clone(),
@@ -678,252 +777,14 @@ fn validate_openapi_upload(upload: &OpenApiUpload) -> Result<(), ApiError> {
Ok(())
}
struct ParsedOpenApiPreview {
preview: crank_import::rest::ImportPreview,
ir_fingerprint: String,
}
enum ImportReplayContract {
LegacyV1,
PersistedV2(ParsedOpenApiPreview),
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 v2-v4 preview payloads are replayed as their persisted
// projection. They must never be parsed again with current v5 semantics.
if !matches!(
(normalizer, projection),
("normalized-ir-v2", "preview-v2")
| ("normalized-ir-v3", "preview-v3")
| ("normalized-ir-v4", "preview-v4")
) {
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(ParsedOpenApiPreview {
preview,
ir_fingerprint: ir_fingerprint.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))
}
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"))?
}
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"),
}
}
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),
}
}
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"))
}
}
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))
.flat_map(|operation| operation.findings.iter())
.any(|finding| {
finding.severity == ImportFindingSeverity::Error
&& !matches!(
finding.code.as_str(),
"unsupported_security_and_requirement"
| "unsupported_security_scheme"
| "unresolved_security_scheme"
)
})
}
fn openapi_application_key(payload: &OpenApiImportCreatePayload) -> Result<String, ApiError> {
let selected_operation_keys = payload
.selected_operation_keys
.iter()
.cloned()
.collect::<BTreeSet<_>>();
let mut auth_mappings = payload.auth_mappings.clone();
auth_mappings.sort_by(|left, right| {
left.operation_key
.cmp(&right.operation_key)
.then(left.alternative_index.cmp(&right.alternative_index))
});
let canonical = serde_json::to_vec(&json!({
"selected_operation_keys": selected_operation_keys,
"auth_mappings": auth_mappings,
"server_url": payload.server_url.as_deref(),
"conflict_mode": payload.conflict_mode.as_str(),
}))
@@ -965,3 +826,20 @@ fn tool_quality_finding_from_import(finding: &ImportFinding) -> ToolQualityFindi
field_path: finding.operation_key.clone(),
}
}
#[cfg(test)]
mod preview_name_tests {
use super::next_available_name;
use std::collections::BTreeSet;
#[test]
fn crowded_catalog_still_gets_a_free_deterministic_proposal() {
let mut occupied = (2..=2_002)
.map(|index| format!("shared_{index}"))
.collect::<BTreeSet<_>>();
occupied.insert("shared".to_owned());
assert_eq!(next_available_name("shared", &mut occupied), "shared_2003");
assert_eq!(next_available_name("shared", &mut occupied), "shared_2004");
}
}
@@ -4,10 +4,16 @@ use tracing::warn;
pub(super) struct MaterializedDependencies {
pub(super) snapshots: Vec<crank_import::rest::ExternalDocumentSnapshot>,
pub(super) secret_literal_rejected: bool,
envelopes: Vec<ImportJobSourceEnvelope>,
canonical_uris: Vec<String>,
guards: Vec<SourceDetachGuard>,
pub(super) unsafe_source: bool,
}
struct StagedDependency {
canonical_uri: String,
bytes: Vec<u8>,
document: String,
}
pub(super) struct ImportReplayContext<'a> {
@@ -22,10 +28,10 @@ impl MaterializedDependencies {
fn empty() -> Self {
Self {
snapshots: Vec::new(),
secret_literal_rejected: false,
envelopes: Vec::new(),
canonical_uris: Vec::new(),
guards: Vec::new(),
unsafe_source: false,
}
}
@@ -178,8 +184,8 @@ impl AdminService {
}
}
let mut seen = BTreeSet::new();
let mut result = MaterializedDependencies::empty();
let mut dependency_by_digest = BTreeMap::<String, usize>::new();
let mut staged = Vec::<StagedDependency>::new();
let mut staged_documents = vec![primary.to_owned()];
while let Some((canonical_uri, depth)) = queue.pop_front() {
if !seen.insert(canonical_uri.clone())
|| depth > self.external_reference_normalization.max_reference_depth
@@ -196,52 +202,77 @@ impl AdminService {
materialization_failure(
"fetch",
external_fetch_error_code(&error),
result.snapshots.len(),
staged.len(),
);
continue;
}
};
let Ok(document) = std::str::from_utf8(&bytes).map(str::to_owned) else {
materialization_failure(
"dependency_decode",
"invalid_utf8",
result.snapshots.len(),
);
materialization_failure("dependency_decode", "invalid_utf8", staged.len());
continue;
};
match crank_import::rest::scan_secret_literals(&bytes) {
Ok(findings) if !findings.is_empty() => {
materialization_failure(
"security_scan",
"literal_credentials_rejected",
result.snapshots.len(),
);
result.secret_literal_rejected = true;
break;
}
Ok(_) => {}
Err(_) => {
materialization_failure(
"security_scan",
"invalid_document",
result.snapshots.len(),
);
continue;
}
}
let Ok(references) = crank_import::rest::external_reference_uris(
&document,
&self.external_reference_normalization,
) else {
materialization_failure(
"dependency_scan",
"invalid_document",
result.snapshots.len(),
);
materialization_failure("dependency_scan", "invalid_document", staged.len());
continue;
};
staged_documents.push(document.clone());
staged.push(StagedDependency {
canonical_uri: canonical_uri.clone(),
bytes,
document,
});
for reference in references {
if let Some(uri) = canonical_external_document_uri(Some(&canonical_uri), &reference)
{
queue.push_back((uri, depth.saturating_add(1)));
}
}
}
let staged_snapshots = staged
.iter()
.filter_map(|dependency| {
let digest = format!("{:x}", Sha256::digest(&dependency.bytes));
let digest = crank_import::rest::SourceDigest::parse(digest).ok()?;
Some(crank_import::rest::ExternalDocumentSnapshot {
canonical_uri: dependency.canonical_uri.clone(),
digest,
document: dependency.document.clone(),
})
})
.collect::<Vec<_>>();
let primary_digest =
crank_import::rest::SourceDigest::parse(format!("{:x}", Sha256::digest(primary_bytes)))
.expect("SHA-256 digest is valid");
let raw_bundle_is_unsafe = crank_import::rest::validate_document_bundle_source_safe(
&staged_documents
.iter()
.map(String::as_str)
.collect::<Vec<_>>(),
&self.external_reference_normalization,
)
.is_err();
let resolved_bundle_is_unsafe = crank_import::rest::validate_resolved_bundle_source_safe(
primary,
primary_digest,
&staged_snapshots,
&self.external_reference_normalization,
)
.is_err();
if raw_bundle_is_unsafe || resolved_bundle_is_unsafe {
materialization_failure("dependency_redaction", "invalid_document", staged.len());
let mut rejected = MaterializedDependencies::empty();
rejected.unsafe_source = true;
return rejected;
}
let mut result = MaterializedDependencies::empty();
let mut dependency_by_digest = BTreeMap::<String, usize>::new();
for dependency in staged {
let store = self.artifact_store.clone();
let artifact_bytes = bytes.clone();
let artifact_bytes = dependency.bytes.clone();
let Ok(Ok(artifact)) =
tokio::task::spawn_blocking(move || store.put_registered(&artifact_bytes)).await
else {
@@ -317,31 +348,22 @@ impl AdminService {
dependency_by_digest.insert(digest_key, index);
index
};
let dependency = &result.envelopes[envelope_index];
let snapshot_digest = match crank_import::rest::SourceDigest::parse(
dependency.digest.digest_hex().to_owned(),
) {
Ok(digest) => digest,
Err(_) => {
materialization_failure("snapshot", "source_integrity", result.snapshots.len());
continue;
}
let dependency_envelope = &result.envelopes[envelope_index];
let Ok(snapshot_digest) = crank_import::rest::SourceDigest::parse(
dependency_envelope.digest.digest_hex().to_owned(),
) else {
materialization_failure("snapshot", "source_integrity", result.snapshots.len());
continue;
};
result
.snapshots
.push(crank_import::rest::ExternalDocumentSnapshot {
canonical_uri: canonical_uri.clone(),
canonical_uri: dependency.canonical_uri.clone(),
digest: snapshot_digest,
document,
document: dependency.document,
});
materialized_count.store(result.snapshots.len(), std::sync::atomic::Ordering::Relaxed);
result.canonical_uris.push(canonical_uri.clone());
for reference in references {
if let Some(uri) = canonical_external_document_uri(Some(&canonical_uri), &reference)
{
queue.push_back((uri, depth.saturating_add(1)));
}
}
result.canonical_uris.push(dependency.canonical_uri);
}
// Registry ownership is one envelope per immutable digest, while the
// resolver may map several canonical URIs to that same snapshot. Keep
@@ -390,14 +412,6 @@ impl AdminService {
}
let document = String::from_utf8(verified.bytes)
.map_err(|_| ApiError::openapi_upload(locale, "source_integrity"))?;
let findings = crank_import::rest::scan_secret_literals(document.as_bytes())
.map_err(|_| ApiError::openapi_upload(locale, "source_integrity"))?;
if !findings.is_empty() {
return Err(ApiError::openapi_upload(
locale,
"literal_credentials_rejected",
));
}
let digest =
crank_import::rest::SourceDigest::parse(dependency.digest.digest_hex().to_owned())
.map_err(|_| ApiError::openapi_upload(locale, "source_integrity"))?;
@@ -0,0 +1,976 @@
mod validation;
use super::*;
use crank_core::AuthConfig;
use crank_import::rest::SecurityRequirementsSource as SecuritySource;
impl AdminService {
pub async fn create_openapi_import_plan(
&self,
workspace_id: &WorkspaceId,
job_id: &ImportJobId,
payload: OpenApiImportPlanCreatePayload,
) -> Result<OpenApiImportPlanCreateResponse, ApiError> {
self.create_openapi_import_plan_with_locale(
workspace_id,
job_id,
payload,
OpenApiUploadLocale::En,
)
.await
}
#[instrument(skip(self, payload), fields(workspace_id = %workspace_id.as_str(), job_id = %job_id.as_str()))]
pub async fn create_openapi_import_plan_with_locale(
&self,
workspace_id: &WorkspaceId,
job_id: &ImportJobId,
payload: OpenApiImportPlanCreatePayload,
locale: OpenApiUploadLocale,
) -> Result<OpenApiImportPlanCreateResponse, ApiError> {
self.ensure_workspace_exists(workspace_id).await?;
let now = OffsetDateTime::now_utc();
let job = self
.registry
.get_import_job(workspace_id, job_id)
.await?
.ok_or_else(|| {
ApiError::not_found_with_context(
"import job was not found",
json!({ "job_id": job_id.as_str() }),
)
})?;
if job.kind != ImportJobKind::OpenApi {
return Err(ApiError::validation("import job kind is not openapi"));
}
if job.expires_at <= now {
let message = match locale {
OpenApiUploadLocale::Ru => "срок действия preview импорта истёк",
OpenApiUploadLocale::En => "import preview has expired",
};
return Err(ApiError::validation(message));
}
if job.status != ImportJobStatus::Pending {
return Err(import_plan_repreview_error(
locale,
"import_plan_job_terminal",
));
}
if payload.decisions.len() > MAX_IMPORT_PLAN_KEYS {
return Err(ApiError::validation(
"too many decision blocks for this import plan",
));
}
if payload.server_url.as_deref().is_some_and(|server_url| {
server_url.is_empty() || server_url.len() > MAX_IMPORT_PLAN_SERVER_URL_BYTES
}) {
return Err(ApiError::validation_with_context(
"server_url is empty or too long",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
// The plan is anchored to the verified job snapshots. A stale or
// corrupt preview is reported as bounded re-preview guidance and
// never mutates the job: other stored plans may still reference the
// same job and its replay must remain readable.
let resolved = self
.resolve_verified_openapi_preview(workspace_id, &job, locale)
.await
.map_err(|resolution| match resolution {
ImportPreviewResolution::Fatal(error_code, _) => {
import_plan_repreview_error(locale, error_code)
}
ImportPreviewResolution::NonFatal(error) => error,
})?;
let preview = &resolved.preview;
let catalog_revision = self.registry.import_catalog_revision(workspace_id).await?;
// Stored external dependency snapshots are re-verified for every
// replay variant (including historically persisted ones) without a
// network fetch: detached or altered snapshots are re-preview
// material and no plan is created.
self.read_import_job_dependencies(workspace_id, &job.preview_payload, locale)
.await
.map_err(|_| {
import_plan_repreview_error(locale, "import_dependency_verification_failed")
})?;
let candidates: BTreeMap<String, &ImportOperationCandidate> = preview
.groups
.iter()
.flat_map(|group| group.operations.iter())
.map(|operation| (operation.key.clone(), operation))
.collect();
let all_set: BTreeSet<String> = candidates.keys().cloned().collect();
if all_set.len() > MAX_IMPORT_PLAN_KEYS {
return Err(ApiError::validation_with_context(
"too many candidates for an import plan",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
let selected = resolve_plan_selection(
&payload.selection_mode,
&payload.selected_operation_keys,
&all_set,
)?;
if selected.len() > MAX_IMPORT_PLAN_KEYS
|| all_set.len() - selected.len() > MAX_IMPORT_PLAN_KEYS
{
return Err(ApiError::validation_with_context(
"too many candidates for an import plan",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
let selected_keys: Vec<String> = selected.iter().cloned().collect();
let excluded: Vec<String> = all_set
.iter()
.filter(|key| !selected.contains(*key))
.cloned()
.collect();
let excluded_reasons = excluded
.iter()
.map(|key| {
let name = candidates
.get(key)
.map(|candidate| candidate.draft.name.clone())
.unwrap_or_else(|| key.clone());
let reason = preview
.findings
.iter()
.find(|finding| {
finding.severity == ImportFindingSeverity::Error
&& finding.operation_key.is_none()
})
.map(|finding| finding.code.clone())
.or_else(|| {
candidates.get(key).and_then(|candidate| {
candidate
.findings
.iter()
.find(|finding| finding.severity == ImportFindingSeverity::Error)
.map(|finding| finding.code.clone())
})
})
.unwrap_or_else(|| "not_selected".to_owned());
(key.clone(), (name, reason))
})
.collect::<BTreeMap<_, _>>();
let decisions = validation::validate_plan_decisions(&payload.decisions, &selected)?;
let global_blocker = preview
.findings
.iter()
.find(|finding| {
finding.severity == ImportFindingSeverity::Error && finding.operation_key.is_none()
})
.map(|finding| finding.code.clone());
let mut planned = Vec::with_capacity(selected_keys.len());
for key in &selected_keys {
let Some(candidate) = candidates.get(key) else {
unreachable!("selection is validated against the candidate set");
};
let blocker = global_blocker.clone().or_else(|| {
candidate
.findings
.iter()
.find(|finding| finding.severity == ImportFindingSeverity::Error)
.map(|finding| finding.code.clone())
});
let candidate_plan = self
.plan_import_candidate(
workspace_id,
payload.server_url.as_deref(),
candidate,
decisions.get(key).copied(),
blocker,
locale,
)
.await?;
planned.push(candidate_plan);
}
let counts = OpenApiImportPlanCounts {
selected: planned.len(),
excluded: excluded.len(),
actionable: planned
.iter()
.filter(|candidate| !candidate.blocked)
.count(),
blocked: planned.iter().filter(|candidate| candidate.blocked).count(),
};
if payload.selection_mode == "partial" && counts.blocked != 0 {
return Err(ApiError::validation_with_context(
"partial selection includes blocked candidates",
json!({ "error_code": "import_plan_partial_blocked" }),
));
}
if self.registry.import_catalog_revision(workspace_id).await? != catalog_revision {
return Err(import_plan_repreview_error(
locale,
"import_plan_catalog_stale",
));
}
// Server-authored immutable plan. Client-supplied candidate material,
// digests or payload fields are not read: every value below derives
// from the verified job preview and the revalidated decisions.
let all_keys: Vec<String> = all_set.iter().cloned().collect();
let plan_counts_value = json!({
"selected": counts.selected,
"excluded": counts.excluded,
"actionable": counts.actionable,
"blocked": counts.blocked,
});
let plan_reference = new_prefixed_id("plan");
let plan_payload = json!({
"schema_version": "import-plan-v2",
"plan_reference": plan_reference,
"job_id": job_id.as_str(),
"server_url": payload.server_url,
"source": {
"source_id": resolved.source.source_id.as_str(),
"digest": resolved.source.digest.as_str(),
},
"dependencies": job.preview_payload.get("dependencies").cloned().unwrap_or(json!([])),
"fingerprint": resolved.fingerprint,
"catalog_revision": catalog_revision,
"support_matrix_version": OPENAPI_SUPPORT_MATRIX_VERSION,
"findings": {
"document": preview.findings,
"candidates": candidates.iter().map(|(key, candidate)| json!({
"key": key,
"findings": candidate.findings,
})).collect::<Vec<_>>(),
},
"selection": {
"mode": payload.selection_mode,
"all": all_keys,
"selected": selected_keys,
"excluded": excluded,
},
"excluded_reasons": excluded_reasons.iter().map(|(key, (name, reason))| json!({
"key": key,
"name": name,
"reason": reason,
})).collect::<Vec<_>>(),
"counts": plan_counts_value,
"candidates": planned.iter().map(plan_candidate_payload).collect::<Result<Vec<_>, _>>()?,
});
let plan_reference_id = ImportPlanId::new(&plan_reference);
let created = self
.registry
.create_import_plan(CreateImportPlanRequest {
id: &plan_reference_id,
workspace_id,
job_id,
payload: &plan_payload,
created_at: &now,
expires_at: &job.expires_at,
})
.await
.map_err(ApiError::from)?;
let mut candidate_views: Vec<OpenApiImportPlanCandidateView> = planned
.iter()
.map(|candidate| OpenApiImportPlanCandidateView {
key: candidate.key.clone(),
name: candidate.name.clone(),
state: if candidate.blocked {
"blocked"
} else {
"actionable"
}
.to_owned(),
action: Some(candidate.action.clone()),
target_operation_id: candidate.target_operation_id.clone(),
confirmed_name: candidate.confirmed_name.clone(),
auth_profile_id: candidate.auth_profile_id.clone(),
security_alternative_index: candidate.security_alternative_index,
reason: candidate.reason.clone(),
})
.collect();
candidate_views.extend(excluded.iter().map(|key| {
let name = excluded_reasons
.get(key)
.map(|(name, _)| name.clone())
.unwrap_or_else(|| key.clone());
OpenApiImportPlanCandidateView {
key: key.clone(),
name,
state: "excluded".to_owned(),
action: None,
target_operation_id: None,
confirmed_name: None,
auth_profile_id: None,
security_alternative_index: None,
reason: excluded_reasons.get(key).map(|(_, reason)| reason.clone()),
}
}));
Ok(OpenApiImportPlanCreateResponse {
plan_reference: created.id.as_str().to_owned(),
plan_digest: created.digest,
catalog_revision,
support_matrix_version: OPENAPI_SUPPORT_MATRIX_VERSION.to_owned(),
expires_at: created
.expires_at
.format(&Rfc3339)
.map_err(|error| ApiError::internal(error.to_string()))?,
selection_mode: payload.selection_mode,
counts,
candidates: candidate_views,
})
}
/// Materializes one selected candidate of the plan: the confirmed
/// decision, the exact authorized target with its expected state and the
/// full Draft snapshot (create/rename/new_version) or the bounded
/// redacted rejection reason (blocked).
async fn plan_import_candidate(
&self,
workspace_id: &WorkspaceId,
server_url: Option<&str>,
candidate: &ImportOperationCandidate,
decision: Option<&OpenApiImportPlanDecision>,
blocker_reason: Option<String>,
locale: OpenApiUploadLocale,
) -> Result<PlannedCandidate, ApiError> {
let action = decision
.map(|decision| decision.action.as_str())
.unwrap_or("create");
let target_operation_id =
decision.and_then(|decision| decision.target_operation_id.clone());
let confirmed_name = decision.and_then(|decision| decision.confirmed_name.clone());
let auth_profile_id = decision.and_then(|decision| decision.auth_profile_id.clone());
let requested_security_alternative =
decision.and_then(|decision| decision.security_alternative_index);
let mut blocker_reason = blocker_reason;
let candidate_name = candidate.draft.name.clone();
let mut blocked = blocker_reason.is_some();
// Explicit skip/new_version targets are always resolved in the
// workspace: an unknown target, a name mismatch, or an incompatible
// protocol is a request error even when the candidate is already
// blocked.
let mut target = None;
let mut target_summary = None;
let mut next_version: Option<u32> = None;
if matches!(action, "skip" | "new_version") {
let target_id = target_operation_id
.as_ref()
.expect("target_operation_id is validated for skip/new_version")
.clone();
let target_operation = OperationId::new(target_id.clone());
let summary = self
.registry
.get_operation_summary(workspace_id, &target_operation)
.await?
.ok_or_else(|| {
ApiError::validation_with_context(
"decision target operation was not found in this workspace",
json!({
"target_operation_id": target_id,
"error_code": "import_plan_target_invalid"
}),
)
})?;
if summary.name != candidate_name {
return Err(ApiError::validation_with_context(
"decision target does not match the candidate name in this workspace",
json!({
"target_operation_id": target_id,
"error_code": "import_plan_target_invalid"
}),
));
}
if action == "new_version"
&& (summary.protocol != Protocol::Rest
|| summary.status == OperationStatus::Archived)
{
return Err(ApiError::validation_with_context(
"new_version target must be an active REST operation",
json!({
"target_operation_id": target_id,
"error_code": "import_plan_target_invalid"
}),
));
}
target = Some(json!({
"operation_id": target_id,
"name": summary.name,
"expected_state": {
"status": serde_json::to_value(summary.status)
.map_err(|error| ApiError::internal(error.to_string()))?,
"current_draft_version": summary.current_draft_version,
"latest_published_version": summary.latest_published_version,
},
}));
if action == "new_version" {
let version = summary
.current_draft_version
.checked_add(1)
.filter(|value| i32::try_from(*value).is_ok())
.ok_or_else(|| {
ApiError::conflict_with_context(
"operation revision limit reached",
json!({ "error_code": "operation_revision_exhausted" }),
)
})?;
next_version = Some(version);
}
target_summary = Some(summary);
}
// create/rename must land on a name that is free now; the server
// never auto-selects a replacement when the confirmed name is taken.
if !blocked && matches!(action, "create" | "rename") {
let final_name = confirmed_name.as_deref().unwrap_or(candidate_name.as_str());
if self
.find_operation_by_name(workspace_id, final_name)
.await?
.is_some()
{
if action == "create" && decision.is_none() {
return Ok(PlannedCandidate {
key: candidate.key.clone(),
name: candidate_name,
blocked: true,
reason: Some("operation_name_conflict".to_owned()),
action: action.to_owned(),
target_operation_id,
confirmed_name,
auth_profile_id,
security_alternative_index: requested_security_alternative,
auth_requirement: None,
auth_snapshot: None,
target: None,
operation: None,
});
}
let message = match locale {
OpenApiUploadLocale::Ru => {
format!("операция с именем {final_name} уже существует")
}
OpenApiUploadLocale::En => {
format!("operation with name {final_name} already exists")
}
};
return Err(ApiError::conflict_with_context(
message,
json!({
"name": final_name,
"error_code": "import_plan_name_conflict",
"recovery": "confirm_skip_rename_or_new_version"
}),
));
}
}
// Use an explicit decision or inherit the target reference for new_version.
let mut auth_profile_ref = auth_profile_id
.as_deref()
.map(|id| AuthProfileId::new(id.to_owned()));
let mut inherited_auth_profile = false;
if let Some(summary) = target_summary.as_ref()
&& !blocked
&& action == "new_version"
&& auth_profile_ref.is_none()
&& (candidate.security_requirements.source == SecuritySource::None
|| !candidate.security_requirements.alternatives.is_empty())
{
let record = self
.registry
.get_operation_version(workspace_id, &summary.id, summary.current_draft_version)
.await?
.ok_or_else(|| ApiError::internal("current operation version is unavailable"))?;
auth_profile_ref = record.snapshot.execution_config.auth_profile_ref;
inherited_auth_profile = auth_profile_ref.is_some();
}
let auth_profile_id = auth_profile_ref.as_ref().map(|id| id.as_str().to_owned());
let inherited_unconstrained_auth = inherited_auth_profile
&& action == "new_version"
&& candidate.security_requirements.source
== crank_import::rest::SecurityRequirementsSource::None
&& candidate.security_requirements.alternatives.is_empty()
&& requested_security_alternative.is_none();
let security_alternative_index = if blocked {
requested_security_alternative
} else if inherited_unconstrained_auth {
None
} else {
resolve_security_binding(
self,
workspace_id,
candidate,
auth_profile_ref.as_ref(),
requested_security_alternative,
&mut blocker_reason,
)
.await?
};
blocked = blocker_reason.is_some();
let auth_requirement = if !blocked && inherited_unconstrained_auth {
Some(json!({ "kind": "unconstrained" }))
} else if !blocked && auth_profile_ref.is_some() {
security_alternative_index
.and_then(|index| candidate.security_requirements.alternatives.get(index))
.and_then(|alternative| {
(alternative.schemes.len() == 1).then(|| &alternative.schemes[0])
})
.and_then(|scheme_name| candidate.security_schemes.get(scheme_name))
.and_then(|scheme| match &scheme.kind {
crank_import::rest::NormalizedSecuritySchemeKind::Http { scheme, .. } => {
match scheme.to_ascii_lowercase().as_str() {
"bearer" => Some(json!({ "kind": "bearer" })),
"basic" => Some(json!({ "kind": "basic" })),
_ => None,
}
}
crank_import::rest::NormalizedSecuritySchemeKind::ApiKey {
location: crank_import::rest::SecurityParameterLocation::Header,
parameter_name,
..
} => {
Some(json!({ "kind": "api_key_header", "parameter_name": parameter_name }))
}
crank_import::rest::NormalizedSecuritySchemeKind::ApiKey {
location: crank_import::rest::SecurityParameterLocation::Query,
parameter_name,
..
} => Some(json!({ "kind": "api_key_query", "parameter_name": parameter_name })),
_ => None,
})
} else {
None
};
if blocked {
return Ok(PlannedCandidate {
key: candidate.key.clone(),
name: candidate_name,
blocked: true,
reason: blocker_reason,
action: action.to_owned(),
target_operation_id,
confirmed_name,
auth_profile_id,
security_alternative_index,
auth_requirement,
auth_snapshot: None,
target,
operation: None,
});
}
if action == "skip" {
return Ok(PlannedCandidate {
key: candidate.key.clone(),
name: candidate_name,
blocked: false,
reason: None,
action: action.to_owned(),
target_operation_id,
confirmed_name,
auth_profile_id,
security_alternative_index,
auth_requirement: None,
auth_snapshot: None,
target,
operation: None,
});
}
let mut draft = operation_draft_from_candidate(candidate, server_url);
if action == "rename" {
draft.name = confirmed_name
.clone()
.expect("rename decisions carry the exact confirmed_name");
}
attach_import_findings(&mut draft, candidate);
let operation = self.new_operation_snapshot(OperationPayload {
name: draft.name.clone(),
display_name: draft.display_name.clone(),
category: draft.category,
protocol: Protocol::Rest,
security_level: OperationSecurityLevel::Standard,
target: crank_core::Target::Rest(draft.target),
input_schema: draft.input_schema,
output_schema: draft.output_schema,
input_mapping: draft.input_mapping,
output_mapping: draft.output_mapping,
execution_config: ExecutionConfig {
timeout_ms: 10_000,
retry_policy: None,
response_cache: None,
idempotency: None,
safety: None,
approval_policy: None,
auth_profile_ref,
headers: BTreeMap::new(),
},
tool_description: draft.tool_description,
wizard_state: draft.wizard_state,
})?;
// The same workspace/auth secret validator the operation creation
// path uses: the referenced profile and its active secret refs must
// resolve in this workspace before the plan is accepted.
self.validate_registry_operation_in_workspace(workspace_id, &operation)
.await?;
let mut operation = operation;
if action == "new_version" {
let target_id = target_operation_id
.clone()
.expect("new_version decisions carry target_operation_id");
operation.id = OperationId::new(target_id);
operation.version = next_version.expect("new_version computes the next Draft version");
}
let auth_snapshot = match operation.execution_config.auth_profile_ref.as_ref() {
Some(profile_id) => Some(self.import_auth_snapshot(workspace_id, profile_id).await?),
None => None,
};
Ok(PlannedCandidate {
key: candidate.key.clone(),
name: draft.name,
blocked: false,
reason: None,
action: action.to_owned(),
target_operation_id,
confirmed_name,
auth_profile_id,
security_alternative_index,
auth_requirement,
auth_snapshot,
target,
operation: Some(operation),
})
}
/// Captures only profile configuration and secret metadata. Credential
/// values never enter the plan; Apply compares this snapshot under locks.
async fn import_auth_snapshot(
&self,
workspace_id: &WorkspaceId,
profile_id: &AuthProfileId,
) -> Result<Value, ApiError> {
let unavailable = || {
ApiError::unprocessable_with_context(
"The selected authentication profile is unavailable for this import.",
json!({ "error_code": "import_plan_auth_unavailable" }),
)
};
let profile = self
.registry
.get_auth_profile(workspace_id, profile_id)
.await?
.ok_or_else(unavailable)?;
let mut secret_ids: Vec<String> = profile
.config
.secret_ids()
.into_iter()
.map(|id| id.as_str().to_owned())
.collect();
secret_ids.sort();
secret_ids.dedup();
let mut secrets = Vec::with_capacity(secret_ids.len());
for id in secret_ids {
let secret = self
.registry
.get_secret(workspace_id, &crank_core::SecretId::new(id.clone()))
.await?
.ok_or_else(unavailable)?
.secret;
secrets.push(json!({
"id": id,
"status": secret.status,
"current_version": secret.current_version,
"updated_at": secret.updated_at.format(&Rfc3339)
.map_err(|error| ApiError::internal(error.to_string()))?,
}));
}
Ok(json!({
"profile_id": profile_id.as_str(),
"name": profile.name,
"kind": profile.kind,
"config": profile.config,
"updated_at": profile.updated_at.format(&Rfc3339)
.map_err(|error| ApiError::internal(error.to_string()))?,
"secrets": secrets,
}))
}
}
struct PlannedCandidate {
key: String,
name: String,
blocked: bool,
reason: Option<String>,
action: String,
target_operation_id: Option<String>,
confirmed_name: Option<String>,
auth_profile_id: Option<String>,
security_alternative_index: Option<usize>,
auth_requirement: Option<Value>,
auth_snapshot: Option<Value>,
target: Option<Value>,
operation: Option<RegistryOperation>,
}
pub(super) fn import_plan_repreview_error(
locale: OpenApiUploadLocale,
error_code: &'static str,
) -> ApiError {
let message = match locale {
OpenApiUploadLocale::Ru => {
"не удалось повторно проверить план импорта; создайте новый preview"
}
OpenApiUploadLocale::En => "import plan revalidation failed; create a fresh preview",
};
ApiError::conflict_with_context(
message,
json!({
"error_code": error_code,
"recovery": "repreview_required",
"repreview_required": true
}),
)
}
/// Closes the selection against the current preview: `full` keeps every
/// candidate (an explicit list must equal the whole candidate set), `partial`
/// requires a non-empty exact subset. Unknown or duplicate keys are rejected
/// before any plan material exists.
fn resolve_plan_selection(
selection_mode: &str,
requested: &[String],
all: &BTreeSet<String>,
) -> Result<BTreeSet<String>, ApiError> {
if !matches!(selection_mode, "full" | "partial") {
return Err(ApiError::validation_with_context(
"selection_mode must be full or partial",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
if requested.len() > MAX_IMPORT_PLAN_KEYS {
return Err(ApiError::validation_with_context(
"too many selected_operation_keys for this import plan",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
for key in requested {
if key.is_empty() || key.len() > MAX_IMPORT_PLAN_KEY_BYTES {
return Err(ApiError::validation_with_context(
"selected_operation_keys entries are empty or too long",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
}
let requested_set: BTreeSet<&String> = requested.iter().collect();
if requested_set.len() != requested.len() {
return Err(ApiError::validation_with_context(
"selected_operation_keys contains duplicates",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
let all_set: BTreeSet<&String> = all.iter().collect();
match selection_mode {
"full" => {
if !requested_set.is_empty() && requested_set != all_set {
return Err(ApiError::validation_with_context(
"full selection covers the entire candidate set; selected_operation_keys does not match the preview",
json!({ "error_code": "import_plan_selection_mismatch" }),
));
}
Ok(all.clone())
}
_ => {
if requested_set.is_empty() {
return Err(ApiError::validation_with_context(
"partial selection requires at least one selected_operation_key",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
if !requested_set.is_subset(&all_set) {
return Err(ApiError::validation_with_context(
"selected_operation_keys reference operations absent from the preview",
json!({ "error_code": "import_plan_unknown_operation_key" }),
));
}
Ok(requested.iter().cloned().collect())
}
}
}
async fn resolve_security_binding(
service: &AdminService,
workspace_id: &WorkspaceId,
candidate: &ImportOperationCandidate,
profile_ref: Option<&AuthProfileId>,
requested_index: Option<usize>,
blocker_reason: &mut Option<String>,
) -> Result<Option<usize>, ApiError> {
let alternatives = &candidate.security_requirements.alternatives;
if alternatives.is_empty() {
if profile_ref.is_some() || requested_index.is_some() {
return Err(ApiError::validation_with_context(
"security binding was supplied for an operation with no security requirement",
json!({ "operation_key": candidate.key, "error_code": "import_plan_auth_incompatible" }),
));
}
return Ok(None);
}
let public_index = alternatives
.iter()
.position(|alternative| alternative.supported && alternative.schemes.is_empty());
let compatible = if let Some(profile_ref) = profile_ref {
let profile = service
.registry
.get_auth_profile(workspace_id, profile_ref)
.await?
.ok_or_else(|| {
ApiError::unprocessable_with_context(
"selected Auth Profile is unavailable in this workspace",
json!({ "error_code": "import_plan_auth_unavailable" }),
)
})?;
let compatible = alternatives
.iter()
.enumerate()
.filter(|(_, alternative)| {
alternative.supported
&& alternative.schemes.len() == 1
&& candidate
.security_schemes
.get(&alternative.schemes[0])
.is_some_and(|scheme| auth_config_matches_scheme(&profile.config, scheme))
})
.map(|(index, _)| index)
.collect::<Vec<_>>();
Some((profile, compatible))
} else {
None
};
if let Some((_, compatible_indices)) = compatible.as_ref() {
let selected = match requested_index {
Some(index) if compatible_indices.contains(&index) => index,
Some(_) => {
return Err(ApiError::validation_with_context(
"selected Auth Profile is incompatible with the selected security alternative",
json!({ "operation_key": candidate.key, "error_code": "import_plan_auth_incompatible" }),
));
}
None if compatible_indices.len() == 1 => compatible_indices[0],
None if compatible_indices.is_empty() => {
return Err(ApiError::validation_with_context(
"selected Auth Profile is incompatible with the source security schemes",
json!({ "operation_key": candidate.key, "error_code": "import_plan_auth_incompatible" }),
));
}
None => {
return Err(ApiError::validation_with_context(
"security_alternative_index is required when a profile matches multiple alternatives",
json!({ "operation_key": candidate.key, "error_code": "import_plan_security_alternative_required" }),
));
}
};
return Ok(Some(selected));
}
if let Some(index) = requested_index {
if alternatives
.get(index)
.is_none_or(|alternative| !alternative.supported)
{
return Err(ApiError::validation_with_context(
"selected security alternative is unsupported",
json!({ "operation_key": candidate.key, "error_code": "import_plan_auth_incompatible" }),
));
}
if alternatives[index].schemes.is_empty() {
return Ok(Some(index));
}
}
if let Some(public_index) = public_index
&& requested_index.is_none()
{
return Ok(Some(public_index));
}
*blocker_reason = Some("auth_profile_required".to_owned());
Ok(requested_index)
}
pub(super) fn auth_config_matches_scheme(
config: &AuthConfig,
scheme: &crank_import::rest::NormalizedSecurityScheme,
) -> bool {
use crank_import::rest::{NormalizedSecuritySchemeKind, SecurityParameterLocation};
match (&scheme.kind, config) {
(NormalizedSecuritySchemeKind::Http { scheme, .. }, AuthConfig::Bearer(_)) => {
scheme.eq_ignore_ascii_case("bearer")
}
(NormalizedSecuritySchemeKind::Http { scheme, .. }, AuthConfig::Basic(_)) => {
scheme.eq_ignore_ascii_case("basic")
}
(
NormalizedSecuritySchemeKind::ApiKey {
location: SecurityParameterLocation::Header,
parameter_name,
..
},
AuthConfig::ApiKeyHeader(config),
) => parameter_name.eq_ignore_ascii_case(&config.header_name),
(
NormalizedSecuritySchemeKind::ApiKey {
location: SecurityParameterLocation::Query,
parameter_name,
..
},
AuthConfig::ApiKeyQuery(config),
) => parameter_name == &config.param_name,
_ => false,
}
}
/// Serializes one planned candidate into the versioned plan payload: the
/// redacted decision, the bounded rejection reason (if any), the exact
/// authorized target with expected state and, for mutating actions, the full
/// server-authored Draft snapshot.
fn plan_candidate_payload(candidate: &PlannedCandidate) -> Result<Value, ApiError> {
let mut object = json!({
"key": candidate.key,
"name": candidate.name,
"state": if candidate.blocked { "blocked" } else { "actionable" },
"decision": {
"action": candidate.action,
"target_operation_id": candidate.target_operation_id,
"confirmed_name": candidate.confirmed_name,
"auth_profile_id": candidate.auth_profile_id,
"security_alternative_index": candidate.security_alternative_index,
},
});
if let Some(reason) = &candidate.reason {
object["reason"] = json!(reason);
}
if let Some(target) = &candidate.target {
object["target"] = target.clone();
}
if let Some(auth_snapshot) = &candidate.auth_snapshot {
object["auth_snapshot"] = auth_snapshot.clone();
}
if let Some(auth_requirement) = &candidate.auth_requirement {
object["auth_requirement"] = auth_requirement.clone();
}
if let Some(operation) = &candidate.operation {
let value = serde_json::to_value(operation)
.map_err(|error| ApiError::internal(error.to_string()))?;
object["operation"] = value;
}
Ok(object)
}
@@ -0,0 +1,128 @@
use super::*;
/// Binds decisions to selected candidates with action-specific field rules:
/// unknown/duplicate keys, foreign fields and oversized references are
/// rejected before the plan is materialized.
pub(super) fn validate_plan_decisions<'input>(
decisions: &'input [OpenApiImportPlanDecision],
selected: &BTreeSet<String>,
) -> Result<BTreeMap<String, &'input OpenApiImportPlanDecision>, ApiError> {
let invalid = |context: Value| {
Err(ApiError::validation_with_context(
"import plan decision is invalid",
context,
))
};
let mut mapping = BTreeMap::new();
for decision in decisions {
if decision.operation_key.is_empty()
|| decision.operation_key.len() > MAX_IMPORT_PLAN_KEY_BYTES
{
return invalid(json!({
"operation_key": decision.operation_key,
"error_code": "import_plan_invalid_input"
}));
}
if !matches!(
decision.action.as_str(),
"create" | "skip" | "rename" | "new_version"
) {
return invalid(json!({
"operation_key": decision.operation_key,
"error_code": "import_plan_invalid_input"
}));
}
validate_decision_fields(decision)?;
if !selected.contains(&decision.operation_key) {
return invalid(json!({
"operation_key": decision.operation_key,
"error_code": "import_plan_decision_unselected"
}));
}
if mapping
.insert(decision.operation_key.clone(), decision)
.is_some()
{
return invalid(json!({
"operation_key": decision.operation_key,
"error_code": "import_plan_invalid_input"
}));
}
}
Ok(mapping)
}
fn validate_decision_fields(decision: &OpenApiImportPlanDecision) -> Result<(), ApiError> {
let context = json!({
"operation_key": decision.operation_key,
"error_code": "import_plan_invalid_input"
});
let invalid = |message: &str| -> Result<(), ApiError> {
Err(ApiError::validation_with_context(message, context.clone()))
};
if decision
.target_operation_id
.as_deref()
.is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_ID_REF_BYTES)
{
return invalid("decision target_operation_id is empty or too long");
}
if decision
.confirmed_name
.as_deref()
.is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_NAME_BYTES)
{
return invalid("decision confirmed_name is empty or too long");
}
if decision
.auth_profile_id
.as_deref()
.is_some_and(|value| value.is_empty() || value.len() > MAX_IMPORT_PLAN_ID_REF_BYTES)
{
return invalid("decision auth_profile_id is empty or too long");
}
if decision
.security_alternative_index
.is_some_and(|index| index > MAX_IMPORT_PLAN_KEYS)
{
return invalid("decision security_alternative_index is too large");
}
match decision.action.as_str() {
"create" => {
if decision.target_operation_id.is_some() || decision.confirmed_name.is_some() {
return invalid(
"target_operation_id and confirmed_name are not allowed for action create",
);
}
}
"skip" => {
if decision.auth_profile_id.is_some() || decision.security_alternative_index.is_some() {
return invalid("security binding is not allowed for action skip");
}
if decision.target_operation_id.is_none() {
return invalid("action skip requires the exact target_operation_id");
}
if decision.confirmed_name.is_some() {
return invalid("confirmed_name is not allowed for action skip");
}
}
"rename" => {
if decision.target_operation_id.is_some() {
return invalid("target_operation_id is not allowed for action rename");
}
if decision.confirmed_name.is_none() {
return invalid("action rename requires the exact confirmed_name");
}
}
"new_version" => {
if decision.target_operation_id.is_none() {
return invalid("action new_version requires the exact target_operation_id");
}
if decision.confirmed_name.is_some() {
return invalid("confirmed_name is not allowed for action new_version");
}
}
_ => unreachable!("decision action is validated before the field rules"),
}
Ok(())
}
@@ -0,0 +1,440 @@
use super::*;
use crank_registry::{ApplyImportPlanRequest, ImportPlanApplyReport};
const MAX_IMPORT_PLAN_IDEMPOTENCY_KEY_BYTES: usize = 128;
impl AdminService {
/// Reads an immutable plan and checks its current authority without Apply mutations.
pub async fn revalidate_openapi_import_plan(
&self,
workspace_id: &WorkspaceId,
plan_id: &ImportPlanId,
) -> Result<OpenApiImportPlanRevalidationResponse, ApiError> {
self.revalidate_openapi_import_plan_with_locale(
workspace_id,
plan_id,
OpenApiUploadLocale::En,
)
.await
}
/// Locale-aware variant used by the HTTP boundary.
pub async fn revalidate_openapi_import_plan_with_locale(
&self,
workspace_id: &WorkspaceId,
plan_id: &ImportPlanId,
locale: OpenApiUploadLocale,
) -> Result<OpenApiImportPlanRevalidationResponse, ApiError> {
self.ensure_workspace_exists(workspace_id).await?;
let plan = self
.registry
.get_import_plan(workspace_id, plan_id)
.await?
.ok_or_else(|| {
ApiError::not_found_with_context(
"import plan was not found in this workspace",
json!({ "error_code": "import_plan_not_found" }),
)
})?;
let mut reason = None;
let now = OffsetDateTime::now_utc();
if plan.expires_at <= now {
reason = Some("import_plan_expired");
} else if let Some(job) = self
.registry
.get_import_job(workspace_id, &plan.job_id)
.await?
{
if job.kind != ImportJobKind::OpenApi
|| job.status != ImportJobStatus::Pending
|| job.expires_at <= now
{
reason = Some("import_plan_job_terminal");
} else {
match self
.resolve_verified_openapi_preview(workspace_id, &job, locale)
.await
{
Ok(resolved) => {
let v2 = plan.payload.get("schema_version").and_then(Value::as_str)
== Some("import-plan-v2");
if self
.read_import_job_dependencies(
workspace_id,
&job.preview_payload,
locale,
)
.await
.is_err()
{
reason = Some("import_dependency_verification_failed");
} else if !v2 {
// Historical plans stay readable for audit, but lack the
// catalog evidence required for current Apply authority.
reason = Some("importer_version_changed");
} else if resolved
.fingerprint
.get("normalizer_version")
.and_then(Value::as_str)
!= Some(NORMALIZER_VERSION)
|| resolved
.fingerprint
.get("projection_version")
.and_then(Value::as_str)
!= Some(PROJECTION_VERSION)
|| plan
.payload
.get("support_matrix_version")
.and_then(Value::as_str)
!= Some(OPENAPI_SUPPORT_MATRIX_VERSION)
{
reason = Some("importer_version_changed");
} else if self
.registry
.revalidate_import_plan(workspace_id, plan_id, &resolved.fingerprint)
.await
.is_err()
{
reason = Some("import_plan_revalidation_failed");
}
}
Err(_) => reason = Some("import_preview_revalidation_failed"),
}
}
} else {
reason = Some("import_plan_job_unavailable");
}
let counts = &plan.payload["counts"];
let count = |key: &str| {
counts
.get(key)
.and_then(Value::as_u64)
.and_then(|value| usize::try_from(value).ok())
.unwrap_or(0)
};
let selected = plan.payload["candidates"]
.as_array()
.into_iter()
.flatten()
.map(|candidate| {
let decision = &candidate["decision"];
let string = |value: &Value| value.as_str().map(str::to_owned);
OpenApiImportPlanCandidateView {
key: string(&candidate["key"]).unwrap_or_default(),
name: string(&candidate["name"]).unwrap_or_default(),
state: string(&candidate["state"]).unwrap_or_default(),
action: string(&decision["action"]),
target_operation_id: string(&decision["target_operation_id"]),
confirmed_name: string(&decision["confirmed_name"]),
auth_profile_id: string(&decision["auth_profile_id"]),
security_alternative_index: decision["security_alternative_index"]
.as_u64()
.and_then(|value| usize::try_from(value).ok()),
reason: string(&candidate["reason"]),
}
});
let excluded = plan
.payload
.pointer("/selection/excluded")
.and_then(Value::as_array)
.into_iter()
.flatten()
.filter_map(Value::as_str)
.map(|key| OpenApiImportPlanCandidateView {
key: key.to_owned(),
name: excluded_candidate_display_name(&plan.payload, key),
state: "excluded".to_owned(),
action: None,
target_operation_id: None,
confirmed_name: None,
auth_profile_id: None,
security_alternative_index: None,
reason: plan.payload["excluded_reasons"]
.as_array()
.and_then(|items| items.iter().find(|item| item["key"].as_str() == Some(key)))
.and_then(|item| item["reason"].as_str())
.map(str::to_owned)
.or_else(|| Some("not_selected".to_owned())),
});
Ok(OpenApiImportPlanRevalidationResponse {
plan_reference: plan.id.as_str().to_owned(),
plan_digest: plan.digest,
revalidation_status: if reason.is_some() { "stale" } else { "current" }.to_owned(),
revalidation_required: reason.is_some(),
reason: reason.map(str::to_owned),
counts: OpenApiImportPlanCounts {
selected: count("selected"),
excluded: count("excluded"),
actionable: count("actionable"),
blocked: count("blocked"),
},
candidates: selected.chain(excluded).collect(),
})
}
pub async fn apply_openapi_import_plan(
&self,
workspace_id: &WorkspaceId,
plan_id: &ImportPlanId,
payload: OpenApiImportPlanApplyPayload,
) -> Result<ImportPlanApplyReport, ApiError> {
self.apply_openapi_import_plan_with_locale(
workspace_id,
plan_id,
payload,
OpenApiUploadLocale::En,
)
.await
}
#[instrument(skip(self, payload), fields(workspace_id = %workspace_id.as_str(), plan_id = %plan_id.as_str()))]
pub async fn apply_openapi_import_plan_with_locale(
&self,
workspace_id: &WorkspaceId,
plan_id: &ImportPlanId,
payload: OpenApiImportPlanApplyPayload,
locale: OpenApiUploadLocale,
) -> Result<ImportPlanApplyReport, ApiError> {
self.ensure_workspace_exists(workspace_id).await?;
validate_apply_payload(&payload)?;
// The replay row is deliberately checked before the plan or job.
// Its report remains authoritative after normal TTL cleanup removes
// those source rows.
if let Some(application) = self
.registry
.get_import_plan_application(workspace_id, &payload.idempotency_key)
.await?
{
if application.plan_digest != payload.plan_digest {
return Err(key_digest_conflict(locale));
}
return Ok(application.result.report);
}
let plan = self
.registry
.get_import_plan(workspace_id, plan_id)
.await?
.ok_or_else(|| {
ApiError::not_found_with_context(
"import plan was not found in this workspace",
json!({ "error_code": "import_plan_not_found" }),
)
})?;
if plan.digest != payload.plan_digest {
return Err(import_plan_repreview_error(
locale,
"import_plan_digest_mismatch",
));
}
let now = OffsetDateTime::now_utc();
if plan.expires_at <= now {
return Err(import_plan_repreview_error(locale, "import_plan_expired"));
}
let job = self
.registry
.get_import_job(workspace_id, &plan.job_id)
.await?
.ok_or_else(|| import_plan_repreview_error(locale, "import_plan_job_unavailable"))?;
if job.kind != ImportJobKind::OpenApi {
return Err(import_plan_repreview_error(
locale,
"import_plan_job_kind_mismatch",
));
}
if job.status != ImportJobStatus::Pending || job.expires_at <= now {
return Err(import_plan_repreview_error(
locale,
"import_plan_job_terminal",
));
}
let resolved = self
.resolve_verified_openapi_preview(workspace_id, &job, locale)
.await
.map_err(|resolution| match resolution {
ImportPreviewResolution::Fatal(error_code, _) => {
import_plan_repreview_error(locale, error_code)
}
ImportPreviewResolution::NonFatal(_) => {
import_plan_repreview_error(locale, "import_preview_revalidation_failed")
}
})?;
// Applying a new plan requires the current normalizer/projection
// contract. Historic jobs remain available to the legacy replay path,
// but a plan created from a historic projection must be previewed
// again before it can authorize mutations.
if resolved
.fingerprint
.get("normalizer_version")
.and_then(Value::as_str)
!= Some(NORMALIZER_VERSION)
|| resolved
.fingerprint
.get("projection_version")
.and_then(Value::as_str)
!= Some(PROJECTION_VERSION)
|| (plan.payload.get("schema_version").and_then(Value::as_str)
== Some("import-plan-v2")
&& plan
.payload
.get("support_matrix_version")
.and_then(Value::as_str)
!= Some(OPENAPI_SUPPORT_MATRIX_VERSION))
{
return Err(import_plan_repreview_error(
locale,
"importer_version_changed",
));
}
// Verify every persisted external snapshot again without making a
// network request. The registry repeats source/dependency checks
// under its transaction before it mutates operations.
self.read_import_job_dependencies(workspace_id, &job.preview_payload, locale)
.await
.map_err(|_| {
import_plan_repreview_error(locale, "import_dependency_verification_failed")
})?;
let result = self
.registry
.apply_import_plan(&ApplyImportPlanRequest {
workspace_id,
plan_id,
plan_digest: &payload.plan_digest,
idempotency_key: &payload.idempotency_key,
verified_fingerprint: &resolved.fingerprint,
applied_at: &now,
})
.await
.map_err(|error| map_apply_registry_error(locale, error))?;
Ok(result.report)
}
}
fn excluded_candidate_display_name(plan: &Value, key: &str) -> String {
plan["excluded_reasons"]
.as_array()
.and_then(|items| items.iter().find(|item| item["key"].as_str() == Some(key)))
.and_then(|item| item["name"].as_str())
.filter(|name| !name.is_empty())
.unwrap_or(key)
.to_owned()
}
fn validate_apply_payload(payload: &OpenApiImportPlanApplyPayload) -> Result<(), ApiError> {
let digest_valid = payload.plan_digest.len() == 64
&& payload
.plan_digest
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte));
if !digest_valid {
return Err(ApiError::validation_with_context(
"plan_digest must be 64 lowercase hexadecimal characters",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
if !(1..=MAX_IMPORT_PLAN_IDEMPOTENCY_KEY_BYTES).contains(&payload.idempotency_key.len())
|| payload.idempotency_key.trim() != payload.idempotency_key
|| payload.idempotency_key.chars().any(char::is_control)
{
return Err(ApiError::validation_with_context(
"idempotency_key must be a non-empty bounded printable value",
json!({ "error_code": "import_plan_invalid_input" }),
));
}
Ok(())
}
fn map_apply_registry_error(locale: OpenApiUploadLocale, error: RegistryError) -> ApiError {
match error {
RegistryError::ImportPlanNotFound { .. } => ApiError::not_found_with_context(
"import plan was not found in this workspace",
json!({ "error_code": "import_plan_not_found" }),
),
RegistryError::ImportPlanExpired { .. } => {
import_plan_repreview_error(locale, "import_plan_expired")
}
RegistryError::ImportPlanPayloadCorrupt { .. } => {
import_plan_repreview_error(locale, "import_plan_payload_invalid")
}
RegistryError::ImportPlanFingerprintStale { .. } => {
import_plan_repreview_error(locale, "import_plan_fingerprint_stale")
}
RegistryError::ImportPlanKeyDigestConflict { .. } => key_digest_conflict(locale),
RegistryError::ImportPlanNameConflict { .. } => {
let message = match locale {
OpenApiUploadLocale::Ru => "имя операции изменилось после создания плана",
OpenApiUploadLocale::En => "an operation name changed after the plan was created",
};
ApiError::conflict_with_context(
message,
json!({
"error_code": "import_plan_name_conflict",
"recovery": "confirm_skip_rename_or_new_version"
}),
)
}
RegistryError::ImportPlanTargetStale { .. } => {
import_plan_repreview_error(locale, "import_plan_target_stale")
}
RegistryError::ImportPlanAuthUnavailable { .. } => {
import_plan_repreview_error(locale, "import_plan_auth_unavailable")
}
other => ApiError::from(other),
}
}
fn key_digest_conflict(locale: OpenApiUploadLocale) -> ApiError {
let message = match locale {
OpenApiUploadLocale::Ru => {
"ключ идемпотентности уже зафиксирован для другого материала плана; создайте новый preview"
}
OpenApiUploadLocale::En => {
"idempotency key was already committed for different plan material"
}
};
ApiError::conflict_with_context(
message,
json!({
"error_code": "import_plan_key_digest_conflict",
"recovery": "repreview_required",
"repreview_required": true
}),
)
}
#[cfg(test)]
mod tests {
use super::excluded_candidate_display_name;
use serde_json::json;
#[test]
fn excluded_candidate_name_uses_persisted_display_name_and_legacy_key_fallback() {
let current = json!({
"excluded_reasons": [{
"key": "GET /alpha",
"name": "Alpha display label",
"reason": "not_selected"
}]
});
assert_eq!(
excluded_candidate_display_name(&current, "GET /alpha"),
"Alpha display label"
);
let historic = json!({
"excluded_reasons": [{ "key": "GET /alpha", "reason": "not_selected" }]
});
assert_eq!(
excluded_candidate_display_name(&historic, "GET /alpha"),
"GET /alpha"
);
}
}
@@ -1,195 +0,0 @@
use super::*;
use crate::service::{OpenApiAuthProfileChoice, OpenApiAuthProfileOption};
use crank_core::{AuthConfig, AuthProfile, AuthProfileId};
impl AdminService {
pub(super) async fn openapi_auth_profile_choices(
&self,
workspace_id: &WorkspaceId,
preview: &crank_import::rest::ImportPreview,
) -> Result<Vec<OpenApiAuthProfileChoice>, ApiError> {
let mut profiles = self
.registry
.list_auth_profiles(workspace_id)
.await?
.into_iter()
.filter(|profile| profile.kind == profile.config.kind())
.collect::<Vec<_>>();
let mut available_profiles = Vec::with_capacity(profiles.len());
for profile in profiles.drain(..) {
if auth_profile_is_available(&self.registry, workspace_id, &profile).await? {
available_profiles.push(profile);
}
}
let mut choices = Vec::new();
for operation in preview
.groups
.iter()
.flat_map(|group| group.operations.iter())
{
for (alternative_index, alternative) in operation
.security_requirements
.alternatives
.iter()
.enumerate()
{
let scheme = (alternative.schemes.len() == 1)
.then(|| operation.security_schemes.get(&alternative.schemes[0]))
.flatten();
let requirement = scheme.and_then(import_auth_requirement);
let supported = alternative.supported
&& (alternative.schemes.is_empty() || requirement.is_some());
let options = requirement
.as_ref()
.map(|requirement| {
available_profiles
.iter()
.filter(|profile| auth_profile_matches(profile, requirement))
.map(|profile| OpenApiAuthProfileOption {
id: profile.id.as_str().to_owned(),
name: profile.name.clone(),
kind: profile.kind,
})
.collect()
})
.unwrap_or_default();
choices.push(OpenApiAuthProfileChoice {
operation_key: operation.key.clone(),
alternative_index,
scheme_names: alternative.schemes.clone(),
supported,
profiles: options,
});
}
}
Ok(choices)
}
pub(super) async fn resolve_openapi_auth_binding(
&self,
workspace_id: &WorkspaceId,
candidate: &ImportOperationCandidate,
mapping: Option<&OpenApiAuthMapping>,
locale: OpenApiUploadLocale,
) -> Result<(Option<AuthProfileId>, Option<ImportAuthRequirement>), ApiError> {
let alternatives = &candidate.security_requirements.alternatives;
if alternatives.is_empty() {
return if mapping.is_none() {
Ok((None, None))
} else {
Err(ApiError::openapi_upload(locale, "auth_mapping_invalid"))
};
}
let mapping =
mapping.ok_or_else(|| ApiError::openapi_upload(locale, "auth_mapping_required"))?;
let alternative = alternatives
.get(mapping.alternative_index)
.ok_or_else(|| ApiError::openapi_upload(locale, "auth_mapping_invalid"))?;
if !alternative.supported {
return Err(ApiError::openapi_upload(locale, "auth_mapping_unsupported"));
}
if alternative.schemes.is_empty() {
return if mapping.auth_profile_id.is_none() {
Ok((None, None))
} else {
Err(ApiError::openapi_upload(locale, "auth_mapping_invalid"))
};
}
if alternative.schemes.len() != 1 {
return Err(ApiError::openapi_upload(locale, "auth_mapping_unsupported"));
}
let scheme = candidate
.security_schemes
.get(&alternative.schemes[0])
.ok_or_else(|| ApiError::openapi_upload(locale, "auth_mapping_unsupported"))?;
let requirement = import_auth_requirement(scheme)
.ok_or_else(|| ApiError::openapi_upload(locale, "auth_mapping_unsupported"))?;
let profile_id = mapping
.auth_profile_id
.as_deref()
.filter(|value| !value.is_empty())
.ok_or_else(|| ApiError::openapi_upload(locale, "auth_mapping_required"))?;
let profile_id = AuthProfileId::new(profile_id.to_owned());
let profile = self
.registry
.get_auth_profile(workspace_id, &profile_id)
.await?
.ok_or_else(|| ApiError::openapi_auth_binding_unavailable(locale))?;
if !auth_profile_matches(&profile, &requirement)
|| !auth_profile_is_available(&self.registry, workspace_id, &profile).await?
{
return Err(ApiError::openapi_auth_binding_unavailable(locale));
}
Ok((Some(profile_id), Some(requirement)))
}
}
fn import_auth_requirement(
scheme: &crank_import::rest::NormalizedSecurityScheme,
) -> Option<ImportAuthRequirement> {
use crank_import::rest::{NormalizedSecuritySchemeKind, SecurityParameterLocation};
match &scheme.kind {
NormalizedSecuritySchemeKind::Http { scheme, .. }
if scheme.eq_ignore_ascii_case("bearer") =>
{
Some(ImportAuthRequirement::Bearer)
}
NormalizedSecuritySchemeKind::Http { scheme, .. }
if scheme.eq_ignore_ascii_case("basic") =>
{
Some(ImportAuthRequirement::Basic)
}
NormalizedSecuritySchemeKind::ApiKey {
location: SecurityParameterLocation::Header,
parameter_name,
..
} => Some(ImportAuthRequirement::ApiKeyHeader {
parameter_name: parameter_name.clone(),
}),
NormalizedSecuritySchemeKind::ApiKey {
location: SecurityParameterLocation::Query,
parameter_name,
..
} => Some(ImportAuthRequirement::ApiKeyQuery {
parameter_name: parameter_name.clone(),
}),
_ => None,
}
}
fn auth_profile_matches(profile: &AuthProfile, requirement: &ImportAuthRequirement) -> bool {
if profile.kind != profile.config.kind() {
return false;
}
match (requirement, &profile.config) {
(ImportAuthRequirement::Bearer, AuthConfig::Bearer(_))
| (ImportAuthRequirement::Basic, AuthConfig::Basic(_)) => true,
(
ImportAuthRequirement::ApiKeyHeader { parameter_name },
AuthConfig::ApiKeyHeader(config),
) => config.header_name.eq_ignore_ascii_case(parameter_name),
(
ImportAuthRequirement::ApiKeyQuery { parameter_name },
AuthConfig::ApiKeyQuery(config),
) => config.param_name == *parameter_name,
_ => false,
}
}
async fn auth_profile_is_available(
registry: &crank_registry::PostgresRegistry,
workspace_id: &WorkspaceId,
profile: &AuthProfile,
) -> Result<bool, ApiError> {
for secret_id in profile.config.secret_ids() {
if registry
.get_current_secret_version(workspace_id, secret_id)
.await?
.is_none()
{
return Ok(false);
}
}
Ok(true)
}
@@ -0,0 +1,401 @@
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")
) {
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(),
))
})
}
+153 -15
View File
@@ -1,8 +1,10 @@
use crank_core::{
OnboardingProjection, OnboardingStepId, ProductEventId, ProductEventKind, WorkspaceId,
OnboardingProjection, OnboardingStepId, OperationId, ProductEventId, ProductEventKind,
WorkspaceId,
};
use crank_registry::{
OnboardingPresentationMilestone, RecordOnboardingMilestoneRequest, RegistryError,
OnboardingImportContext, OnboardingPresentationMilestone, RecordOnboardingMilestoneRequest,
RegisterOnboardingImportContextRequest, RegistryError, SelectOnboardingImportDraftRequest,
};
use serde_json::json;
use time::OffsetDateTime;
@@ -11,7 +13,10 @@ use crate::{
error::ApiError,
service::{
AdminService, OnboardingEventPayload, OnboardingEventResponse, OnboardingFirstCallEvidence,
OnboardingResponse, OnboardingStepView, ResetOnboardingSelectionResponse, format_timestamp,
OnboardingImportChoiceView, OnboardingImportContextView, OnboardingImportDriftView,
OnboardingResponse, OnboardingStepView, RegisterOnboardingImportContextPayload,
RegisterOnboardingImportContextResponse, ResetOnboardingSelectionResponse,
SelectOnboardingImportDraftPayload, SelectOnboardingImportDraftResponse, format_timestamp,
new_prefixed_id,
},
};
@@ -22,11 +27,12 @@ impl AdminService {
workspace_id: &WorkspaceId,
) -> Result<OnboardingResponse, ApiError> {
self.ensure_workspace_exists(workspace_id).await?;
let projection = self
let snapshot = self
.registry
.ensure_onboarding_eligibility(workspace_id, OffsetDateTime::now_utc())
.ensure_onboarding_eligibility_snapshot(workspace_id, OffsetDateTime::now_utc())
.await?;
self.map_onboarding_response(projection).await
self.map_onboarding_response(snapshot.projection, snapshot.import_context)
.await
}
pub async fn record_onboarding_event(
@@ -67,13 +73,12 @@ impl AdminService {
};
// Presentation events must never exist outside the server-owned cohort,
// including a direct API call before the first UI snapshot GET.
let current = self
.registry
.ensure_onboarding_eligibility(workspace_id, OffsetDateTime::now_utc())
self.registry
.ensure_onboarding_eligibility_snapshot(workspace_id, OffsetDateTime::now_utc())
.await?;
let outcome = self
.registry
.record_onboarding_milestone(RecordOnboardingMilestoneRequest {
.record_onboarding_milestone_snapshot(RecordOnboardingMilestoneRequest {
workspace_id,
event_id: &ProductEventId::new(new_prefixed_id("pe")),
milestone,
@@ -94,9 +99,18 @@ impl AdminService {
.as_ref()
.is_some_and(|record| record.event.kind == event_kind)
{
let latest = self
.registry
.ensure_onboarding_eligibility_snapshot(
workspace_id,
OffsetDateTime::now_utc(),
)
.await?;
return Ok(OnboardingEventResponse {
accepted: false,
onboarding: self.map_onboarding_response(current).await?,
onboarding: self
.map_onboarding_response(latest.projection, latest.import_context)
.await?,
});
}
if replay.is_some() {
@@ -122,7 +136,12 @@ impl AdminService {
};
Ok(OnboardingEventResponse {
accepted: outcome.accepted,
onboarding: self.map_onboarding_response(outcome.projection).await?,
onboarding: self
.map_onboarding_response(
outcome.snapshot.projection,
outcome.snapshot.import_context,
)
.await?,
})
}
@@ -132,9 +151,13 @@ impl AdminService {
expected_revision: i64,
) -> Result<ResetOnboardingSelectionResponse, ApiError> {
self.ensure_workspace_exists(workspace_id).await?;
let projection = self
let snapshot = self
.registry
.reset_onboarding_selection(workspace_id, expected_revision, OffsetDateTime::now_utc())
.reset_onboarding_selection_snapshot(
workspace_id,
expected_revision,
OffsetDateTime::now_utc(),
)
.await
.map_err(|error| match error {
RegistryError::OnboardingStaleRevision => ApiError::conflict_with_context(
@@ -145,13 +168,76 @@ impl AdminService {
})?;
Ok(ResetOnboardingSelectionResponse {
selection_reset: true,
onboarding: self.map_onboarding_response(projection).await?,
onboarding: self
.map_onboarding_response(snapshot.projection, snapshot.import_context)
.await?,
})
}
pub async fn register_onboarding_import_context(
&self,
workspace_id: &WorkspaceId,
payload: RegisterOnboardingImportContextPayload,
) -> Result<RegisterOnboardingImportContextResponse, ApiError> {
self.ensure_workspace_exists(workspace_id).await?;
validate_application_identity(&payload.application_idempotency_key, &payload.plan_digest)?;
let snapshot = self
.registry
.register_onboarding_import_context_snapshot(RegisterOnboardingImportContextRequest {
workspace_id,
application_idempotency_key: &payload.application_idempotency_key,
plan_digest: &payload.plan_digest,
expected_revision: payload.expected_revision,
occurred_at: OffsetDateTime::now_utc(),
})
.await?;
Ok(RegisterOnboardingImportContextResponse {
registered: true,
onboarding: self
.map_onboarding_response(snapshot.projection, snapshot.import_context)
.await?,
})
}
pub async fn select_onboarding_import_draft(
&self,
workspace_id: &WorkspaceId,
payload: SelectOnboardingImportDraftPayload,
) -> Result<SelectOnboardingImportDraftResponse, ApiError> {
self.ensure_workspace_exists(workspace_id).await?;
validate_application_identity(&payload.application_idempotency_key, &payload.plan_digest)?;
if payload.operation_id.is_empty() || payload.operation_id.len() > 128 {
return Err(ApiError::validation(
"operation_id must contain 1..128 bytes",
));
}
if payload.operation_version == 0 {
return Err(ApiError::validation("operation_version must be positive"));
}
let snapshot = self
.registry
.select_onboarding_import_draft_snapshot(SelectOnboardingImportDraftRequest {
workspace_id,
application_idempotency_key: &payload.application_idempotency_key,
plan_digest: &payload.plan_digest,
operation_id: &OperationId::new(payload.operation_id),
operation_version: payload.operation_version,
expected_revision: payload.expected_revision,
occurred_at: OffsetDateTime::now_utc(),
})
.await?;
Ok(SelectOnboardingImportDraftResponse {
selected: true,
onboarding: self
.map_onboarding_response(snapshot.projection, snapshot.import_context)
.await?,
})
}
async fn map_onboarding_response(
&self,
projection: OnboardingProjection,
import_context: Option<OnboardingImportContext>,
) -> Result<OnboardingResponse, ApiError> {
let endpoint = if let Some(agent_id) = projection.agent_id.as_ref() {
let workspace = self.get_workspace(&projection.workspace_id).await?;
@@ -195,6 +281,7 @@ impl AdminService {
_ => None,
};
let first_incomplete = projection.steps.iter().position(|step| !step.completed);
let import_context = import_context.map(map_import_context);
Ok(OnboardingResponse {
schema_version: 1,
workspace_id: projection.workspace_id.as_str().to_owned(),
@@ -244,10 +331,61 @@ impl AdminService {
.map(|id| id.as_str().to_owned()),
mcp_endpoint: endpoint,
first_call,
import_context,
})
}
}
fn map_import_context(context: OnboardingImportContext) -> OnboardingImportContextView {
OnboardingImportContextView {
application_idempotency_key: context.application_idempotency_key,
plan_digest: context.plan_digest,
report: context.report,
choices: context
.choices
.into_iter()
.map(|choice| OnboardingImportChoiceView {
key: choice.key,
name: choice.name,
outcome: choice.outcome,
operation_id: choice.operation_id,
version: choice.version,
reason: choice.reason,
selectable: choice.selectable,
})
.collect(),
selected_operation_id: context
.selected_operation_id
.map(|id| id.as_str().to_owned()),
selected_operation_version: context.selected_operation_version,
drift: context.drift.map(|drift| OnboardingImportDriftView {
reason: drift.reason,
current_operation_version: drift.current_operation_version,
}),
}
}
fn validate_application_identity(
application_idempotency_key: &str,
plan_digest: &str,
) -> Result<(), ApiError> {
if application_idempotency_key.is_empty() || application_idempotency_key.len() > 128 {
return Err(ApiError::validation(
"application_idempotency_key must contain 1..128 bytes",
));
}
let valid_digest = plan_digest.len() == 64
&& plan_digest
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte));
if !valid_digest {
return Err(ApiError::validation(
"plan_digest must be 64 lowercase hex characters",
));
}
Ok(())
}
fn action_code(step: OnboardingStepId) -> &'static str {
match step {
OnboardingStepId::Operation => "create_operation",