# 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`