feat(api): complete gateway route lifecycle

[seonghobae]

Preservation / reconstruction state — 2026-09-08 KST

This PR remains Draft and is not an integration candidate on its current ancestry. It preserves a reviewed Wardnet-owned gateway route/DNSBL resource-lifecycle slice: item-level reads, conditional replace/delete, ETag/If-Match concurrency, write/read-only authorization distinction, persistence/audit evidence, OpenAPI 3.1 contracts, and hostile edge tests.

Fresh protected/default truth is main@a52ccd0a24a727d9349bb32def7713882d8cad1e. Current branch is exact bab3c72bb72e041ad494932ae07b0fb2401991ec from obsolete merge base 107117634764c901dff540044585d64088fafedb. Fresh protected-main comparison is diverged, ahead 11 / behind 8, and GitHub reports the PR non-mergeable. The current protected-main-relative delta is three paths: docs/api-inventory.md (+40), docs/openapi.yaml (+169), and src/lib.rs (+743/-32). Do not mechanically merge this stale aggregate source into protected main and do not close it until the valid unique delta is completely transferred or proven obsolete.

Reviewed behavior to preserve

The branch's historical review findings are all resolved/outdated in the live thread inventory. Valid repaired contracts that a successor must retain or explicitly supersede include:

• rejected 404/412/428 conditional mutations do not rewrite persistent state or mask the intended HTTP status on persistence failure;
• RFC 9110 If-Match: * semantics and missing-resource behavior;
• authorization failures distinguish invalid/missing credentials (401) from authenticated read-only mutation attempts (403) consistently;
• route and DNSBL DELETE contracts model missing If-Match as a runtime-reachable 428 rather than making generated clients reject the request before transmission;
• malformed DNSBL item addresses return the JSON error contract with write authorization precedence preserved;
• conditional mutation remains atomic across check/mutate/persist/rollback;
• ETag generation is currently deterministic because the serialized resource contains no unordered map/set fields; a successor must not silently weaken that invariant;
• OpenAPI status/threshold contracts must match runtime behavior.

Historical exact-head CI 33119527141, Fuzz 33119527052, Security 33119527071, and SAST 33119527274 are terminal SUCCESS on bab3c72..., but they predate current protected ancestry and central governance/workflow contracts. They are preservation evidence only and do not transfer to a reconstructed head.

Reconstruction order and ownership

Rebuild from the exact then-current protected main, not by copying this stale src/lib.rs wholesale. Protected authentication/runtime/configuration and gateway fixes that landed or are carried by newer bounded lanes must be adopted first. Reconcile this resource-lifecycle behavior with #155 management-authentication authority, #140 Runtime Configuration, #93 deterministic persistence-fault seam, and protected/new gateway route semantics such as #181. Preserve only the route/DNSBL lifecycle API delta that remains unique after that comparison.

Wardnet owns this management API lifecycle, persistence coordination and audit evidence. EgressWeave outbound transport authorization, Keyverse identity backend, quarantine execution, contextual-orchestrator LLM/provider orchestration and AppGuardrail static analysis remain separate owner authorities.

A bounded successor must add/replay hostile REDs against current protected behavior before causal implementation, publish code-current OpenAPI/architecture docs, and reacquire exact-head format/locked workspace tests/Clippy, owned coverage, fuzz, Security/SAST/CodeQL/Strix/review/thread/candidate-base/governance evidence. No self/model approval, routine administrator bypass, gate weakening, force push/destructive rebase, predecessor-result transfer, stale aggregate merge, mutable foreign dependency, source copy or cross-service SQL.

[coderabbitai]

📝 Walkthrough

Walkthrough

라우트와 DNSBL 항목의 조회·교체·삭제 API를 추가했습니다. ETag와 If-Match로 조건부 변경을 적용했습니다. RBAC 오류, 영속화 롤백, 감사 로그, OpenAPI 계약 및 통합 테스트를 추가했습니다.

Changes

라우트 및 DNSBL 항목 API

Layer / File(s)	Summary
API 계약과 오류 응답 docs/api-inventory.md, docs/openapi.yaml	라우트와 DNSBL 항목의 HTTP 계약을 추가했습니다. AdminToken, Route, Error, ETag, If-Match 및 상태별 오류 응답을 정의했습니다.
변경 영속화와 권한 처리 src/lib.rs	변경 함수와 영속화가 실패하면 상태를 롤백하도록 했습니다. 관리 쓰기 권한이 없는 요청은 인증 상태에 따라 401 또는 403을 반환합니다.
라우트 및 DNSBL 핸들러 구현 src/lib.rs	항목별 조회·교체·삭제 경로를 연결했습니다. ETag 검증, 주소 형식 및 식별자 검증, 204 삭제 응답, 감사 로그를 구현했습니다.
통합 동작 검증 src/lib.rs	조건부 변경, DNSBL 주소 검증, RBAC, 오류 상태, 삭제 감사 로그 및 영속성 관련 동작을 검증했습니다.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🔵 Low · up to 8e762

