120 lines
5.4 KiB
Markdown
120 lines
5.4 KiB
Markdown
# Functional Design Plan — Unit 2: slave-availability-extension
|
|
|
|
## Unit Context
|
|
|
|
**Unit**: `slave-availability-extension`
|
|
**Project**: `src/SlpModularCms.Modules.Availability/` (EXTENDED — existing project)
|
|
**Test Project**: `src/SlpModularCms.Modules.Availability.Master.Tests/` (NEW)
|
|
**Construction Cycle**: Functional Design → NFR Requirements → NFR Design → Code Generation
|
|
|
|
**What this unit does**: Extends the slave CMS so it can:
|
|
1. Accept registrations from a master CMS (store master URL)
|
|
2. Receive status pushes from master (cache available/unavailable)
|
|
3. Return the registered master URL (for integrity checks from master)
|
|
4. Block requests via a two-phase middleware gate (master gate outer + local gate inner)
|
|
|
|
**Endpoint contract (fixed by Unit 1 SlaveApiClient)**:
|
|
- `POST /api/v1/master/register` — receive master registration
|
|
- `POST /api/v1/master/status` — receive status push from master
|
|
- `GET /api/v1/master/registered-url` — return currently registered master URL
|
|
|
|
---
|
|
|
|
## Questions
|
|
|
|
Answer each question by filling in your choice after the `[Answer]:` tag.
|
|
|
|
---
|
|
|
|
### Q1 — API Key Validation: How does the slave authenticate incoming master requests?
|
|
|
|
The master sends an `X-Master-Api-Key` header on every call. The slave must validate this. Where does the slave get the expected key to compare against?
|
|
|
|
A) **Configuration-based** — slave admin sets the expected key in `appsettings.json` under `Availability:MasterApiKey`. The key is shared out-of-band when setting up the master/slave relationship. Simple and explicit.
|
|
|
|
B) **Stored at first registration** — slave accepts the first registration request unconditionally and stores the API key from the header. Subsequent calls (status push, registered-url) validate against this stored key. No pre-configuration needed.
|
|
|
|
C) **No validation** — slave trusts all requests to master endpoints (relies on network security). Simpler but less secure.
|
|
|
|
D) Other
|
|
|
|
[Answer]: B
|
|
|
|
---
|
|
|
|
### Q2 — No Master Registered: What happens when a slave has never been registered with a master?
|
|
|
|
If no registration exists in the `MasterRegistrations` table, what should the master gate do?
|
|
|
|
A) **Fail-open** — no registration means master gate passes (slave is Available from master's perspective). This is safe: a fresh slave not yet connected to a master is fully accessible. Consistent with the fail-open philosophy from the requirements.
|
|
|
|
B) **Fail-closed** — no registration means master gate blocks (slave is unavailable until a master registers it). More secure but breaks fresh deployments.
|
|
|
|
C) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Q3 — Master Gate: Which paths bypass the master gate?
|
|
|
|
The master gate blocks incoming requests when master says slave is unavailable. Which paths should always bypass it?
|
|
|
|
A) **Same as local gate + master endpoints** — bypass the same paths already in `_bypassPrefixes` (Auth, Setup, Availability/status) AND add `/api/v1/master/` so master can always push status or re-register even when gate is closed.
|
|
|
|
B) **All internal API paths** — bypass everything under `/api/v1/master/` and `/api/v1/Availability/` (broader bypass for any "system" paths).
|
|
|
|
C) **Master endpoints only** — only `/api/v1/master/` bypasses the master gate; keep Auth/Setup/Availability bypass only in the local gate where it already lives.
|
|
|
|
D) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Q4 — Master Status Cache: When does the cached master status expire?
|
|
|
|
When the master pushes a status to the slave, the slave stores it in a static field. How long is it valid?
|
|
|
|
A) **No expiry** — cache never expires; only updated when master pushes again. If master goes offline permanently, last known status is used forever. Simplest implementation; consistent with fail-open (default = Available).
|
|
|
|
B) **Configurable expiry** — add `MasterCacheMinutes` to `AvailabilityOptions`; after expiry, status reverts to Available (fail-open). Allows fresh slaves to auto-recover if master disappears.
|
|
|
|
C) **Timestamp-based expiry (same as existing circuit breaker)** — static field with `_lastMasterUpdateTime`; if older than `CacheMinutes`, revert to Available.
|
|
|
|
D) Other
|
|
|
|
[Answer]: A
|
|
|
|
---
|
|
|
|
### Q5 — MasterRegistration Entity: What data does it store?
|
|
|
|
The `MasterRegistrations` table on the slave stores data about the registered master. What fields are needed?
|
|
|
|
A) **Minimal** — `Id` (Guid PK), `MasterUrl` (string). Just the URL needed for integrity check response. The API key (Q1) is stored in config, not DB.
|
|
|
|
B) **Extended** — `Id` (Guid PK), `MasterUrl` (string), `RegisteredAt` (DateTimeOffset), `LastContactedAt` (DateTimeOffset?). More diagnostic info; useful for monitoring.
|
|
|
|
C) Other
|
|
|
|
[Answer]: B
|
|
|
|
---
|
|
|
|
## Execution Steps
|
|
|
|
After all questions above are answered, the following artifacts will be generated:
|
|
|
|
- [x] **Step 1** — Analyze answers; flag ambiguities
|
|
- [x] **Step 2** — Generate `domain-entities.md` — `MasterRegistration` entity + relationship to `AvailabilityDbContext`
|
|
- [x] **Step 3** — Generate `business-logic-model.md` — sequence diagrams for: register, status push, get-registered-url, middleware gate evaluation
|
|
- [x] **Step 4** — Generate `business-rules.md` — validation rules, gate bypass logic, cache behavior, API key validation
|
|
- [x] **Step 5** — Validate all Mermaid diagrams
|
|
- [ ] **Step 6** — Update `aidlc-state.md`
|
|
- [ ] **Step 7** — Present completion message for approval
|
|
|
|
---
|
|
|
|
*Artifact path*: `aidlc-docs/features/master-cms-module/construction/plans/slave-availability-extension-functional-design-plan.md`
|