//! ATDD (RED) Story 3.7 — «Публиковать и привязывать static Resource Versions»: первый срез. //! //! Источники: live Gitea #14 (`STORY37-SOURCE.md`, 6 AC), canonical `tickets.toml` entry 7 //! (lines 174–232), QA baseline `_bmad-output/test-artifacts/test-design-epic-3.md:97` //! (3.7-INT-A/B, risk E3-R3), `docs/acceptance-test-plan.md:1032–1037` (AT-3.7-01…06) и //! TL interface decisions (`.tmp/t_8c38b75f/STORY37-NEXT.md` §2–§5). //! //! Границы среза: AC01 (preview controls), AC02 (publication validation), AC03 (immutable //! Published Version) и API/registry часть AC06. AC04 (typed Agent binding, atomic Agent //! publication, `catalog_revision`), AC05 (lifecycle UI + RU/EN), archive и stale Agent //! revision остаются обязательным остатком Story 3.7 и здесь не проверяются. //! //! Фаза ATDD, production-код не изменяется. Целевой контракт публикации пока отсутствует, //! поэтому RED-тесты падают на реальном HTTP-ответе (404 fallback-роутера там, где контракт //! требует 200/400/403/422/428), а не на ошибке компиляции, SQL-отношения или setup. //! Позитивные контроли держат уже принятое поведение create/update/preview/download. //! //! Фильтр запуска: `cargo test -p admin-api --test integration --locked story37_ -- --test-threads=1`. #![allow(dead_code)] mod contract; mod immutable_version; mod policy; mod preview_controls; mod validation; use std::path::{Path, PathBuf}; use crank_registry::PostgresRegistry; use reqwest::StatusCode; use serde_json::{Value, json}; use super::super::common::{ TestServer, authorized_client, build_test_app, spawn_admin_api, test_registry, test_storage_root, }; use super::helpers::{ create_draft, created_resource_id, draft_form, draft_updated_at, error_signature, get_card, read_response, }; // --------------------------------------------------------------------------- // Стенд с наблюдаемым артефактным хранилищем // --------------------------------------------------------------------------- /// Тот же стенд, что `helpers::spawn_authorized`, но корень артефактного хранилища остаётся /// известен тесту: AC02 требует независимой проверки artifact digest/integrity, а не доверия /// ответу API. pub(super) async fn spawn_with_storage( storage_name: &str, ) -> (PostgresRegistry, TestServer, reqwest::Client, PathBuf) { let registry = test_registry().await; let storage_root = test_storage_root(storage_name); let app = build_test_app(registry.clone(), storage_root.clone()); let server = spawn_admin_api(app).await; let client = authorized_client(&server).await; (registry, server, client, storage_root) } // --------------------------------------------------------------------------- // Контракт публикации: publish и exact Published Version // --------------------------------------------------------------------------- /// Тело запроса публикации: `expected_updated_at` — точное значение карточки Draft /// (TL interface decision 2), тот же CAS, что у существующего PUT. pub(super) fn publish_body(expected_updated_at: &str) -> Value { json!({ "expected_updated_at": expected_updated_at }) } /// POST `.../resources/{resource_id}/publish` с произвольным телом (нужен для негатива /// «precondition отсутствует»). pub(super) async fn publish_raw( client: &reqwest::Client, server: impl AsRef, resource_id: &str, body: &Value, ) -> (StatusCode, String, Value) { let server = server.as_ref(); read_response( client .post(format!("{server}/resources/{resource_id}/publish")) .json(body) .send() .await .expect("publish request must complete"), ) .await } /// POST `.../resources/{resource_id}/publish` с точным precondition карточки. pub(super) async fn publish( client: &reqwest::Client, server: impl AsRef, resource_id: &str, expected_updated_at: &str, ) -> (StatusCode, String, Value) { publish_raw( client, server, resource_id, &publish_body(expected_updated_at), ) .await } /// GET `.../resources/{resource_id}/versions/{version}`: метаданные immutable версии. pub(super) async fn read_version( client: &reqwest::Client, server: impl AsRef, resource_id: &str, version: u32, ) -> (StatusCode, String, Value) { let server = server.as_ref(); read_response( client .get(format!( "{server}/resources/{resource_id}/versions/{version}" )) .send() .await .expect("version metadata request must complete"), ) .await } /// GET `.../resources/{resource_id}/versions/{version}/content`: ответ нужен целиком, потому /// что проверяются и точные bytes, и inert download policy (TL decision 3). pub(super) async fn read_version_content( client: &reqwest::Client, server: impl AsRef, resource_id: &str, version: u32, ) -> reqwest::Response { let server = server.as_ref(); client .get(format!( "{server}/resources/{resource_id}/versions/{version}/content" )) .send() .await .expect("version content request must complete") } /// `published_version` из успешного ответа публикации: отсутствие объекта — уже нарушение /// контракта, поэтому паника называет фактическое тело. pub(super) fn published_metadata(body: &Value) -> Value { body.get("published_version") .cloned() .filter(Value::is_object) .unwrap_or_else(|| { panic!( "a successful publish must answer `{{\"resource\": ..., \"published_version\": ...}}` \ (TL interface decision 2); body={body}" ) }) } /// Тот же immutable metadata object, возвращаемый `GET .../versions/{version}`: допускается /// как верхнеуровневый объект, так и вложенный `published_version` (TL decision 2/3). pub(super) fn version_metadata(body: &Value) -> Value { for pointer in ["", "/published_version", "/version"] { if let Some(value) = body.pointer(pointer) && value.get("digest").is_some() { return value.clone(); } } panic!("Published Version metadata object must expose `digest` (TL decision 3): {body}"); } /// Идентификатор Resource внутри ответа публикации: сам resource card у вложенного /// `resource` (existing card shape) либо на верхнем уровне. pub(super) fn resource_card_id(body: &Value) -> Option { for pointer in [ "/resource/resource_id", "/resource/resource/resource_id", "/resource/id", ] { if let Some(id) = body.pointer(pointer).and_then(Value::as_str) { return Some(id.to_owned()); } } None } /// `published_version` (и тот же объект из `GET .../versions/{version}`) не должен раскрывать /// storage/path/raw filename/artifact source (TL decision 2), при этом обязан нести /// version/uri/name/description/kind/mime_type/size_bytes/digest/sensitivity (TL decision 3). pub(super) fn assert_immutable_metadata(metadata: &Value, raw_upload_filename: &str) { let object = metadata .as_object() .unwrap_or_else(|| panic!("published version metadata must be a JSON object: {metadata}")); for key in [ "version", "uri", "name", "description", "kind", "mime_type", "size_bytes", "digest", "sensitivity", ] { assert!( object.contains_key(key), "published version metadata must include `{key}` (TL decision 3): {metadata}" ); } for (key, value) in object { let lowered = key.to_ascii_lowercase(); for forbidden in [ "path", "storage", "filename", "file_name", "source", "blob", "raw_upload", "upload", ] { assert!( !lowered.contains(forbidden), "published version metadata must not expose `{forbidden}` (key `{key}`): {metadata}" ); } if let Some(text) = value.as_str() { assert!( !text.starts_with('/'), "published version metadata must not expose an absolute storage path (`{key}`): {metadata}" ); assert!( !text.contains("sha256/"), "published version metadata must not expose the content-addressed store path (`{key}`): {metadata}" ); assert!( !text.starts_with("src_"), "published version metadata must not expose the artifact source id (`{key}`): {metadata}" ); assert!( !text.contains(raw_upload_filename), "published version metadata must not echo the raw upload filename (`{key}`): {metadata}" ); } } } // --------------------------------------------------------------------------- // Фикстуры: Draft → публикация, наблюдение «не опубликовано» // --------------------------------------------------------------------------- pub(super) struct DraftFixture { pub resource_id: String, /// Точный CAS карточки Draft. pub updated_at: String, pub card: Value, } /// Создаёт Draft через существующий принятый контракт и читает карточку как источник /// precondition и digest. pub(super) async fn create_fixture( client: &reqwest::Client, server: impl AsRef, metadata: &Value, bytes: &[u8], filename: &str, mime: &str, ) -> DraftFixture { let server = server.as_ref(); let created = create_draft(client, server, metadata, bytes, filename, mime).await; let resource_id = created_resource_id(&created); let card = get_card(client, server, &resource_id).await; let updated_at = draft_updated_at(&card); DraftFixture { resource_id, updated_at, card, } } pub(super) struct PublishedFixture { pub draft: DraftFixture, pub bytes: Vec, pub published_version: Value, /// Полное тело успешного ответа: `resource` card + `published_version` (TL decision 2). pub body: Value, } /// Полный позитивный цикл «валидный Draft → публикация»: успех обязан быть 200 и нести /// immutable `published_version` (AT-3.7-03). pub(super) async fn create_and_publish( client: &reqwest::Client, server: impl AsRef, metadata: &Value, bytes: &[u8], filename: &str, mime: &str, ) -> PublishedFixture { let server = server.as_ref(); let draft = create_fixture(client, server, metadata, bytes, filename, mime).await; let (status, text, body) = publish(client, server, &draft.resource_id, &draft.updated_at).await; assert_eq!( status, StatusCode::OK, "POST .../publish must publish a valid Draft into an immutable Published Version \ (AT-3.7-03); observed {} body={text}", error_signature(status, &body) ); let published_version = published_metadata(&body); assert_immutable_metadata(&published_version, filename); PublishedFixture { draft, bytes: bytes.to_vec(), published_version, body, } } /// Обновление Draft существующим PUT-контрактом: меняются только изменяемые поля. pub(super) async fn update_draft_expect_success( client: &reqwest::Client, server: impl AsRef, resource_id: &str, metadata: &Value, bytes: &[u8], filename: &str, mime: &str, ) -> Value { let server = server.as_ref(); let (status, text, body) = read_response( client .put(format!("{server}/resources/{resource_id}")) .multipart(draft_form(metadata, bytes, filename, mime)) .send() .await .expect("draft update request must complete"), ) .await; assert!( status.is_success(), "a valid Draft update must stay accepted (Story 3.6 contract); observed {} body={text}", error_signature(status, &body) ); body } /// «Точная версия не опубликована»: Draft/nonpublished/чужой version не выдаётся (TL decision 3). pub(super) async fn assert_version_not_published( client: &reqwest::Client, server: impl AsRef, resource_id: &str, version: u32, context: &str, ) { let (status, text, body) = read_version(client, server, resource_id, version).await; assert_eq!( status, StatusCode::NOT_FOUND, "{context}: version {version} must not be readable as a Published Version; observed {} body={text}", error_signature(status, &body) ); } /// «Ничего не опубликовано» для ресурса, который никогда не был опубликован: точная версия /// недоступна и карточка остаётся Draft (refusal не создаёт Published metadata). pub(super) async fn assert_nothing_published( client: &reqwest::Client, server: impl AsRef, resource_id: &str, version: u32, context: &str, ) { let server = server.as_ref(); assert_version_not_published(client, server, resource_id, version, context).await; let card = get_card(client, server, resource_id).await; assert_eq!( card["resource"]["status"], json!("draft"), "{context}: the Resource must stay a Draft after a refusal; card={card}" ); } /// Публикация обязана отказать: точный статус, sanitized error envelope, сохранённый Draft и /// отсутствие Published metadata. Возвращает тело отказа для дополнительных проверок. pub(super) async fn publish_expect_refusal( client: &reqwest::Client, server: impl AsRef, resource_id: &str, expected_updated_at: &str, expected_status: StatusCode, context: &str, ) -> Value { let server = server.as_ref(); let (status, text, body) = publish(client, server, resource_id, expected_updated_at).await; assert_eq!( status, expected_status, "{context}: publication must be refused with {expected_status}; observed {} body={text}", error_signature(status, &body) ); assert!( body["error"]["code"].is_string(), "{context}: a refusal must keep the existing sanitized error envelope; body={text}" ); assert_nothing_published(client, server, resource_id, 1, context).await; body } // --------------------------------------------------------------------------- // Наблюдение сохранённого артефакта (AC02 artifact digest/integrity) // --------------------------------------------------------------------------- /// Физический путь blob по контракту content-addressed store: `sha256//` /// (`crates/crank-artifacts/src/store.rs`: `SHA_DIR`/`ArtifactRef::shard`). pub(super) fn blob_path(storage_root: &Path, digest: &str) -> PathBuf { storage_root.join("sha256").join(&digest[..2]).join(digest) } /// Заменяет сохранённые bytes артефакта другими, сохраняя контракт store: обычный файл, /// одна ссылка, ноль write-бит. Поэтому отказ публикации обязан прийти из digest-проверки, /// а не из проверки прав файла. pub(super) fn replace_blob_with_tampered_bytes(storage_root: &Path, digest: &str, tampered: &[u8]) { let path = blob_path(storage_root, digest); assert!( path.is_file(), "the artifact blob must exist at the content-addressed path {path:?} (fixture premise)" ); std::fs::remove_file(&path).expect("blob must be replaceable for the integrity fixture"); std::fs::write(&path, tampered).expect("tampered blob must be written"); #[cfg(unix)] { use std::os::unix::fs::PermissionsExt; std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o444)) .expect("tampered blob keeps the read-only contract"); } } /// Тест-фикстура defense-in-depth: сохранённый URI больше не проходит грамматику D-10, /// хотя ограничения БД (длина) соблюдены — значит проверять обязан publication validator. pub(super) async fn overwrite_resource_uri(pool: &sqlx::PgPool, resource_id: &str, uri: &str) { sqlx::query("update resources set uri = $1 where resource_id = $2") .bind(uri) .bind(resource_id) .execute(pool) .await .expect("fixture must be able to persist a grammar-invalid uri"); } /// Тест-фикстура defense-in-depth: сохранённый MIME текущей версии больше не входит в /// allowlist kind, хотя синтаксис MIME и ограничения БД соблюдены. pub(super) async fn overwrite_current_version_mime( pool: &sqlx::PgPool, resource_id: &str, mime: &str, ) { sqlx::query( "update resource_versions set mime_type = $1 \ where resource_id = $2 and superseded_at is null", ) .bind(mime) .bind(resource_id) .execute(pool) .await .expect("fixture must be able to persist a non-allowlisted mime type"); }