# Component Methods — Master CMS Module

> Method signatures at the interface level. Detailed business rules and implementation logic are deferred to Functional Design (CONSTRUCTION phase).

---

## Unit 1 — master-backend

### ICmsInstanceRepository

| Method | Signature | Purpose |
|--------|-----------|---------|
| `GetAllAsync` | `Task<IReadOnlyList<CmsInstance>> GetAllAsync()` | Returns all registered slave CMS instances |
| `GetActiveAsync` | `Task<IReadOnlyList<CmsInstance>> GetActiveAsync()` | Returns all non-Inactive instances (used by integrity check) |
| `GetByIdAsync` | `Task<CmsInstance?> GetByIdAsync(Guid id)` | Returns instance by primary key; null if not found |
| `AddAsync` | `Task AddAsync(CmsInstance instance)` | Adds new entity to the change tracker |
| `UpdateAsync` | `Task UpdateAsync(CmsInstance instance)` | Marks entity as modified in the change tracker |
| `SaveChangesAsync` | `Task<int> SaveChangesAsync()` | Persists pending changes via `MasterDbContext` |

### ICmsInstanceService

| Method | Signature | Purpose |
|--------|-----------|---------|
| `GetAllAsync` | `Task<IReadOnlyList<CmsInstanceDto>> GetAllAsync()` | Returns all instances as DTOs; `ApiKey` excluded (NFR-MASTER-03) |
| `AddAsync` | `Task<CmsInstanceDto> AddAsync(CreateCmsInstanceRequest request)` | Creates entity, persists, triggers auto-registration with slave (FR-MASTER-03); returns DTO |
| `UpdateStatusAsync` | `Task UpdateStatusAsync(Guid id, CmsInstanceStatus status, string? disableMessage)` | Updates entity status, persists, pushes status to slave via HTTP (FR-MASTER-05); `disableMessage` required when `status = NotAvailable` (FR-MASTER-14) |
| `VerifyIntegrityAsync` | `Task VerifyIntegrityAsync()` | Called by `IntegrityCheckBackgroundService`; checks all active slaves have correct master URL; re-registers if mismatch (FR-MASTER-04) |

### ISlaveApiClient

| Method | Signature | Purpose |
|--------|-----------|---------|
| `RegisterMasterAsync` | `Task<bool> RegisterMasterAsync(string slaveUrl, string apiKey, string masterUrl)` | POST `/api/internal/master/register` on slave; returns `true` on success (FR-MASTER-03) |
| `PushStatusAsync` | `Task<bool> PushStatusAsync(string slaveUrl, string apiKey, CmsInstanceStatus status, string? disableMessage)` | Pushes new status to slave's availability endpoint; returns `true` on success (FR-MASTER-05) |
| `GetRegisteredMasterUrlAsync` | `Task<string?> GetRegisteredMasterUrlAsync(string slaveUrl, string apiKey)` | GET slave's currently registered master URL; used for integrity check (FR-MASTER-04); null if no master registered |

### IntegrityCheckBackgroundService

| Method | Signature | Purpose |
|--------|-----------|---------|
| `ExecuteAsync` | `override Task ExecuteAsync(CancellationToken stoppingToken)` | Main background loop; uses `PeriodicTimer` with interval from `MasterModuleOptions.IntegrityCheckIntervalMinutes`; creates `IServiceScope` per tick to resolve scoped services |

### CmsInstanceController

| Method | HTTP | Route | Purpose |
|--------|------|-------|---------|
| `GetAll` | GET | `/api/v1/CmsInstances` | Returns `IReadOnlyList<CmsInstanceDto>` |
| `Add` | POST | `/api/v1/CmsInstances` | Body: `CreateCmsInstanceRequest`; returns created `CmsInstanceDto` (201) |
| `UpdateStatus` | PUT | `/api/v1/CmsInstances/{id}/status` | Body: `UpdateStatusRequest`; returns 200 OK or 404 if not found |

---

## Unit 2 — slave-availability-extension

### IMasterAvailabilityService

| Method | Signature | Purpose |
|--------|-----------|---------|
| `GetMasterStatusAsync` | `Task<MasterGateResult> GetMasterStatusAsync()` | Checks DB for `MasterRegistration`; if no registration → returns `HasMaster = false`; if registration exists → returns cached or freshly-pulled status with fail-open fallback |

### MasterGateResult

| Property | Type | Purpose |
|----------|------|---------|
| `HasMaster` | `bool` | Whether a master URL is registered on this slave |
| `Status` | `CmsInstanceStatus?` | Master-controlled status (null when `HasMaster = false`) |
| `DisableMessage` | `string?` | Message to include in 503 when `Status = NotAvailable` |

### AvailabilityController (new method)

| Method | HTTP | Route | Purpose |
|--------|------|-------|---------|
| `RegisterMaster` | POST | `/api/internal/master/register` | Header: `X-Master-Api-Key`; Body: `RegisterMasterRequest`; validates key, upserts `MasterRegistration`; returns 200 OK or 401 Unauthorized |

### RegisterMasterRequest

| Property | Type | Notes |
|----------|------|-------|
| `MasterUrl` | `string` | Base URL of the Master CMS |

### AvailabilityMiddleware.InvokeAsync (extended signature)

```csharp
public async Task InvokeAsync(
    HttpContext context,
    IAvailabilityService availabilityService,
    IMasterAvailabilityService masterAvailabilityService)
```

---

## Unit 3 — frontend-cms-page

### useCmsInstances

```typescript
function useCmsInstances(): UseQueryResult<CmsInstance[], Error>
```

### useAddCmsInstance

```typescript
interface CreateCmsInstancePayload {
    name: string;
    url: string;
    apiKey: string;
}

function useAddCmsInstance(): UseMutationResult<CmsInstance, Error, CreateCmsInstancePayload>
```

### useUpdateCmsInstanceStatus

```typescript
interface UpdateStatusPayload {
    id: string;
    status: CmsInstanceStatus;
    disableMessage?: string;
}

function useUpdateCmsInstanceStatus(): UseMutationResult<void, Error, UpdateStatusPayload>
```

### CmsInstance (TypeScript)

```typescript
interface CmsInstance {
    id: string;
    name: string;
    url: string;
    status: CmsInstanceStatus;
    disableMessage?: string;
    lastContactedAt?: string;     // ISO 8601
    lastStatusPushedAt?: string;  // ISO 8601
}

enum CmsInstanceStatus {
    Available = 'Available',
    NotAvailable = 'NotAvailable',
    Inactive = 'Inactive',
}
```