slp-modular-cms/aidlc-docs/features/master-cms-module/construction/plans/slave-availability-extension-functional-design-plan.md

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

---

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 — MasterRegistration entity + relationship to AvailabilityDbContext
• 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