Integrate Antirion admin with FastAPI and htmx

Add the shared document API, constructor and expert editors, isolated preview, and fragment catalog metadata with typed block IDs.

Include design references, specification 001, QA scripts, project guidance, and cached Docker dependency installation. Leave example sites for a separate commit.
This commit is contained in:
2026-11-12 21:55:36 +03:00
parent 58cc8090a9
commit 88ac95dd19
260 changed files with 20395 additions and 320 deletions
+351
View File
@@ -0,0 +1,351 @@
"""Real FastAPI contract and HTML -> ASGI client -> API integration."""
import os
from unittest.mock import patch
from fastapi.testclient import TestClient
from helpers import SiteTestCase
from site_engine.services.auth import hash_password
from site_engine.web.app import create_app
class ApiTests(SiteTestCase):
@classmethod
def setUpClass(cls):
cls.password = "temporary test password"
cls.password_hash = hash_password(cls.password, n=2**10)
def setUp(self):
super().setUp()
self.env = patch.dict(
os.environ,
{
"SITE_ROOT": str(self.site),
"SITE_DIST": str(self.out),
"SITE_STATE_DIR": str(self.tmp / "state"),
"SITE_ADMIN_LOGIN": "admin",
"SITE_ADMIN_PASSWORD_HASH": self.password_hash,
"SITE_SECRET_KEY": "test-api-secret-" * 4,
"SITE_COOKIE_SECURE": "0",
"SITE_ADMIN_ORIGIN": "",
"SITE_PREVIEW_ORIGIN": "",
},
)
self.env.start()
self.addCleanup(self.env.stop)
self.app = create_app()
self.client = TestClient(self.app)
self.addCleanup(self.client.close)
self.cookie = self.app.state.auth.login("admin", self.password, "testclient")
self.client.cookies.set("se_session", self.cookie)
self.principal = self.app.state.auth.authenticate(self.cookie)
self.csrf = self.app.state.auth.csrf_token(self.principal)
self.app.state.api_credentials["test-credential"] = (self.cookie, "testclient")
self.headers = {"Authorization": "Bearer test-credential"}
def api(self, method, path, data=None, headers=None):
return self.client.request(
method, "/admin/api/v1" + path, json=data, headers=headers or self.headers
)
def source(self):
return self.api("GET", "/pages/index/source").json()
def test_fragment_names_and_descriptions_reach_catalog_through_api(self):
fragments = self.source()["schema"]["fragments"]
expected = {
"collection_list": ("Список коллекций", "Карточки, получаемые из collection"),
"section": ("Текстовая секция", "Заголовок и содержимое секции"),
"richtext": ("Markdown body", "Выводит Markdown из файла страницы"),
"card_grid": ("Карточки", "Сетка преимуществ"),
}
html = self.client.get("/admin/pages/index").text
from html.parser import HTMLParser
class Catalog(HTMLParser):
def __init__(self):
super().__init__()
self.items, self.current = {}, None
def handle_starttag(self, tag, attrs):
attrs = dict(attrs)
if tag == "button" and "data-fragment" in attrs:
self.current = attrs["data-fragment"]
self.items[self.current] = []
def handle_data(self, data):
if self.current:
self.items[self.current].append(data)
def handle_endtag(self, tag):
if tag == "button":
self.current = None
catalog = Catalog()
catalog.feed(html)
for fid, (name, description) in expected.items():
self.assertEqual(fragments[fid]["name"], name)
self.assertEqual(fragments[fid]["description"], description)
text = " ".join(catalog.items[fid])
self.assertIn(name, text)
self.assertIn(description, text)
def test_json_html_and_openapi_separate(self):
self.assertEqual(self.client.get("/admin/api/v1/site").status_code, 401)
data = self.api("GET", "/site")
self.assertEqual(data.status_code, 200)
self.assertIn("pages", data.json())
self.assertEqual(data.headers["cache-control"], "no-store")
schema = self.client.get("/admin/api/openapi.json")
self.assertEqual(schema.status_code, 200)
self.assertIn("/admin/api/v1/pages/{identity}/save", schema.json()["paths"])
self.assertIn("Transform", schema.json()["components"]["schemas"])
self.assertIn("InternalUiSession", schema.json()["components"]["securitySchemes"])
self.client.cookies.clear()
self.assertEqual(self.client.get("/admin/api/openapi.json").status_code, 401)
self.assertEqual(self.client.get("/admin/api/docs").status_code, 401)
def test_html_uses_client_and_removes_request_credentials(self):
before = self.app.state.api_calls
response = self.client.get("/admin/pages/index")
self.assertEqual(response.status_code, 200)
self.assertIn("document-editor", response.text)
self.assertGreater(self.app.state.api_calls, before)
self.assertEqual(set(self.app.state.api_credentials), {"test-credential"})
self.assertNotIn("test-credential", response.text)
self.assertNotIn("Bearer ", response.text)
with patch(
"site_engine.web.admin.api_client.AdminApi.call",
side_effect=__import__(
"site_engine.web.admin.api_client", fromlist=["ApiError"]
).ApiError(503, {"error": {"message": "Unavailable"}}),
):
response = self.client.get("/admin/pages")
self.assertEqual(response.status_code, 503)
self.assertIn("Unavailable", response.text)
def test_buffer_validate_transform_save_and_conflict(self):
s = self.source()
payload = {"source": s["source"], "etag": s["etag"], "revision": 7}
transformed = self.api(
"POST",
"/pages/index/transform",
dict(payload, action={"type": "metadata", "values": {"title": "API buffer"}}),
)
self.assertEqual(transformed.status_code, 200, transformed.text)
t = transformed.json()
self.assertEqual(t["etag"], s["etag"])
self.assertEqual(self.source()["source"], s["source"])
saved = self.api("POST", "/pages/index/save", dict(payload, source=t["source"]))
self.assertEqual(saved.status_code, 200, saved.text)
conflict = self.api("POST", "/pages/index/save", payload)
self.assertEqual(conflict.status_code, 409)
e = conflict.json()["error"]
self.assertEqual(e["current"]["source"], t["source"])
self.assertEqual(e["submitted"]["source"], s["source"])
self.assertEqual(e["submitted"]["etag"], s["etag"])
def test_typed_actions_and_error_envelopes(self):
s = self.source()
payload = {"source": s["source"], "etag": s["etag"]}
for action in (
{"type": "unimplemented"},
{"type": "move", "block_id": "b_hero", "direction": "up", "before": "b_hero"},
):
response = self.api("POST", "/pages/index/transform", dict(payload, action=action))
self.assertEqual(response.status_code, 422)
self.assertIn("error", response.json())
bad = self.api(
"POST", "/pages/index/validate", dict(payload, source="---\na: 1\na: 2\n---\n")
)
self.assertEqual(bad.status_code, 422)
self.assertIsNone(bad.json()["error"]["buffer"]["model"])
self.assertEqual(self.api("GET", "/pages/missing/source").status_code, 404)
self.assertEqual(self.api("GET", "/assets/..%2f..%2fsite.yaml").status_code, 403)
def test_builder_catalog_duplicate_and_metadata_use_the_same_contract(self):
s = self.source()
payload = {"source": s["source"], "etag": s["etag"], "revision": 4}
added = self.api(
"POST",
"/pages/index/transform",
dict(
payload,
action={
"type": "add",
"fragment": "hero",
"region": "main",
"props": {"title": "Catalog"},
},
),
)
self.assertEqual(added.status_code, 200, added.text)
block = added.json()["model"]["meta"]["regions"]["main"][-1]
self.assertRegex(block["id"], r"^hero_[a-z0-9]{5}$")
duplicate = self.api(
"POST",
"/pages/index/transform",
dict(
payload,
source=added.json()["source"],
action={"type": "duplicate", "block_id": block["id"]},
),
)
self.assertEqual(duplicate.status_code, 200, duplicate.text)
blocks = duplicate.json()["model"]["meta"]["regions"]["main"]
self.assertNotEqual(blocks[-1]["id"], block["id"])
self.assertRegex(blocks[-1]["id"], r"^hero_[a-z0-9]{5}$")
self.assertEqual(blocks[-1]["props"], block["props"])
response = self.client.post(
"/admin/editor/pages/index/transform",
data={
**payload,
"csrf": self.csrf,
"operation": "metadata",
"title": "Changed title",
"status": "published",
"seo_title": "Real SEO title",
"seo_description": "Description",
},
headers={"Origin": "http://testserver", "HX-Request": "true"},
)
self.assertEqual(response.status_code, 200, response.text[:1000])
self.assertIn("Real SEO title", response.text)
self.assertEqual(self.source()["source"], s["source"])
def test_nested_create_entry_and_publish_rollback(self):
result = self.api("POST", "/pages", {"id": "nested/api", "title": "Nested API"})
self.assertEqual(result.status_code, 201, result.text)
self.assertEqual(self.api("GET", "/pages/nested/api/source").status_code, 200)
self.assertEqual(
self.api("POST", "/collections/services/entries", {"id": "api-draft"}).status_code, 201
)
e = self.api("GET", "/collections/services/entries/bots/source").json()
self.assertEqual(e["kind"], "entry")
result = self.api("POST", "/publish")
self.assertEqual(result.status_code, 200, result.text)
build = result.json()["current"]
self.assertEqual(self.api("POST", "/rollback/" + build).status_code, 200)
def test_epoch_revokes_api_credentials(self):
self.app.state.auth.logout(self.principal)
self.assertEqual(self.api("GET", "/site").status_code, 401)
def test_pages_comparison_and_html_creation_preserve_list_selection(self):
self.assertEqual(len(self.api("GET", "/pages?changed=true").json()), 5)
self.assertEqual(self.api("POST", "/publish").status_code, 200)
rows = self.api("GET", "/pages?changed=true").json()
self.assertEqual([p["id"] for p in rows], ["drafts/next"])
self.assertEqual(self.client.get("/admin/pages?selected=missing").status_code, 404)
payload = {
"csrf": self.csrf,
"title": "Nested draft",
"page_id": "nested/ui",
"layout": "default",
}
response = self.client.post(
"/admin/pages/new",
data=payload,
headers={"Origin": "http://testserver"},
follow_redirects=False,
)
self.assertEqual(response.status_code, 303, response.text)
self.assertEqual(
response.headers["location"], "/admin/pages?selected=nested%2Fui&msg=created"
)
response = self.client.post(
"/admin/pages/new", data=payload, headers={"Origin": "http://testserver"}
)
self.assertEqual(response.status_code, 409, response.text[:500])
self.assertIn("open data-auto-open", response.text)
self.assertIn("value='Nested draft'", response.text)
def test_html_csrf_and_full_form_save(self):
s = self.source()
response = self.client.post(
"/admin/editor/pages/index/save",
data={"source": s["source"], "etag": s["etag"], "csrf": self.csrf},
)
self.assertEqual(response.status_code, 403)
source = s["source"].replace("title:", "# preserved\ntitle:", 1)
response = self.client.post(
"/admin/editor/pages/index/save",
data={"source": source, "etag": s["etag"], "csrf": self.csrf},
headers={"Origin": "http://testserver"},
)
self.assertEqual(response.status_code, 200, response.text[:1000])
self.assertEqual(self.source()["source"], source)
response = self.client.post(
"/admin/editor/pages/index/save",
data={"source": s["source"], "etag": s["etag"], "csrf": self.csrf},
headers={"Origin": "http://testserver", "HX-Request": "true"},
)
self.assertEqual(response.status_code, 409)
self.assertIn("data-rebase", response.text)
self.assertIn("Серверный исходник", response.text)
def test_ui_assets_are_binary_and_protected(self):
self.write("assets/new.svg", '<svg xmlns="http://www.w3.org/2000/svg"/>')
response = self.client.get("/admin/preview/assets/new.svg")
self.assertEqual(response.status_code, 200)
self.assertIn("image/svg+xml", response.headers["content-type"])
self.client.cookies.clear()
self.assertEqual(
self.client.get("/admin/preview/assets/new.svg", follow_redirects=False).status_code,
303,
)
def test_planned_routes_filters_and_readonly_inspector(self):
self.assertEqual(self.api("GET", "/collections").status_code, 200)
self.assertEqual(self.api("GET", "/pages?q=no-such-document").json(), [])
self.assertEqual(self.api("GET", "/pages?status=unknown").status_code, 422)
self.assertEqual(self.api("GET", "/entries/services").status_code, 200)
s = self.api("GET", "/editor/pages/index/source").json()
self.assertEqual(s["kind"], "page")
response = self.api(
"POST",
"/editor/pages/index/validate",
{"source": s["source"], "etag": s["etag"], "revision": 2},
)
self.assertEqual(response.status_code, 200)
self.assertEqual(self.client.get("/admin/api/v1/openapi.json").status_code, 200)
self.assertEqual(self.client.get("/admin/api/v1/docs").status_code, 200)
import json
response = self.client.post(
"/admin/editor/pages/index/select",
data={
"source": s["source"],
"etag": s["etag"],
"csrf": self.csrf,
"readonly": json.dumps({"scope": "layout", "owner": "default", "id": "lh_header"}),
},
headers={"Origin": "http://testserver", "HX-Request": "true"},
)
self.assertEqual(response.status_code, 200)
self.assertIn("data-readonly-inspector", response.text)
self.assertIn("site_header", response.text)
def test_incomplete_preview_configuration_keeps_editor_available(self):
with patch.dict(
os.environ, {"SITE_ADMIN_ORIGIN": "http://127.0.0.1:8000", "SITE_PREVIEW_ORIGIN": ""}
):
app = create_app()
self.assertIsNone(app.state.previews.config)
self.assertTrue(app.state.previews.unavailable_reason)
def test_limits_and_forged_credentials_keep_error_contract(self):
response = self.api("GET", "/site", headers={"Authorization": "Bearer forged"})
self.assertEqual(response.status_code, 401)
self.assertIn("error", response.json())
response = self.client.post(
"/admin/api/v1/pages/index/validate", content=b"x" * 1048577, headers=self.headers
)
self.assertEqual(response.status_code, 413)
self.assertEqual(response.json()["error"]["code"], "body_too_large")
response = self.api("GET", "/site", headers={**self.headers, "HX-Request": "true"})
self.assertIn("application/json", response.headers["content-type"])
response = self.client.get("/admin/pages/index?mode=expert")
self.assertEqual(response.status_code, 200)
self.assertIn("name='mode' value='expert'", response.text)