malpercio.dev
WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
1meta {
2 name: Check Health
3 type: http
4 seq: 1
5}
6
7get {
8 url: {{appview_url}}/api/health
9}
10
11assert {
12 res.status: eq 200
13 res.body.status: isDefined
14 res.body.timestamp: isDefined
15 res.body.services.database.status: isDefined
16 res.body.services.database.latency_ms: isDefined
17 res.body.services.firehose.status: isDefined
18 res.body.services.firehose.connected: isDefined
19 res.body.services.forumAgent.status: isDefined
20 res.body.services.forumAgent.authenticated: isDefined
21}
22
23docs {
24 Comprehensive health check endpoint for operational monitoring and visibility.
25 Returns detailed status of all system components.
26
27 **Authentication:** Public (no auth required)
28
29 **Security:** Does not expose sensitive data (no DIDs, handles, credentials, or configuration details)
30
31 Returns (always HTTP 200):
32 {
33 "status": "healthy" | "degraded" | "unhealthy",
34 "timestamp": "2026-02-13T10:30:00.000Z",
35 "services": {
36 "database": {
37 "status": "up" | "down",
38 "latency_ms": 5
39 },
40 "firehose": {
41 "status": "up" | "down",
42 "connected": true,
43 "last_event_at": "2026-02-13T10:29:55.000Z" // Optional
44 },
45 "forumAgent": {
46 "status": "authenticated" | "retrying" | "failed" | "unavailable" | "initializing",
47 "authenticated": true,
48 "last_auth_attempt": "2026-02-13T10:29:00.000Z", // Optional
49 "retry_count": 2, // Only if status=retrying
50 "next_retry_at": "2026-02-13T10:31:00.000Z", // Only if status=retrying
51 "error": "Connection to PDS temporarily unavailable" // User-safe message
52 }
53 }
54 }
55
56 Overall Status Logic:
57 - "healthy": All services up, forumAgent authenticated
58 - "degraded": Database + firehose up, forumAgent not authenticated (read-only mode)
59 - "unhealthy": Database or firehose down
60
61 ForumAgent Status Values:
62 - "authenticated": Successfully authenticated and ready for writes
63 - "retrying": Failed temporarily, retrying with exponential backoff (includes retry_count and next_retry_at)
64 - "failed": Permanently failed (auth error or max retries exceeded)
65 - "unavailable": Not configured (missing FORUM_HANDLE or FORUM_PASSWORD)
66 - "initializing": First auth attempt in progress
67
68 Usage Examples:
69 - Kubernetes liveness probe: Check `status !== "unhealthy"`
70 - Web UI banner: Show read-only warning if `forumAgent.status !== "authenticated"`
71 - Admin dashboard: Show retry countdown if `forumAgent.status === "retrying"`
72 - Monitoring alerts: Alert if `status === "unhealthy"` for more than 2 minutes
73
74 Example - Healthy System:
75 {
76 "status": "healthy",
77 "timestamp": "2026-02-13T10:30:00.000Z",
78 "services": {
79 "database": { "status": "up", "latency_ms": 5 },
80 "firehose": { "status": "up", "connected": true, "last_event_at": "2026-02-13T10:29:55.000Z" },
81 "forumAgent": { "status": "authenticated", "authenticated": true }
82 }
83 }
84
85 Example - Degraded System (ForumAgent Retrying):
86 {
87 "status": "degraded",
88 "timestamp": "2026-02-13T10:30:00.000Z",
89 "services": {
90 "database": { "status": "up", "latency_ms": 5 },
91 "firehose": { "status": "up", "connected": true, "last_event_at": "2026-02-13T10:29:55.000Z" },
92 "forumAgent": {
93 "status": "retrying",
94 "authenticated": false,
95 "last_auth_attempt": "2026-02-13T10:29:00.000Z",
96 "retry_count": 2,
97 "next_retry_at": "2026-02-13T10:31:00.000Z",
98 "error": "Connection to PDS temporarily unavailable"
99 }
100 }
101 }
102
103 Example - Unhealthy System (Database Down):
104 {
105 "status": "unhealthy",
106 "timestamp": "2026-02-13T10:30:00.000Z",
107 "services": {
108 "database": { "status": "down", "latency_ms": 0 },
109 "firehose": { "status": "up", "connected": true, "last_event_at": "2026-02-13T10:29:55.000Z" },
110 "forumAgent": { "status": "authenticated", "authenticated": true }
111 }
112 }
113
114 Notes:
115 - Always returns HTTP 200 (check response body for actual status)
116 - Optional fields (last_event_at, last_auth_attempt, retry_count, next_retry_at, error) may be absent
117 - All timestamps are ISO 8601 format
118 - Database latency is measured in milliseconds
119}