Skip to content

Commit b2e8c14

Browse files
committed
docs(design): promote admin dashboard from _partial_ to _implemented_
Per docs/design/README.md's lifecycle convention. The original P1–P4 plan has fully shipped: - P1 (admin skeleton + Dynamo + AdminForward) — #634/#635/#644/#648 - P2 (S3 endpoints incl. write paths and AdminForward integration) — #658 / #669 / #673 / #695 (TOCTOU safety net) - P3 (React SPA + embed) — #649 / #650 - P4 (TLS / role / CSRF / operator doc / deployment runbook / scripts/rolling-update.sh admin support) — #674 / #669 / #678 The AdminDeleteBucket TOCTOU caught during PR #669 review (the last "in-flight" item that kept the doc at _partial_) is fully resolved by the safety-net design landed in #695. What changed: - git mv 2026_04_24_partial_admin_dashboard.md → 2026_04_24_implemented_admin_dashboard.md (history follows the rename) - Header Status line: "Partial" → "Implemented", explanation updated to reflect the post-fix state and the rationale for promotion. - "Last updated" bumped to 2026-04-28 with the rename trigger. - Section heading "Outstanding open items" → "Out-of-scope follow-ups" — the remaining three entries (criterion 5, object browser, TLS hot-reload) are not in-flight work; they are deferred-at-design or Non-goal items. The TOCTOU bullet is removed (resolved) and replaced with a one-line cross-link to the safety-net design + admin_deployment.md §4.6 contract. - Removed the closing "rename trigger" sentence — we just did the rename. - Status table: P2 row now lists #695 alongside #658/#669/#673 so a future reader can find the TOCTOU fix from the index. - Cross-references updated everywhere the old filename appeared: docs/admin.md (header link + Cross-references) docs/admin_deployment.md (header link + final cross-ref) docs/design/2026_04_28_proposed_admin_delete_bucket_safety_net.md (Background section pointer) internal/admin/config.go (Section 7.1 reference comment) No code changes other than the comment-only filename refresh in config.go.
1 parent 4e3fdb8 commit b2e8c14

5 files changed

Lines changed: 16 additions & 17 deletions

File tree

docs/admin.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
This document covers configuration and day-2 operation of the admin
44
HTTP listener. Architecture and design rationale live in
5-
[docs/design/2026_04_24_proposed_admin_dashboard.md](design/2026_04_24_proposed_admin_dashboard.md);
5+
[docs/design/2026_04_24_implemented_admin_dashboard.md](design/2026_04_24_implemented_admin_dashboard.md);
66
read that first if you're touching the code.
77

88
## What the admin dashboard is
@@ -336,6 +336,6 @@ to populate the embedded `dist` directory, then rebuild the binary.
336336
## Cross-references
337337

