5.4 KiB
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:
- Accept registrations from a master CMS (store master URL)
- Receive status pushes from master (cache available/unavailable)
- Return the registered master URL (for integrity checks from master)
- 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 registrationPOST /api/v1/master/status— receive status push from masterGET /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
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
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
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
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
Execution Steps
After all questions above are answered, the following artifacts will be generated:
- Step 1 — Analyze answers; flag ambiguities
- Step 2 — Generate
domain-entities.md—MasterRegistrationentity + relationship toAvailabilityDbContext - Step 3 — Generate
business-logic-model.md— sequence diagrams for: register, status push, get-registered-url, middleware gate evaluation - Step 4 — Generate
business-rules.md— validation rules, gate bypass logic, cache behavior, API key validation - 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