feat(api): complete gateway route lifecycle

[seonghobae]

Summary

• inventory Wardnet's current customer/operator HTTP surface and concrete remaining lifecycle gaps
• add item-level GET, conditional PUT, and conditional DELETE for gateway routes
• preserve legacy POST /api/routes upsert behavior while adding ETag/If-Match concurrency, write/read-only RBAC distinction, persistence, and audit evidence
• publish an OpenAPI 3.1 route contract and edge tests

Verification

• cargo fmt --check
• cargo test (102 library tests plus integration and fuzz-invariant tests)
• git diff --check

Compatibility and scope

Existing collection responses and legacy route upserts are unchanged. The new item endpoints require If-Match only when replacing or deleting an existing route. This slice does not invent WAF/IDS detection logic or routing algorithms, so it does not add an academic-paper artifact; the inventory explicitly leaves those research-grounded product slices for their owning changes.

---

Summary by CodeRabbit

• 새로운 기능

  • 라우트와 DNSBL 항목별 조회·교체·삭제 API를 제공합니다.
  • ETag 및 If-Match 기반 동시성 제어를 지원합니다.
  • 관리자 인증과 읽기 전용 권한에 따른 접근 제어를 적용합니다.
  • 변경 성공 시 감사 로그를 기록합니다.

• 문서

  • OpenAPI 3.1 계약, 인증 방식과 오류 응답을 문서화했습니다.
  • API 동작 및 남은 수명주기 공백을 정리했습니다.

• 버그 수정

  • 잘못된 요청, 인증·권한 오류와 리소스 불일치를 적절한 상태 코드로 반환합니다.
  • 변경 실패 시 상태를 안전하게 복원합니다.

[coderabbitai]

Warning

Review limit reached

Next included review available in 59 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2e645104-d1ee-43e5-9437-aaf1b9be3cf2

📥 Commits

Reviewing files that changed from the base of the PR and between 8e7625f and bab3c72.

📒 Files selected for processing (2)

• docs/openapi.yaml
• src/lib.rs

📝 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 게이트웨이 라우트의 조회·조건부 교체·삭제와 기존 upsert 동작을 포함한 주요 변경 사항을 명확하고 간결하게 요약합니다.
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.

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.)

✨ 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.