338338
- Deployment runbook: [docs/admin_deployment.md](admin_deployment.md) (login flow, rollout via `scripts/rolling-update.sh`, key/TLS rotation, failure-mode runbooks)
339-
- Design rationale: [docs/design/2026_04_24_proposed_admin_dashboard.md](design/2026_04_24_proposed_admin_dashboard.md) (renamed to `_partial_` in PR #675; this link will follow once that lands)
339+
- Design rationale: [docs/design/2026_04_24_implemented_admin_dashboard.md](design/2026_04_24_implemented_admin_dashboard.md)
340340
- Architecture overview: [docs/architecture_overview.md](architecture_overview.md)
341341
- AdminForward RPC contract: `proto/admin_forward.proto`

docs/admin_deployment.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ read [`docs/admin.md`](admin.md) first — this doc assumes you have
1111
already skimmed it.
1212

1313
For design rationale, see
14-
[`docs/design/2026_04_24_partial_admin_dashboard.md`](design/2026_04_24_partial_admin_dashboard.md).
14+
[`docs/design/2026_04_24_implemented_admin_dashboard.md`](design/2026_04_24_implemented_admin_dashboard.md).
1515

1616
---
1717

@@ -402,7 +402,7 @@ mean the cluster has lost quorum.
402402

403403
- [`docs/admin.md`](admin.md) — per-flag configuration reference,
404404
audit log shapes, troubleshooting catalogue.
405-
- [`docs/design/2026_04_24_partial_admin_dashboard.md`](design/2026_04_24_partial_admin_dashboard.md)
405+
- [`docs/design/2026_04_24_implemented_admin_dashboard.md`](design/2026_04_24_implemented_admin_dashboard.md)
406406
design rationale, acceptance criteria, outstanding items.
407407
- [`scripts/rolling-update.sh`](../scripts/rolling-update.sh)
408408
the rollout driver this doc references throughout.

docs/design/2026_04_24_partial_admin_dashboard.md renamed to docs/design/2026_04_24_implemented_admin_dashboard.md

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,26 @@
11
# elastickv Admin Dashboard Design
22

3-
**Status:** Partial — every phase of the original P1–P4 plan has shipped. The doc stays at `_partial_` (rather than `_implemented_`) because AdminForward acceptance criterion 5 (rolling-upgrade compatibility flag) is explicitly deferred and the AdminDeleteBucket TOCTOU caught during PR #669 review is tracked here as a pre-existing limitation. See the status table for the per-phase breakdown and Outstanding open items below.
3+
**Status:** Implemented — every phase of the original P1–P4 plan has shipped, the AdminDeleteBucket TOCTOU caught during PR #669 review is fixed (PR #695 with the two-phase split required by the production coordinator's dispatch validation), and operator documentation + deployment tooling are in place. The remaining items in §"Out-of-scope follow-ups" below are either explicitly deferred at design time or were called out as Non-goals in §2.2; none block dashboard usability today.
44
**Author:** bootjp
55
**Date:** 2026-04-24
6-
**Last updated:** 2026-04-27 (P2 write paths + P4 operator doc landed; status table refreshed)
6+
**Last updated:** 2026-04-28 (renamed from `_partial_` to `_implemented_` after PR #695 landed the TOCTOU safety-net fix)
77

8-
## Implementation status (as of 2026-04-27)
8+
## Implementation status (as of 2026-04-28)
99

1010
| Phase | Status | Landed via |
1111
|---|---|---|
12-
| **P1**`internal/admin/` skeleton, auth, DynamoDB list/create/describe/delete, AdminForward (Section 3.3 acceptance criteria 1–4 + 6; criterion 5 deferred — see outstanding items) | ✅ shipped | #634, #635, #644, #648 |
13-
| **P2** — S3 bucket list/create/delete/ACL, DescribeTable | ✅ shipped | #658 (read-only slice 1) + #669 (writes, slice 2a) + #673 (AdminForward integration, slice 2b) |
12+
| **P1**`internal/admin/` skeleton, auth, DynamoDB list/create/describe/delete, AdminForward (Section 3.3 acceptance criteria 1–4 + 6; criterion 5 deferred — see follow-ups) | ✅ shipped | #634, #635, #644, #648 |
13+
| **P2** — S3 bucket list/create/delete/ACL, DescribeTable | ✅ shipped | #658 (read-only slice 1) + #669 (writes, slice 2a) + #673 (AdminForward integration, slice 2b) + #695 (AdminDeleteBucket TOCTOU safety net) |
1414
| **P3** — React SPA + embed | ✅ shipped | #649, #650 |
1515
| **P4** — TLS, read-only role, CSRF, `docs/admin.md`, deployment runbook + `scripts/rolling-update.sh` admin support | ✅ shipped | TLS / role / CSRF live in P1; operator doc + runbook + script wiring in #674 / #669 / #678 |
1616

17-
Outstanding open items (kept here so future readers know what is still owed against the original proposal):
17+
Out-of-scope follow-ups (recorded so future readers know what was deliberately deferred):
1818

19-
- **AdminForward acceptance criterion 5** — rolling-upgrade compatibility flag (`admin.leader_forward_v2`). Deferred behind a cluster-version bump; not blocking dashboard usability today because every node forwards through the same `pb.AdminOperation` enum.
20-
- ~~AdminDeleteBucket TOCTOU~~**fixed**. The empty-probe → commit race is now covered by a `DEL_PREFIX` safety net on the same `OperationGroup`: `AdminDeleteBucket` and `s3.go:deleteBucket` both wipe every per-bucket key family (manifest / upload-meta / upload-part / blob / gc-upload / route) at the shared commitTS, so objects that landed in the race window are tombstoned together with `BucketMetaKey` instead of orphaning. Trade-off: a `PutObject` that returned 200 OK during the race window can be swept by the concurrent delete — operators should pause writes before bucket delete (now documented in `docs/admin_deployment.md` §4.6). See [`2026_04_28_proposed_admin_delete_bucket_safety_net.md`](2026_04_28_proposed_admin_delete_bucket_safety_net.md) for the design.
21-
- **S3 object browser** — explicitly called out as "next phase" in Section 2 Non-goals; no work item yet.
19+
- **AdminForward acceptance criterion 5** — rolling-upgrade compatibility flag (`admin.leader_forward_v2`). Deferred at design time behind a cluster-version bump that does not exist yet; not blocking dashboard usability today because every node forwards through the same `pb.AdminOperation` enum.
20+
- **S3 object browser** — explicitly called out as "next phase" in §2.2 Non-goals; no work item yet.
2221
- **Operator-visible TLS cert reload** — out of scope; restart-to-rotate is the documented model in `docs/admin.md`.
2322

24-
When the rolling-upgrade flag (the only remaining functional blocker after the TOCTOU fix landed) is addressed, this doc is renamed `2026_04_24_implemented_admin_dashboard.md` per `docs/design/README.md`'s lifecycle convention.
23+
The AdminDeleteBucket TOCTOU is fully resolved: see [`2026_04_28_proposed_admin_delete_bucket_safety_net.md`](2026_04_28_proposed_admin_delete_bucket_safety_net.md) for the safety-net design and [`docs/admin_deployment.md`](../admin_deployment.md) §4.6 for the operator-side contract (a `PutObject` 200-OK landing during the race window can be swept by the concurrent admin delete; pause writes before delete to retain in-flight writes).
2524

2625
---
2726

docs/design/2026_04_28_proposed_admin_delete_bucket_safety_net.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@
88

99
`AdminDeleteBucket` and the SigV4 `s3.go:deleteBucket` share a known
1010
TOCTOU race documented in
11-
[`docs/design/2026_04_24_partial_admin_dashboard.md`](2026_04_24_partial_admin_dashboard.md)
12-
under Outstanding open items. coderabbitai 🔴/🟠 flagged it during PR
11+
[`docs/design/2026_04_24_implemented_admin_dashboard.md`](2026_04_24_implemented_admin_dashboard.md)
12+
under Out-of-scope follow-ups. coderabbitai 🔴/🟠 flagged it during PR
1313
#669 review.
1414

1515
The current shape:

internal/admin/config.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ const (
1515
)
1616

1717
// Config captures everything the admin listener needs at startup. It mirrors
18-
// the Section 7.1 table in docs/design/2026_04_24_proposed_admin_dashboard.md
18+
// the Section 7.1 table in docs/design/2026_04_24_implemented_admin_dashboard.md
1919
// and intentionally uses plain Go fields rather than a config library so the
2020
// existing flag-based wiring in main.go can hand values over without a new
2121
// dependency.

0 commit comments

Comments
 (0)