v0.31.0: meta-only repository topology (ROADMAP #36)
Retire the per-RFC-repo model. RFCs now live in their meta-repo entry (rfcs/<slug>.md) for their whole life; graduation is an in-place super-draft → active state flip that keeps the body in the entry — no repo creation, no body-strip, no five-step transaction, no rollback. SPEC: §1 topology rewritten (one meta/content repository, no per-RFC repos) with a deployer-facing "single content repository" framing; §2 (repo: always-null), §3 (active is in-place), §4, §9.8 (handoff frictions dissolve), and §13 fully rewritten (two-field dialog, "The flip", §13.6 RFC-0001 fold-back record). Code: graduation collapses to open+merge one frontmatter PR; branch/PR/ chat dispatch re-keyed on meta-residency (repo IS NULL) so active RFCs edit on the meta repo exactly as super-drafts do; the two "RFC has no repo" 409 guards removed; promote-to-branch slug-embeds an active RFC's auto-branch (edit-<slug>-<hex>) for shared-repo cache attribution; refresh_meta_branches + hygiene branch-resolution include meta-resident actives; the §9.8 read-only guard + pre_graduation_history scoped to legacy per-repo only; dead bot primitives + GraduateDialog repo field + blocking-PR popover removed. The repo: frontmatter field and the /blocking-prs endpoint are retained (schema stability / informational). Tests: graduation suite rewritten to the flip model; e2e + hygiene updated. Full backend suite 375 passed; frontend builds. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ben Stull
+132
-365
@@ -1,26 +1,30 @@
|
||||
"""Slice 5 API surface — the §13 graduation flow's endpoints and the
|
||||
in-process orchestrator that runs the §13.3 transactional sequence with
|
||||
rollback.
|
||||
"""§13 graduation flow — the meta-only in-place state flip.
|
||||
|
||||
Owns four routes per §17:
|
||||
Under the meta-only topology (SPEC §1), graduation no longer creates a
|
||||
per-RFC repo. It is a single frontmatter-flipping commit to the entry's
|
||||
`rfcs/<slug>.md` on the meta repo: open a PR that re-serializes the entry
|
||||
with `state: active`, the assigned integer `id`, `graduated_at` /
|
||||
`graduated_by`, and the dialog's owners — **leaving the body unchanged** —
|
||||
then auto-merge it. There is no repo to create, nothing to seed, and the
|
||||
body is neither moved nor stripped, so there is no multi-step transaction
|
||||
and no rollback (§13.3). If the open or merge fails, the entry stays a
|
||||
super-draft and we clean up the half-open PR/branch (the only artifact a
|
||||
mid-flip failure can leave behind).
|
||||
|
||||
Routes (§17):
|
||||
|
||||
- GET /api/rfcs/<slug>/blocking-prs (§13.2 precondition popover)
|
||||
- GET /api/rfcs/<slug>/graduate/check (§13.2 debounced validator)
|
||||
- POST /api/rfcs/<slug>/graduate (§13.3 kickoff)
|
||||
- POST /api/rfcs/<slug>/graduate (§13.3 the flip)
|
||||
- GET /api/rfcs/<slug>/graduate/progress (§13.3 SSE step stream)
|
||||
- GET /api/rfcs/<slug>/blocking-prs (informational; no longer a
|
||||
graduation precondition)
|
||||
|
||||
Plus the §13.1 claim PR endpoint (POST /api/rfcs/<slug>/claim), which is
|
||||
graduation's prerequisite for non-admins per §13.1.
|
||||
Plus the §13.1 claim PR endpoint (POST /api/rfcs/<slug>/claim).
|
||||
|
||||
The orchestrator runs in-process — each in-flight graduation lives in a
|
||||
small `GraduationState` keyed by slug, with an asyncio.Queue feeding the
|
||||
SSE handler. Per the §13.3 transactional contract, every forward step is
|
||||
paired with an undo; rollback runs the undos in reverse order from the
|
||||
last step that completed. §13.4's chat migration is a database semantic
|
||||
no-op (the threads' `(rfc_slug, branch_name='main')` rows are interpreted
|
||||
as super-draft canonical-body before graduation and as new-RFC main
|
||||
afterwards — same shape, different meaning), so the only DB work the
|
||||
sequence does is the audit-log rows the bot's `_log` writes per step.
|
||||
SSE handler. §13.4's chat/branch/history are a database no-op: every row
|
||||
is keyed by the slug per §2.3 and stays put across the flip.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -44,24 +48,18 @@ log = logging.getLogger(__name__)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Step machine
|
||||
# Step machine — two steps under meta-only: open the flip PR, merge it.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
STEP_KEYS = (
|
||||
"create_repo",
|
||||
"seed_files",
|
||||
"open_pr",
|
||||
"merge_pr",
|
||||
"refresh_cache",
|
||||
)
|
||||
|
||||
STEP_LABELS = {
|
||||
"create_repo": "Create per-RFC repository",
|
||||
"seed_files": "Seed RFC.md, README.md, and .rfc/metadata.yaml",
|
||||
"open_pr": "Open meta-repo graduation PR",
|
||||
"open_pr": "Open graduation PR (flip state to active)",
|
||||
"merge_pr": "Merge graduation PR",
|
||||
"refresh_cache": "Refresh catalog and views",
|
||||
}
|
||||
|
||||
|
||||
@@ -77,8 +75,6 @@ class StepState:
|
||||
class GraduationState:
|
||||
slug: str
|
||||
rfc_id: str
|
||||
repo_name: str
|
||||
repo_full: str
|
||||
owners: list[str]
|
||||
arbiters: list[str]
|
||||
steps: list[StepState]
|
||||
@@ -86,8 +82,6 @@ class GraduationState:
|
||||
finished: bool = False
|
||||
succeeded: bool = False
|
||||
error: str | None = None
|
||||
rollback_started: bool = False
|
||||
rollback_steps: list[StepState] = field(default_factory=list)
|
||||
new_pr_number: int | None = None
|
||||
graduation_branch: str | None = None
|
||||
|
||||
@@ -95,12 +89,9 @@ class GraduationState:
|
||||
return {
|
||||
"slug": self.slug,
|
||||
"rfc_id": self.rfc_id,
|
||||
"repo_full": self.repo_full,
|
||||
"steps": [_step_payload(s) for s in self.steps],
|
||||
"rollback_steps": [_step_payload(s) for s in self.rollback_steps],
|
||||
"finished": self.finished,
|
||||
"succeeded": self.succeeded,
|
||||
"rolled_back": self.rollback_started,
|
||||
"error": self.error,
|
||||
"pr_number": self.new_pr_number,
|
||||
}
|
||||
@@ -114,7 +105,7 @@ def _step_payload(s: StepState) -> dict:
|
||||
# is fine; the registry is keyed by slug to refuse concurrent graduations
|
||||
# of the same entry (the §13.2 atomic re-check is a separate defense
|
||||
# against a concurrent attempt of a DIFFERENT slug claiming the same
|
||||
# integer ID or repo name).
|
||||
# integer ID).
|
||||
_active: dict[str, GraduationState] = {}
|
||||
|
||||
|
||||
@@ -122,10 +113,10 @@ def _get_active(slug: str) -> GraduationState | None:
|
||||
return _active.get(slug)
|
||||
|
||||
|
||||
def _new_active(slug: str, *, rfc_id: str, repo_name: str, repo_full: str,
|
||||
def _new_active(slug: str, *, rfc_id: str,
|
||||
owners: list[str], arbiters: list[str]) -> GraduationState:
|
||||
state = GraduationState(
|
||||
slug=slug, rfc_id=rfc_id, repo_name=repo_name, repo_full=repo_full,
|
||||
slug=slug, rfc_id=rfc_id,
|
||||
owners=owners, arbiters=arbiters,
|
||||
steps=[StepState(key=k, label=STEP_LABELS[k]) for k in STEP_KEYS],
|
||||
)
|
||||
@@ -138,17 +129,9 @@ def _new_active(slug: str, *, rfc_id: str, repo_name: str, repo_full: str,
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
# §13.2: Gitea repo name pattern. Gitea accepts alphanumerics, dashes,
|
||||
# dots, and underscores; cannot start with a dot. 100-char cap as a sane
|
||||
# upper bound — the spec doesn't pin a max but Gitea's enforcement does.
|
||||
_REPO_NAME_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$")
|
||||
_RFC_ID_RE = re.compile(r"^RFC-\d{4,}$")
|
||||
|
||||
|
||||
def _is_valid_repo_name(name: str) -> bool:
|
||||
return bool(_REPO_NAME_RE.match(name)) and ".." not in name
|
||||
|
||||
|
||||
def _is_valid_rfc_id(rfc_id: str) -> bool:
|
||||
return bool(_RFC_ID_RE.match(rfc_id))
|
||||
|
||||
@@ -167,13 +150,6 @@ def _suggest_next_rfc_id() -> str:
|
||||
return f"RFC-{nxt:04d}"
|
||||
|
||||
|
||||
def _suggest_repo_name(slug: str, rfc_id: str) -> str:
|
||||
# rfc-NNNN-<slug> per §13.2's default. Strip the 'RFC-' prefix and
|
||||
# lowercase the number-pad.
|
||||
num = rfc_id.split("-", 1)[1] if "-" in rfc_id else "0001"
|
||||
return f"rfc-{num}-{slug}"
|
||||
|
||||
|
||||
def _rfc_id_taken(rfc_id: str, *, excluding_slug: str) -> bool:
|
||||
row = db.conn().execute(
|
||||
"SELECT slug FROM cached_rfcs WHERE rfc_id = ? AND slug != ?",
|
||||
@@ -189,7 +165,6 @@ def _rfc_id_taken(rfc_id: str, *, excluding_slug: str) -> bool:
|
||||
|
||||
class GraduateBody(BaseModel):
|
||||
rfc_id: str = Field(min_length=5, max_length=40)
|
||||
repo_name: str = Field(min_length=1, max_length=100)
|
||||
owners: list[str] = Field(min_length=1)
|
||||
|
||||
|
||||
@@ -206,19 +181,17 @@ def make_router(
|
||||
router = APIRouter()
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# §13.2: GET /api/rfcs/<slug>/blocking-prs
|
||||
# Lists open meta-repo PRs against rfcs/<slug>.md per the precondition
|
||||
# popover. Returns PR number, title, author, last-activity timestamp,
|
||||
# and the viewer's available actions (merge, withdraw, open-in-new-tab).
|
||||
# GET /api/rfcs/<slug>/blocking-prs
|
||||
# Lists open meta-repo body-edit PRs against rfcs/<slug>.md. Under the
|
||||
# meta-only topology (§9.8) these no longer block graduation — the body
|
||||
# is kept, so a body-edit PR coexists with the flip. Retained as an
|
||||
# informational surface (the dialog can show "N body-edit PRs open").
|
||||
# -------------------------------------------------------------------
|
||||
|
||||
@router.get("/api/rfcs/{slug}/blocking-prs")
|
||||
async def list_blocking_prs(slug: str, request: Request) -> dict[str, Any]:
|
||||
viewer = auth.current_user(request)
|
||||
rfc = _require_super_draft(slug)
|
||||
# §13's opening paragraph: only body-edit PRs block graduation.
|
||||
# Bare edit branches without an open PR do not block. The query
|
||||
# filters cached_prs to open meta_body_edit kinds for this slug.
|
||||
rows = db.conn().execute(
|
||||
"""
|
||||
SELECT pr_number, title, opened_by, opened_at, head_branch, pr_kind
|
||||
@@ -261,14 +234,15 @@ def make_router(
|
||||
"open_in_new_tab": True,
|
||||
},
|
||||
})
|
||||
return {"items": items}
|
||||
# `blocking` is a legacy field name kept for client compatibility;
|
||||
# under §9.8 these PRs do not block graduation.
|
||||
return {"items": items, "blocking": False}
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# §13.2: GET /api/rfcs/<slug>/graduate/check?id=&repo=
|
||||
# GET /api/rfcs/<slug>/graduate/check?id=
|
||||
# Inline validation for the Graduate dialog — debounced from the
|
||||
# client; the dialog calls this as the admin types. Returns per-field
|
||||
# collision/validity from the catalog cache plus a server-authoritative
|
||||
# repo-name collision check.
|
||||
# client. Two fields under meta-only: the integer ID and the owners
|
||||
# precondition. There is no repo name to validate (§13.2).
|
||||
# -------------------------------------------------------------------
|
||||
|
||||
@router.get("/api/rfcs/{slug}/graduate/check")
|
||||
@@ -281,16 +255,7 @@ def make_router(
|
||||
# admins/owners, but the check itself is read-only.
|
||||
|
||||
candidate_id = (request.query_params.get("id") or "").strip()
|
||||
candidate_repo = (request.query_params.get("repo") or "").strip()
|
||||
|
||||
owners = json.loads(rfc["owners_json"] or "[]")
|
||||
blocking_count = db.conn().execute(
|
||||
"""
|
||||
SELECT COUNT(*) AS n FROM cached_prs
|
||||
WHERE rfc_slug = ? AND state = 'open' AND pr_kind = 'meta_body_edit'
|
||||
""",
|
||||
(slug,),
|
||||
).fetchone()["n"]
|
||||
|
||||
# ID field
|
||||
id_payload: dict[str, Any] = {"value": candidate_id, "ok": True, "error": None}
|
||||
@@ -304,34 +269,6 @@ def make_router(
|
||||
id_payload["ok"] = False
|
||||
id_payload["error"] = f"Integer ID {candidate_id} is already taken"
|
||||
|
||||
# Repo field — validate pattern then probe Gitea for an existing
|
||||
# repo of that name under our org. The repo lookup is a single GET
|
||||
# so it's cheap to call on every keystroke (debounced from the
|
||||
# client per §13.2).
|
||||
repo_payload: dict[str, Any] = {"value": candidate_repo, "ok": True, "error": None}
|
||||
if not candidate_repo:
|
||||
repo_payload["ok"] = False
|
||||
repo_payload["error"] = "Repo name is required"
|
||||
elif not _is_valid_repo_name(candidate_repo):
|
||||
repo_payload["ok"] = False
|
||||
repo_payload["error"] = (
|
||||
"Repo name must be alphanumerics, dashes, dots, or underscores "
|
||||
"(start with alphanumeric)"
|
||||
)
|
||||
else:
|
||||
try:
|
||||
existing = await gitea.get_repo(config.gitea_org, candidate_repo)
|
||||
except GiteaError as e:
|
||||
# Network/auth flake — surface as a non-fatal hint; the
|
||||
# atomic server-side check at POST time is the authority.
|
||||
existing = None
|
||||
log.warning("graduate_check: Gitea get_repo error: %s", e)
|
||||
if existing is not None:
|
||||
repo_payload["ok"] = False
|
||||
repo_payload["error"] = (
|
||||
f"Repo `{config.gitea_org}/{candidate_repo}` already exists"
|
||||
)
|
||||
|
||||
# Owners precondition — §13's opening paragraph.
|
||||
owners_payload: dict[str, Any] = {
|
||||
"ok": len(owners) > 0,
|
||||
@@ -340,28 +277,13 @@ def make_router(
|
||||
"error": None if len(owners) > 0 else "No owners claimed yet",
|
||||
}
|
||||
|
||||
# Blocking PR precondition — §9.8 / §13's opening paragraph.
|
||||
prs_payload: dict[str, Any] = {
|
||||
"ok": blocking_count == 0,
|
||||
"count": blocking_count,
|
||||
"error": (
|
||||
None if blocking_count == 0
|
||||
else f"{blocking_count} open body-edit PR{'' if blocking_count == 1 else 's'} blocking graduation"
|
||||
),
|
||||
}
|
||||
|
||||
in_flight = _get_active(slug)
|
||||
any_invalid = not (
|
||||
id_payload["ok"] and repo_payload["ok"]
|
||||
and owners_payload["ok"] and prs_payload["ok"]
|
||||
)
|
||||
any_invalid = not (id_payload["ok"] and owners_payload["ok"])
|
||||
|
||||
return {
|
||||
"slug": slug,
|
||||
"id": id_payload,
|
||||
"repo": repo_payload,
|
||||
"owners": owners_payload,
|
||||
"blocking_prs": prs_payload,
|
||||
"can_submit": (not any_invalid) and (in_flight is None or in_flight.finished),
|
||||
"in_flight": (
|
||||
None if in_flight is None
|
||||
@@ -370,8 +292,8 @@ def make_router(
|
||||
}
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# §13.3: POST /api/rfcs/<slug>/graduate
|
||||
# Atomic re-validation, then kicks off the sequence as an async task.
|
||||
# POST /api/rfcs/<slug>/graduate
|
||||
# Atomic re-validation, then kicks off the flip as an async task.
|
||||
# The client opens GET /graduate/progress on confirm to watch the SSE.
|
||||
# -------------------------------------------------------------------
|
||||
|
||||
@@ -392,9 +314,8 @@ def make_router(
|
||||
|
||||
# §13.2 atomic re-validation. The dialog's debounced check runs
|
||||
# client-side as the admin types; this is the authoritative check
|
||||
# that closes the dialog-open-to-confirm race.
|
||||
# that closes the dialog-open-to-confirm race on the integer ID.
|
||||
rfc_id = body.rfc_id.strip()
|
||||
repo_name = body.repo_name.strip()
|
||||
owners = [o.strip() for o in body.owners if o.strip()]
|
||||
if not owners:
|
||||
raise HTTPException(422, "Add at least one initial owner")
|
||||
@@ -402,35 +323,10 @@ def make_router(
|
||||
raise HTTPException(422, "ID must look like RFC-NNNN (at least four digits)")
|
||||
if _rfc_id_taken(rfc_id, excluding_slug=slug):
|
||||
raise HTTPException(409, f"Integer ID {rfc_id} is already taken")
|
||||
if not _is_valid_repo_name(repo_name):
|
||||
raise HTTPException(422, "Repo name must be alphanumerics, dashes, dots, or underscores")
|
||||
try:
|
||||
existing_repo = await gitea.get_repo(config.gitea_org, repo_name)
|
||||
except GiteaError as e:
|
||||
raise HTTPException(502, f"Gitea: {e.detail}")
|
||||
if existing_repo is not None:
|
||||
raise HTTPException(409, f"Repo `{config.gitea_org}/{repo_name}` already exists")
|
||||
|
||||
# §9.8 precondition gate — enforced before the bot starts the
|
||||
# sequence so the §13.3 rollback complexity does not grow. An
|
||||
# open body-edit PR against rfcs/<slug>.md would attempt to
|
||||
# re-introduce a body to a frontmatter-only entry after step 3.
|
||||
blocking = db.conn().execute(
|
||||
"""
|
||||
SELECT COUNT(*) AS n FROM cached_prs
|
||||
WHERE rfc_slug = ? AND state = 'open' AND pr_kind = 'meta_body_edit'
|
||||
""",
|
||||
(slug,),
|
||||
).fetchone()["n"]
|
||||
if blocking > 0:
|
||||
raise HTTPException(
|
||||
409,
|
||||
f"{blocking} open body-edit PR{'' if blocking == 1 else 's'} block graduation",
|
||||
)
|
||||
|
||||
# Read the meta-repo entry once — we need the file's sha for the
|
||||
# graduation PR's update_file call and the original body so the
|
||||
# bot can seed RFC.md on the new repo with the migrated body.
|
||||
# graduation PR's update_file call and the body to carry through
|
||||
# unchanged (meta-only keeps the body in the entry, §13.3).
|
||||
fetched = await gitea.read_file(
|
||||
config.gitea_org, config.meta_repo, f"rfcs/{slug}.md", ref="main",
|
||||
)
|
||||
@@ -442,19 +338,17 @@ def make_router(
|
||||
except Exception as e:
|
||||
raise HTTPException(500, f"Meta entry malformed: {e}")
|
||||
|
||||
repo_full = f"{config.gitea_org}/{repo_name}"
|
||||
arbiters = json.loads(rfc["arbiters_json"] or "[]") or owners[:1]
|
||||
|
||||
# Compose the graduated frontmatter — body stripped, graduation
|
||||
# fields filled. The serializer is run now so the PR-open step
|
||||
# has the contents pre-rendered (single source of truth for the
|
||||
# body migration vs. the meta-entry update).
|
||||
# Compose the graduated frontmatter — body KEPT, graduation fields
|
||||
# filled, repo left null (§1). Serialized now so the PR-open step
|
||||
# has the contents pre-rendered.
|
||||
graduated_entry = entry_mod.Entry(
|
||||
slug=slug,
|
||||
title=super_draft_entry.title,
|
||||
state="active",
|
||||
id=rfc_id,
|
||||
repo=repo_full,
|
||||
repo=None,
|
||||
proposed_by=super_draft_entry.proposed_by,
|
||||
proposed_at=super_draft_entry.proposed_at,
|
||||
graduated_at=entry_mod.today(),
|
||||
@@ -462,37 +356,30 @@ def make_router(
|
||||
owners=owners,
|
||||
arbiters=arbiters,
|
||||
tags=list(super_draft_entry.tags),
|
||||
body="",
|
||||
models=super_draft_entry.models,
|
||||
funder=super_draft_entry.funder,
|
||||
body=super_draft_entry.body,
|
||||
)
|
||||
graduated_contents = entry_mod.serialize(graduated_entry)
|
||||
|
||||
state = _new_active(
|
||||
slug, rfc_id=rfc_id, repo_name=repo_name, repo_full=repo_full,
|
||||
owners=owners, arbiters=arbiters,
|
||||
slug, rfc_id=rfc_id, owners=owners, arbiters=arbiters,
|
||||
)
|
||||
|
||||
# Audit: graduation started. The terminal `graduate_complete` /
|
||||
# `graduate_rollback` rows below close the linkable sequence.
|
||||
# `graduate_failed` rows below close the linkable sequence.
|
||||
_audit(
|
||||
viewer.user_id, viewer.gitea_login, "graduate_start",
|
||||
rfc_slug=slug,
|
||||
details={
|
||||
"rfc_id": rfc_id, "repo": repo_full, "owners": owners,
|
||||
"blocking_prs": blocking,
|
||||
},
|
||||
details={"rfc_id": rfc_id, "owners": owners},
|
||||
)
|
||||
|
||||
# Test seam: `?_sync=1` awaits the orchestrator inline so
|
||||
# integration tests can assert post-conditions without driving
|
||||
# the SSE. Production clients use the spec-described shape —
|
||||
# POST returns immediately, the client subscribes to the
|
||||
# progress SSE.
|
||||
# the SSE. Production clients POST then subscribe to the SSE.
|
||||
coro = _orchestrate(
|
||||
config=config, gitea=gitea, bot=bot,
|
||||
actor=viewer.as_actor(), state=state,
|
||||
super_draft_body=super_draft_entry.body,
|
||||
super_draft_title=super_draft_entry.title,
|
||||
super_draft_tags=list(super_draft_entry.tags),
|
||||
graduated_contents=graduated_contents,
|
||||
meta_file_sha=meta_sha,
|
||||
)
|
||||
@@ -505,38 +392,31 @@ def make_router(
|
||||
"ok": True,
|
||||
"slug": slug,
|
||||
"rfc_id": rfc_id,
|
||||
"repo": repo_full,
|
||||
"stream_url": f"/api/rfcs/{slug}/graduate/progress",
|
||||
"finished": state.finished,
|
||||
"succeeded": state.succeeded,
|
||||
}
|
||||
|
||||
# -------------------------------------------------------------------
|
||||
# §13.3: GET /api/rfcs/<slug>/graduate/progress
|
||||
# SSE stream of the step transitions. One event per step transition
|
||||
# (pending → running → done / failed), plus the trailing rollback
|
||||
# step's events if any earlier step fails.
|
||||
# GET /api/rfcs/<slug>/graduate/progress
|
||||
# SSE stream of the flip's step transitions (open_pr, merge_pr).
|
||||
# -------------------------------------------------------------------
|
||||
|
||||
@router.get("/api/rfcs/{slug}/graduate/progress")
|
||||
async def graduate_progress(slug: str, request: Request):
|
||||
# v0.6.0 (item #4): the progress SSE surfaces admin-internal step
|
||||
# detail (repo name, PR number, rollback steps) that isn't part of
|
||||
# the v0.3.0 anonymous-read contract for catalog/RFC bodies. The
|
||||
# corresponding POST /graduate is gated to RFC owners/arbiters and
|
||||
# app admins/owners via `_can_graduate`; the read SSE shares that
|
||||
# operator-visible surface, so it requires at least an
|
||||
# authenticated viewer. We keep the floor at require_user (not
|
||||
# require_contributor) so a write-muted operator can still observe
|
||||
# the progress of a graduation they kicked off before being muted.
|
||||
# The progress SSE surfaces admin-internal step detail (PR number)
|
||||
# that isn't part of the anonymous-read contract. POST /graduate is
|
||||
# gated to RFC owners/arbiters and app admins/owners; the read SSE
|
||||
# shares that operator-visible surface and requires an authenticated
|
||||
# viewer. We keep the floor at require_user (not require_contributor)
|
||||
# so a write-muted operator can still observe a graduation they
|
||||
# kicked off before being muted.
|
||||
auth.require_user(request)
|
||||
state = _get_active(slug)
|
||||
if state is None:
|
||||
raise HTTPException(404, "No graduation in flight for this slug")
|
||||
|
||||
async def event_stream():
|
||||
# Emit the current snapshot first so a late subscriber sees
|
||||
# the steps already completed.
|
||||
yield _sse_event("snapshot", state.to_payload())
|
||||
if state.finished:
|
||||
yield _sse_event("done", state.to_payload())
|
||||
@@ -555,22 +435,16 @@ def make_router(
|
||||
# §13.1: POST /api/rfcs/<slug>/claim
|
||||
# Opens a meta-repo PR adding the actor's gitea_login to the entry's
|
||||
# owners list. Anyone signed in may claim — the merge is gated to
|
||||
# owners/admins per §13.1 (which collapses to admins for unclaimed
|
||||
# entries since `owners` is empty).
|
||||
# owners/admins per §13.1.
|
||||
# -------------------------------------------------------------------
|
||||
|
||||
@router.post("/api/rfcs/{slug}/claim")
|
||||
async def claim_ownership(slug: str, request: Request) -> dict[str, Any]:
|
||||
viewer = auth.require_contributor(request)
|
||||
rfc = _require_super_draft(slug)
|
||||
# Refuse if the actor is already in owners — no-op claim.
|
||||
existing_owners = json.loads(rfc["owners_json"] or "[]")
|
||||
if viewer.gitea_login in existing_owners:
|
||||
return {"ok": True, "noop": True}
|
||||
# Refuse if a claim PR for this actor is already open. The branch
|
||||
# name `claim/<slug>` collides per actor implicitly since Gitea
|
||||
# refuses duplicate branch creation; we surface a clean 409 here
|
||||
# so the client doesn't see a 502.
|
||||
already = db.conn().execute(
|
||||
"""
|
||||
SELECT pr_number FROM cached_prs
|
||||
@@ -581,8 +455,6 @@ def make_router(
|
||||
if already:
|
||||
raise HTTPException(409, f"A claim PR is already open: #{already['pr_number']}")
|
||||
|
||||
# Compose the new entry contents — owners list with the claimant
|
||||
# appended.
|
||||
fetched = await gitea.read_file(
|
||||
config.gitea_org, config.meta_repo, f"rfcs/{slug}.md", ref="main",
|
||||
)
|
||||
@@ -626,7 +498,7 @@ def make_router(
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Orchestrator
|
||||
# Orchestrator — the §13.3 in-place flip
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@@ -637,57 +509,21 @@ async def _orchestrate(
|
||||
bot: Bot,
|
||||
actor: Actor,
|
||||
state: GraduationState,
|
||||
super_draft_body: str,
|
||||
super_draft_title: str,
|
||||
super_draft_tags: list[str],
|
||||
graduated_contents: str,
|
||||
meta_file_sha: str,
|
||||
) -> None:
|
||||
"""Run §13.3 step by step. Each step:
|
||||
"""Open the flip PR, then merge it. Two steps, no transaction:
|
||||
|
||||
- marks itself `running` and pushes an event
|
||||
- calls the bot method (which writes to Gitea + audit log)
|
||||
- marks itself `done` (or `failed`) and pushes another event
|
||||
- open_pr fails → nothing was created; the entry stays a super-draft.
|
||||
- merge_pr fails → close the open PR and delete its branch (the only
|
||||
artifact a mid-flip failure can leave on the meta repo), then the
|
||||
entry stays a super-draft.
|
||||
|
||||
On failure at step N, every later step is marked `not-reached` and
|
||||
`_rollback` runs undoes in reverse from N-1 to 1.
|
||||
There is no rollback of a *merged* flip — once the meta-repo merge has
|
||||
landed, the path forward is §3's `withdraw` (§13.5).
|
||||
"""
|
||||
try:
|
||||
# ----- Step 1: create per-RFC repo -----
|
||||
await _start(state, "create_repo", f"Creating `{state.repo_full}`…")
|
||||
try:
|
||||
await bot.create_rfc_repo_for_graduation(
|
||||
actor, org=config.gitea_org, repo_name=state.repo_name,
|
||||
slug=state.slug, title=super_draft_title,
|
||||
)
|
||||
except GiteaError as e:
|
||||
await _fail(state, "create_repo", f"Gitea: {e.detail}")
|
||||
await _rollback(config=config, gitea=gitea, bot=bot, actor=actor,
|
||||
state=state, failed_at="create_repo")
|
||||
return
|
||||
await _done(state, "create_repo", state.repo_full)
|
||||
|
||||
# ----- Step 2: seed RFC.md, README.md, .rfc/metadata.yaml -----
|
||||
await _start(state, "seed_files", "Writing initial commit on main…")
|
||||
try:
|
||||
await bot.seed_graduated_rfc(
|
||||
actor,
|
||||
org=config.gitea_org, repo_name=state.repo_name,
|
||||
slug=state.slug, title=super_draft_title,
|
||||
rfc_body=super_draft_body, rfc_id=state.rfc_id,
|
||||
meta_full=config.meta_repo_full,
|
||||
meta_path=f"rfcs/{state.slug}.md",
|
||||
owners=state.owners, arbiters=state.arbiters,
|
||||
tags=super_draft_tags,
|
||||
)
|
||||
except GiteaError as e:
|
||||
await _fail(state, "seed_files", f"Gitea: {e.detail}")
|
||||
await _rollback(config=config, gitea=gitea, bot=bot, actor=actor,
|
||||
state=state, failed_at="seed_files")
|
||||
return
|
||||
await _done(state, "seed_files", "RFC.md, README.md, .rfc/metadata.yaml")
|
||||
|
||||
# ----- Step 3: open graduation PR -----
|
||||
# ----- Step 1: open the graduation PR (flip frontmatter) -----
|
||||
await _start(state, "open_pr", "Opening graduation PR…")
|
||||
try:
|
||||
pr = await bot.open_graduation_pr(
|
||||
@@ -696,19 +532,18 @@ async def _orchestrate(
|
||||
slug=state.slug,
|
||||
new_file_contents=graduated_contents,
|
||||
prior_sha=meta_file_sha,
|
||||
rfc_id=state.rfc_id, repo_full=state.repo_full,
|
||||
rfc_id=state.rfc_id,
|
||||
owners=state.owners,
|
||||
)
|
||||
except GiteaError as e:
|
||||
await _fail(state, "open_pr", f"Gitea: {e.detail}")
|
||||
await _rollback(config=config, gitea=gitea, bot=bot, actor=actor,
|
||||
state=state, failed_at="open_pr")
|
||||
await _finish_failed(state, failed_at="open_pr", on_behalf_of=actor.gitea_login)
|
||||
return
|
||||
state.new_pr_number = pr["number"]
|
||||
state.graduation_branch = pr["head"]["ref"]
|
||||
await _done(state, "open_pr", f"PR #{state.new_pr_number}")
|
||||
|
||||
# ----- Step 4: merge the graduation PR -----
|
||||
# ----- Step 2: merge the graduation PR -----
|
||||
await _start(state, "merge_pr", f"Merging PR #{state.new_pr_number}…")
|
||||
try:
|
||||
await bot.merge_graduation_pr(
|
||||
@@ -720,35 +555,28 @@ async def _orchestrate(
|
||||
)
|
||||
except GiteaError as e:
|
||||
await _fail(state, "merge_pr", f"Gitea: {e.detail}")
|
||||
await _rollback(config=config, gitea=gitea, bot=bot, actor=actor,
|
||||
state=state, failed_at="merge_pr")
|
||||
await _cleanup_unmerged(config=config, bot=bot, actor=actor, state=state)
|
||||
await _finish_failed(state, failed_at="merge_pr", on_behalf_of=actor.gitea_login)
|
||||
return
|
||||
await _done(state, "merge_pr", f"PR #{state.new_pr_number} merged")
|
||||
|
||||
# ----- Step 5: refresh the cache so the catalog flips immediately.
|
||||
# Per §13.3 step 5 the webhook flow is the steady-state path, but
|
||||
# we refresh inline so the dialog can transition to "graduation
|
||||
# complete" with the catalog row already showing `active`. A
|
||||
# cache-refresh failure does not unwind Git state — the
|
||||
# reconciler will catch up per §4.1.
|
||||
await _start(state, "refresh_cache", "Refreshing catalog and views…")
|
||||
# Refresh the cache so the catalog flips immediately. The webhook
|
||||
# flow is the steady-state path (§13.3); we refresh inline so the
|
||||
# dialog can transition to "graduation complete" with the catalog
|
||||
# row already showing `active`. A refresh failure does not unwind
|
||||
# the merge — the reconciler catches up per §4.1.
|
||||
try:
|
||||
await cache.refresh_meta_repo(config, gitea)
|
||||
await cache.refresh_meta_branches(config, gitea)
|
||||
await cache.refresh_meta_pulls(config, gitea)
|
||||
await cache.refresh_rfc_repo(config, gitea, state.slug)
|
||||
except Exception as e:
|
||||
log.warning("graduate refresh_cache failed for %s: %s", state.slug, e)
|
||||
await _done(state, "refresh_cache", f"Cache will catch up via reconciler ({e})")
|
||||
else:
|
||||
await _done(state, "refresh_cache", "Catalog and main view updated")
|
||||
log.warning("graduate cache refresh failed for %s: %s", state.slug, e)
|
||||
|
||||
# Terminal success row in the audit log.
|
||||
_audit(
|
||||
None, actor.gitea_login, "graduate_complete",
|
||||
rfc_slug=state.slug,
|
||||
details={
|
||||
"rfc_id": state.rfc_id, "repo": state.repo_full,
|
||||
"rfc_id": state.rfc_id,
|
||||
"owners": state.owners, "pr_number": state.new_pr_number,
|
||||
},
|
||||
)
|
||||
@@ -757,109 +585,38 @@ async def _orchestrate(
|
||||
await state.queue.put({"event": "completed", "payload": state.to_payload()})
|
||||
except Exception as e:
|
||||
log.exception("graduate: unexpected error for %s", state.slug)
|
||||
# Best-effort: mark the in-flight step failed, then roll back.
|
||||
running = next((s for s in state.steps if s.status == "running"), None)
|
||||
if running is not None:
|
||||
await _fail(state, running.key, f"unexpected: {e}")
|
||||
await _rollback(
|
||||
config=config, gitea=gitea, bot=bot, actor=actor,
|
||||
state=state, failed_at=running.key if running else "unknown",
|
||||
await _finish_failed(
|
||||
state, failed_at=running.key if running else "unknown",
|
||||
on_behalf_of=actor.gitea_login,
|
||||
)
|
||||
finally:
|
||||
# Push the sentinel so any open SSE handler returns.
|
||||
await state.queue.put(None)
|
||||
|
||||
|
||||
async def _rollback(
|
||||
*,
|
||||
config: Config, gitea: Gitea, bot: Bot, actor: Actor,
|
||||
state: GraduationState, failed_at: str,
|
||||
async def _cleanup_unmerged(
|
||||
*, config: Config, bot: Bot, actor: Actor, state: GraduationState,
|
||||
) -> None:
|
||||
"""Run undoes in reverse order from the last completed step. Each
|
||||
undo emits its own rollback-step event so the dialog can render the
|
||||
cleanup as a visible step appended to the stack per §13.3."""
|
||||
state.rollback_started = True
|
||||
# Mark every step after the failed one as not-reached so the rendered
|
||||
# stack is honest about what didn't run.
|
||||
seen_failure = False
|
||||
for s in state.steps:
|
||||
if s.status == "failed":
|
||||
seen_failure = True
|
||||
continue
|
||||
if seen_failure and s.status == "pending":
|
||||
s.status = "not-reached"
|
||||
|
||||
# Walk completed steps in reverse and run their inverses.
|
||||
for s in reversed(state.steps):
|
||||
if s.status != "done":
|
||||
continue
|
||||
undo = _UNDO_BY_STEP.get(s.key)
|
||||
if undo is None:
|
||||
continue
|
||||
rb = StepState(key=f"undo:{s.key}", label=f"Undo: {s.label}",
|
||||
status="running", detail="")
|
||||
state.rollback_steps.append(rb)
|
||||
await state.queue.put({"event": "rollback_step", "payload": state.to_payload()})
|
||||
try:
|
||||
detail = await undo(
|
||||
config=config, gitea=gitea, bot=bot, actor=actor, state=state,
|
||||
)
|
||||
except Exception as e:
|
||||
rb.status = "failed"
|
||||
rb.detail = f"{e}"
|
||||
await state.queue.put({"event": "rollback_step", "payload": state.to_payload()})
|
||||
continue
|
||||
rb.status = "done"
|
||||
rb.detail = detail or ""
|
||||
await state.queue.put({"event": "rollback_step", "payload": state.to_payload()})
|
||||
|
||||
_audit(
|
||||
None, actor.gitea_login, "graduate_rollback",
|
||||
rfc_slug=state.slug,
|
||||
details={
|
||||
"failed_at": failed_at,
|
||||
"error": state.error,
|
||||
"rfc_id": state.rfc_id,
|
||||
"repo": state.repo_full,
|
||||
"undone": [s.key for s in state.rollback_steps if s.status == "done"],
|
||||
},
|
||||
)
|
||||
state.finished = True
|
||||
state.succeeded = False
|
||||
await state.queue.put({"event": "rolled_back", "payload": state.to_payload()})
|
||||
|
||||
|
||||
async def _undo_create_repo(*, config, gitea, bot, actor, state) -> str:
|
||||
await bot.delete_rfc_repo(
|
||||
actor, org=config.gitea_org, repo_name=state.repo_name,
|
||||
slug=state.slug, reason="graduation rollback",
|
||||
)
|
||||
return f"Deleted `{state.repo_full}`"
|
||||
|
||||
|
||||
async def _undo_seed_files(*, config, gitea, bot, actor, state) -> str:
|
||||
# The seed commits live inside the per-RFC repo created in step 1;
|
||||
# deleting the repo (step 1's undo) reclaims them at the same time.
|
||||
# We surface a separate rollback step here so the rendered stack
|
||||
# mirrors the forward steps, but the work is folded into _undo_create_repo.
|
||||
return "Folded into repo deletion"
|
||||
|
||||
|
||||
async def _undo_open_pr(*, config, gitea, bot, actor, state) -> str:
|
||||
"""A merge failure leaves the flip PR open on its `graduate-<slug>-<hex>`
|
||||
branch. Close the PR and delete the branch so failed attempts don't
|
||||
accumulate on the meta repo. Best-effort — failures here are logged,
|
||||
not surfaced as a separate step (the entry already stays a super-draft).
|
||||
"""
|
||||
if state.new_pr_number is None:
|
||||
return "No PR opened"
|
||||
await bot.close_graduation_pr(
|
||||
actor,
|
||||
org=config.gitea_org, meta_repo=config.meta_repo,
|
||||
pr_number=state.new_pr_number,
|
||||
head_branch=state.graduation_branch or "",
|
||||
slug=state.slug, reason="graduation rollback",
|
||||
)
|
||||
# Per the §19.2 "graduation rollback's branch cleanup" candidate
|
||||
# that Slice 8 settles: delete the dash-suffixed branch on rollback
|
||||
# so failed-graduation branches don't accumulate on the meta repo.
|
||||
# The §12 hygiene sweep would catch this eventually, but closing
|
||||
# the loop here removes the chance of pile-up across retries.
|
||||
return
|
||||
try:
|
||||
await bot.close_graduation_pr(
|
||||
actor,
|
||||
org=config.gitea_org, meta_repo=config.meta_repo,
|
||||
pr_number=state.new_pr_number,
|
||||
head_branch=state.graduation_branch or "",
|
||||
slug=state.slug, reason="graduation merge failed",
|
||||
)
|
||||
except Exception:
|
||||
log.exception("graduate cleanup: close PR #%s failed", state.new_pr_number)
|
||||
branch_name = state.graduation_branch or ""
|
||||
if branch_name:
|
||||
try:
|
||||
@@ -870,24 +627,35 @@ async def _undo_open_pr(*, config, gitea, bot, actor, state) -> str:
|
||||
branch=branch_name,
|
||||
slug=state.slug,
|
||||
action_kind="delete_post_merge_branch",
|
||||
reason="graduation rollback",
|
||||
reason="graduation merge failed",
|
||||
)
|
||||
except Exception:
|
||||
log.exception("rollback: delete_branch failed for %s", branch_name)
|
||||
return f"Closed PR #{state.new_pr_number}"
|
||||
log.exception("graduate cleanup: delete_branch %s failed", branch_name)
|
||||
|
||||
|
||||
# merge_pr's undo is intentionally absent — once the meta-repo merge has
|
||||
# landed, graduation is irreversible per §13.5. If we ever reach a merged
|
||||
# state and a later step fails (which can't happen — refresh_cache failures
|
||||
# fold into success), there is no clean undo path; the user transitions
|
||||
# via §3's `withdraw` instead.
|
||||
|
||||
_UNDO_BY_STEP = {
|
||||
"create_repo": _undo_create_repo,
|
||||
"seed_files": _undo_seed_files,
|
||||
"open_pr": _undo_open_pr,
|
||||
}
|
||||
async def _finish_failed(state: GraduationState, *, failed_at: str, on_behalf_of: str) -> None:
|
||||
"""Mark any step after the failure as not-reached, write the audit
|
||||
row, and emit the terminal failed event."""
|
||||
seen_failure = False
|
||||
for s in state.steps:
|
||||
if s.status == "failed":
|
||||
seen_failure = True
|
||||
continue
|
||||
if seen_failure and s.status == "pending":
|
||||
s.status = "not-reached"
|
||||
_audit(
|
||||
None, on_behalf_of, "graduate_failed",
|
||||
rfc_slug=state.slug,
|
||||
details={
|
||||
"failed_at": failed_at,
|
||||
"error": state.error,
|
||||
"rfc_id": state.rfc_id,
|
||||
"pr_number": state.new_pr_number,
|
||||
},
|
||||
)
|
||||
state.finished = True
|
||||
state.succeeded = False
|
||||
await state.queue.put({"event": "failed", "payload": state.to_payload()})
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
@@ -907,7 +675,7 @@ def _can_graduate(rfc, viewer) -> bool:
|
||||
|
||||
def _audit(
|
||||
actor_user_id: int | None,
|
||||
on_behalf_of: str,
|
||||
on_behalf_of: str | None,
|
||||
action_kind: str,
|
||||
*,
|
||||
rfc_slug: str | None = None,
|
||||
@@ -918,7 +686,7 @@ def _audit(
|
||||
"""Direct audit-log write for graduation lifecycle events that don't
|
||||
correspond to a single Gitea write. The per-step Gitea writes log
|
||||
themselves via the bot's `_log`; this is for the bracketing
|
||||
`graduate_start` / `graduate_complete` / `graduate_rollback` rows."""
|
||||
`graduate_start` / `graduate_complete` / `graduate_failed` rows."""
|
||||
db.conn().execute(
|
||||
"""
|
||||
INSERT INTO actions
|
||||
@@ -935,8 +703,7 @@ def _audit(
|
||||
json.dumps(details) if details else None,
|
||||
),
|
||||
)
|
||||
# §15 chokepoint per Slice 6: the bracket rows (graduate_start,
|
||||
# graduate_complete) drive their own notifications per §15.1.
|
||||
# §15 chokepoint: the bracket rows drive their own notifications.
|
||||
from . import notify
|
||||
notify.fan_out_from_action(
|
||||
actor_user_id=actor_user_id,
|
||||
|
||||
Reference in New Issue
Block a user