SluijsensandClaude Sonnet 5
0447993181
Frontend (Unit 2 completion): dual dev-server tooling (pnpm dev:slave, pnpm dev:all), per-instance browser tab titles, and a backend capability check (SystemController + useSystemCapabilities + ModuleGuard) so a Master-only page is hidden on a slave instance instead of assuming every backend has every module. Master/slave protocol fixes surfaced by actually running master and slave side by side locally: - Deactivating a CMS instance (Inactive) now releases the slave's master gate instead of leaving it stuck on its last pushed status. - The periodic integrity check now also re-pushes status to every reachable slave (previously URL-verification only) and runs once immediately on startup. - Added the originally-specified (but never implemented) slave-pull path: a slave now periodically polls its own status from the master (GET /api/v1/SlaveStatus) and fails open to Available if the master is unreachable for too long, complementing the existing push. - The slave's own Settings page can no longer "successfully" change local availability while the master controls it; it's now locked with an explanatory banner and the backend rejects the write with 409 instead of silently no-op'ing it. - CMS instance status badges now match the dashboard's color/icon styling instead of a plain grey badge. Also corrected the master-cms-module design docs to match this as-built behavior, and flagged (without a full rewrite) a larger, pre-existing divergence between its inception-stage application design and what construction actually built. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
145 lines
6.3 KiB
Markdown
145 lines
6.3 KiB
Markdown
# Component Methods — Master CMS Module
|
|
|
|
> Method signatures at the interface level. Detailed business rules and implementation logic are deferred to Functional Design (CONSTRUCTION phase).
|
|
|
|
> ⚠️ **Partially superseded, found stale 2026-07-04**: the `IMasterAvailabilityService` methods and `/api/internal/master/*` routes below describe an inception-stage pull design that construction did not build as-is (actual routes are `/api/v1/master/*`; the method set differs — see `RegisterAsync`/`PushStatusAsync`/`GetRegisteredUrlAsync`/`GetMasterStatus` in `construction/slave-availability-extension/`, plus 2026-07-04 additions `GetPollTargetAsync`/`ApplyPolledStatusAsync`/`RecordPollFailureAsync`). Treat the functional-design docs under `construction/` as current truth for exact signatures.
|
|
|
|
---
|
|
|
|
## 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',
|
|
}
|
|
```
|