API: Boot state-machine + status
Ticket 1C-02 • Bron: src/routes/boot.ts (gepland) • Status: ontwerp • Risico: medium
Kerndefinitie: Boot-endpoints die de initialisatie van MAOS beheren. De boot state-machine doorloopt vier fasen: start, step, verify, complete. Idempotente retry zorgt dat mislukte stappen opnieuw uitgevoerd kunnen worden. Stray-step deny blokkeert stappen buiten de verwachte volgorde. SessionStorage bewaart bootState tussen herladingen.
1. Architectuur
Client (Browser)
│
├── GET /boot/status
│ └── Huidige boot-state ophalen
│
├── POST /boot/start
│ └── Boot-flow initialiseren
│ → state: "started"
│
├── POST /boot/step
│ ├── Stap uitvoeren (wallet-check, permission-init, etc.)
│ ├── Idempotent: zelfde stap opnieuw = zelfde resultaat
│ └── → state: "step_complete" of "step_failed"
│
├── POST /boot/verify
│ ├── Verifieer dat alle stappen voltooid zijn
│ ├── Stray-step deny: onverwachte stappen blokkeren
│ └── → state: "verified" of "incomplete"
│
└── POST /boot/complete
└── Boot-flow afsluiten
→ state: "completed"
→ SessionStorage: bootState = "completed"
State machine:
start → step₁ → step₂ → ... → verify → complete
↓
incomplete → step (retry)
SessionStorage:
bootState = "completed" (voorkomt herboot)
2. Endpoints
| Endpoint | Methode | Beschrijving | Auth |
/boot/status | GET | Huidige boot-state ophalen | Geen |
/boot/start | POST | Boot-flow initialiseren | Geen |
/boot/step | POST | Enkele stap uitvoeren | Session cookie |
/boot/verify | POST | Verificatie van volledigheid | Session cookie |
/boot/complete | POST | Boot-flow afsluiten | Session cookie |
3. Boot state-machine
Toegestane transities:
┌──────────┐
│ START │ ← POST /boot/start
└────┬─────┘
│
▼
┌──────────┐
│ STEP₁ │ ← POST /boot/step { step: "wallet-init" }
└────┬─────┘
│
▼
┌──────────┐
│ STEP₂ │ ← POST /boot/step { step: "permission-init" }
└────┬─────┘
│
▼
┌──────────┐
│ STEP₃ │ ← POST /boot/step { step: "extension-init" }
└────┬─────┘
│
▼
┌──────────┐
│ VERIFY │ ← POST /boot/verify
└────┬─────┘
│
├── incomplete → terug naar STEP (ontbrekende stappen)
│
▼
┌──────────┐
│ COMPLETE │ ← POST /boot/complete
└──────────┘
Onbekende transitie → 400 { error: "Invalid state transition" }
3.1 Bekende stappen
| Stap | Beschrijving | Idempotent |
wallet-init | Wallet-verbinding initialiseren | Ja |
permission-init | Rechten controleren/initialiseren | Ja |
extension-init | Extension-connectie opzetten | Ja |
session-init | Sessie validatie/aanmaak | Ja |
storage-init | Lokale storage initialiseren | Ja |
4. Idempotente retry
Regel: elke stap is idempotent.
POST /boot/step { step: "wallet-init" } (eerste keer)
→ { step: "wallet-init", status: "complete", result: { connected: true } }
POST /boot/step { step: "wallet-init" } (opnieuw)
→ { step: "wallet-init", status: "complete", result: { connected: true } }
Reden: browser herlaadt pagina tijdens boot-flow.
Stap opnieuw uitvoeren moet zelfde resultaat geven.
Geen dubbele initialisatie, geen fouten.
5. Stray-step deny
POST /boot/step { step: "extension-init" } (terwijl wallet nog niet geinitialiseerd)
→ 400 {
"error": "Stray step denied",
"currentStep": "wallet-init",
"expected": ["wallet-init"],
"received": "extension-init"
}
POST /boot/verify (niet alle stappen voltooid)
→ 400 {
"error": "Verification failed",
"completed": ["wallet-init"],
"missing": ["permission-init", "extension-init", "session-init"]
}
Reden: voorkomt onvolledige boot-state.
Stappen moeten in volgorde worden uitgevoerd.
6. SessionStorage voor bootState
Client-side opslag:
key: "maos-boot-state"
value: "completed" | "inbidden" | null
Logica:
1. Pagina laadt
2. Check SessionStorage: maos-boot-state
3. "completed" → skip boot-flow, direct naar app
4. null of ontbreekt → start boot-flow
5. Na POST /boot/complete → zet maos-boot-state = "completed"
Waarom SessionStorage (niet localStorage)?
├── Tab-specifiek: elke tab heeft eigen boot-state
├── Session: verloopt bij tab-sluiting
└── Geen persistente localStorage-rotzooi
7. Request / Response voorbeelden
7.1 GET /boot/status
GET /boot/status HTTP/1.1
Response:
{
"state": "step_complete",
"completedSteps": ["wallet-init", "permission-init"],
"currentStep": "extension-init",
"startedAt": "2025-01-15T10:00:00Z",
"elapsed": 5432
}
7.2 POST /boot/start
POST /boot/start HTTP/1.1
Response:
{
"state": "started",
"bootId": "boot_abc123",
"steps": ["wallet-init", "permission-init", "extension-init", "session-init"],
"startedAt": "2025-01-15T10:00:00Z"
}
7.3 POST /boot/step
POST /boot/step HTTP/1.1
Content-Type: application/json
{ "step": "wallet-init" }
Response:
{
"step": "wallet-init",
"status": "complete",
"result": { "connected": true, "address": "0x742d35Cc..." },
"completedSteps": ["wallet-init"],
"nextStep": "permission-init"
}
7.4 POST /boot/complete
POST /boot/complete HTTP/1.1
Response:
{
"state": "completed",
"bootId": "boot_abc123",
"totalTime": 1234,
"stepsCompleted": 4
}
8. Acceptatiecriteria
- Boot state-machine: start → step → verify → complete werkt correct
- Idempotente retry: zelfde stap opnieuw geeft zelfde resultaat
- Stray-step deny: stappen buiten volgorde worden geblokkeerd
- SessionStorage: bootState wordt bewaard tussen herladingen
- Status endpoint: retourneert huidige state + completed steps
- Foutafhandeling: onbekende stappen, onvolledige verificatie
- Timing: elapsed + totalTime worden bijgehouden
9. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| Boot-flow kan blokkeren bij network issues | Medium | Retry met exponential backoff per stap. Timeout na 30s per stap. |
| Stray-step deny kan te streng zijn | Low | Debug-mode: log warnings i.p.v. errors bij stray steps. |
| SessionStorage niet beschikbaar (privacy mode) | Low | Fallback: check via GET /boot/status i.p.v. localStorage. |
| Boot-flow herstart bij elke page load | Medium | SessionStorage check: als "completed" → skip boot-flow. |
10. Verwijzingen
Fase 1C Nog niet geimplementeerd. Vereist: state-machine implementatie, SessionStorage client-side, step-handlers. Prioriteit: medium (ondersteunt snelle app-start).