The PR adds route lifecycle operations and API contract updates, but the current head still has bounded integration issues: generated clients may reject valid DNSBL delete requests, DNSBL responses are weakly typed, and read-only users may be blocked from viewing job status. The change is mergeable with explicit owner follow-up on these contract and read-access inconsistencies.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ResourceAPI
  participant AdminWriteAuth
  participant Persistence
  participant AuditLog
  Client->>ResourceAPI: 라우트 또는 DNSBL 조회·교체·삭제 요청
  ResourceAPI->>AdminWriteAuth: 관리자 쓰기 권한 검증
  AdminWriteAuth-->>ResourceAPI: 인증 및 권한 결과
  ResourceAPI->>ResourceAPI: ETag와 If-Match 검증
  ResourceAPI->>Persistence: 상태 변경 및 영속화
  Persistence-->>ResourceAPI: 성공 또는 오류
  ResourceAPI->>AuditLog: 성공한 교체·삭제 기록
  ResourceAPI-->>Client: 리소스 응답 또는 HTTP 상태

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 34.15% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 41 functions across 1 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 게이트웨이 라우트의 조회, 조건부 교체, 삭제를 포함한 전체 수명 주기 지원이라는 주요 변경을 정확하게 요약합니다.

Full details: Docstring Coverage

Explanation

Docstring coverage is 34.15% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 41 functions across 1 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/operator-resource-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 0 new potential issues.

[devin-ai-integration]

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

Devin Review found 0 new potential issues.

[devin-ai-integration]

Devin Review found 0 new potential issues.

[seonghobae]

Fresh repair-first state (2026-09-05 KST): converted to Draft because exact head bab3c72bb72e041ad494932ae07b0fb2401991ec is non-mergeable against obsolete main@107117634764c901dff540044585d64088fafedb, while protected truth is main@5829a0f08d78de464dd24393ce5d0f25fba9d126. The three-file route-lifecycle delta is not discarded or closed. Reconstruct non-force from fresh protected main, preserve conditional GET/PUT/DELETE + ETag/If-Match/RBAC/persistence/audit/OpenAPI/edge-test behavior, add hostile concurrency/replay/auth regressions first where current main changed the same surfaces, then reacquire exact-head repository/security/coverage/package/SBOM/provenance/review/thread evidence. No predecessor evidence or forced history transfer.

[seonghobae]

Architecture/base repair finding, 2026-09-06 KST. This Draft is still exact bab3c72bb72e041ad494932ae07b0fb2401991ec on obsolete base snapshot main@107117634764c901dff540044585d64088fafedb; live protected/default main is a52ccd0a24a727d9349bb32def7713882d8cad1e, and GitHub reports the old aggregate branch non-mergeable. Do not close it and do not mechanically import the stale src/lib.rs wholesale.

Fresh patch inventory proves the unique customer/API slice to preserve is confined to three paths: docs/api-inventory.md, docs/openapi.yaml, and src/lib.rs. Within src/lib.rs, the item-level route/DNSBL GET/conditional PUT/DELETE, ETag/If-Match optimistic concurrency, persistence rollback/audit and edge regressions remain useful. However the same old branch also introduces and applies management_write_denied across many unrelated management endpoints. That write-capable/read-only authentication foundation is now canonically owned by #155, whose exact current head fb93b61a4a4da30a3471453051ebfb0ed3f63d34 has CI/Fuzz/Security/SAST GREEN and is waiting only on central CodeQL verdict/governance. #112 must not become a competing auth owner.

Repair order: keep this preservation lane Draft; integrate #155 through ordinary protected governance first; then start from fresh protected main, transfer the route/DNSBL item-resource behavior and OpenAPI/inventory contract only, adopt #155's protected authentication semantics rather than copying this branch's old global RBAC edits, add/revalidate hostile conditional-write/persistence/audit tests against the current DNSBL ownership model, and reacquire exact-head gates. The current stale branch is evidence/preservation authority only until that bounded successor fully transfers every still-valid route/DNSBL delta.