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
feat: implement ForumAgent service for server-side PDS writes (ATB-18) (#31)
* docs: add ATB-18 ForumAgent implementation plan
Detailed TDD-based plan with 10 bite-sized tasks:
1. Add forum credentials to config
2. Create ForumAgent class with status types
3. Implement error classification and retry logic
4. Implement proactive session refresh
5. Integrate into AppContext
6. Create health endpoint
7. Update test context
8. Manual integration testing
9. Update documentation
10. Update Linear issue and project plan
Each task follows TDD: write test → verify fail → implement → verify pass → commit
* feat(appview): add forum credentials to config
- Add forumHandle and forumPassword to AppConfig
- Load from FORUM_HANDLE and FORUM_PASSWORD env vars
- Make credentials optional (undefined if not set)
- Add tests for loading forum credentials
* feat(appview): create ForumAgent class with basic structure
- Define ForumAgentStatus and ForumAgentState types
- Implement initialization with status tracking
- Add getStatus(), isAuthenticated(), getAgent() methods
- Add shutdown() for resource cleanup
- Add tests for initialization and successful auth
* fix(appview): address ForumAgent code quality issues
Critical fixes:
- Logging: Wrap all console logs in JSON.stringify() per project standards
- Type safety: Remove non-null assertions by making agent non-nullable
- Test lifecycle: Add shutdown() calls in afterEach for proper cleanup
- Test coverage: Add test verifying shutdown() cleans up resources
All ForumAgent tests pass.
* feat(appview): implement error classification and retry logic in ForumAgent
- Add isAuthError() and isNetworkError() helpers
- Auth errors fail permanently (no retry, prevent lockouts)
- Network errors retry with exponential backoff (10s, 20s, 40s, 80s, 160s)
- Stop retrying after 5 failed attempts
- Update status to 'retrying' during retry attempts
- Add comprehensive tests for error classification and retry behavior
* fix(appview): correct retry backoff intervals to match spec (10s, 30s, 1m, 5m, 10m)
* feat(appview): implement proactive session refresh in ForumAgent
- Add scheduleRefresh() to run every 30 minutes
- Add refreshSession() using agent.resumeSession()
- Fall back to full re-auth if refresh fails
- Add tests for session refresh and refresh failure handling
* fix(appview): address ForumAgent session refresh critical issues
- Add isRefreshing flag to prevent concurrent refresh execution
- Add session existence check to guard clause in refreshSession()
- Set status='retrying' immediately on refresh failure (before attemptAuth)
- Remove non-null assertion by checking session in guard clause
Fixes race conditions and status consistency issues identified in code review.
* feat(appview): integrate ForumAgent into AppContext
- Add forumAgent to AppContext interface (nullable)
- Initialize ForumAgent in createAppContext if credentials provided
- Clean up ForumAgent in destroyAppContext
- Add tests for ForumAgent integration with AppContext
- Use structured logging with JSON.stringify for missing credentials warning
* fix(appview): add missing forumDid field to AppContext test config
- Add required forumDid field to test configuration
- Extend sessionSecret to meet 32-character minimum
* fix(appview): improve AppContext ForumAgent integration logging and tests
- Use JSON.stringify for structured logging (follows project convention)
- Add assertion that initialize() is called when ForumAgent created
- Add console.warn spy assertion for missing credentials path
- Improves test coverage of critical initialization path
* feat(appview): add comprehensive health endpoint with service status reporting
- Create GET /api/health endpoint (public, no auth required)
- Report status: healthy, degraded, unhealthy
- Include database status with latency measurement
- Include firehose connection status
- Include ForumAgent status (authenticated, retrying, failed, etc)
- Expose granular ForumAgent states with retry countdown
- Security: no sensitive data exposed (no DIDs, handles, credentials)
- Add comprehensive tests for all health states
- Maintain backward compatibility with /api/healthz legacy endpoints
* fix(appview): make health endpoint spec-compliant with FirehoseService API
- Add isRunning() and getLastEventTime() methods to FirehoseService
- Track last event timestamp in firehose
- Update health endpoint to use spec-compliant methods
- Add last_event_at field to firehose health response
- Update tests to use new API methods
Fixes spec deviation where health endpoint was using getHealthStatus()
instead of the specified isRunning() and getLastEventTime() methods.
* refactor(appview): improve health endpoint code quality
- Replace 'any' type with proper HealthResponse interface
- Remove dead code (isHealthy, getHealthStatus methods)
- Eliminate redundant isRunning() call (use cached value)
- Add test coverage for last_event_at field
- Improve type safety and reduce maintenance burden
* test(appview): add ForumAgent to test context
- Add forumAgent: null to test context return value
- Ensures route tests have proper AppContext shape
- Mock ForumAgent is null by default (can be overridden in tests)
* docs: mark ATB-18 implementation complete and add usage guide
- Update acceptance criteria to show all items complete
- Add usage examples for checking ForumAgent availability in routes
- Add monitoring examples for health endpoint
- Document required environment variables
* docs: mark ATB-18 complete in project plan
ForumAgent service implemented with:
- Graceful degradation and smart retry logic
- Proactive session refresh
- Health endpoint integration
- Comprehensive test coverage
* docs: update Bruno collection for /api/health endpoint
Update existing Check Health.bru to document the new comprehensive
health endpoint at /api/health instead of the legacy /api/healthz.
Changes:
- Updated URL from /api/healthz to /api/health
- Added comprehensive documentation of response structure
- Documented all three overall status types (healthy/degraded/unhealthy)
- Documented all five ForumAgent status values
- Added assertions for response fields
- Included example responses for each health state
- Added usage examples for monitoring and alerting
- Noted security guarantee (no sensitive data exposure)
Addresses code review feedback on PR #31.
+98
apps/appview/src/lib/__tests__/app-context.test.ts
+98
apps/appview/src/lib/__tests__/app-context.test.ts
···
···
1
+
import { describe, it, expect, vi, beforeEach } from "vitest";
2
+
import { createAppContext, destroyAppContext } from "../app-context.js";
3
+
import type { AppConfig } from "../config.js";
4
+
5
+
// Mock dependencies
6
+
vi.mock("@atbb/db", () => ({
7
+
createDb: vi.fn(() => ({})),
8
+
}));
9
+
10
+
vi.mock("../firehose.js", () => ({
11
+
FirehoseService: vi.fn(() => ({
12
+
start: vi.fn(),
13
+
stop: vi.fn(),
14
+
})),
15
+
}));
16
+
17
+
vi.mock("@atproto/oauth-client-node", () => ({
18
+
NodeOAuthClient: vi.fn(() => ({
19
+
clientMetadata: {},
20
+
})),
21
+
}));
22
+
23
+
vi.mock("../oauth-stores.js", () => ({
24
+
OAuthStateStore: vi.fn(() => ({ destroy: vi.fn() })),
25
+
OAuthSessionStore: vi.fn(() => ({ destroy: vi.fn() })),
26
+
}));
27
+
28
+
vi.mock("../cookie-session-store.js", () => ({
29
+
CookieSessionStore: vi.fn(() => ({ destroy: vi.fn() })),
30
+
}));
31
+
32
+
vi.mock("../forum-agent.js", () => ({
33
+
ForumAgent: vi.fn(() => ({
34
+
initialize: vi.fn(),
35
+
shutdown: vi.fn(),
36
+
isAuthenticated: vi.fn(() => true),
37
+
})),
38
+
}));
39
+
40
+
describe("AppContext", () => {
41
+
let config: AppConfig;
42
+
43
+
beforeEach(() => {
44
+
config = {
45
+
port: 3000,
46
+
forumDid: "did:plc:test123",
47
+
databaseUrl: "postgres://localhost/test",
48
+
jetstreamUrl: "wss://jetstream.example.com",
49
+
pdsUrl: "https://pds.example.com",
50
+
oauthPublicUrl: "http://localhost:3000",
51
+
sessionSecret: "test-secret-with-minimum-32-chars-for-validation",
52
+
sessionTtlDays: 7,
53
+
forumHandle: "forum.example.com",
54
+
forumPassword: "test-password",
55
+
};
56
+
});
57
+
58
+
describe("createAppContext", () => {
59
+
it("creates ForumAgent when credentials are provided", async () => {
60
+
const ctx = await createAppContext(config);
61
+
62
+
expect(ctx.forumAgent).toBeDefined();
63
+
expect(ctx.forumAgent).not.toBeNull();
64
+
expect(ctx.forumAgent!.initialize).toHaveBeenCalled();
65
+
});
66
+
67
+
it("sets forumAgent to null when credentials are missing", async () => {
68
+
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
69
+
config.forumHandle = undefined;
70
+
config.forumPassword = undefined;
71
+
72
+
const ctx = await createAppContext(config);
73
+
74
+
expect(ctx.forumAgent).toBeNull();
75
+
expect(warnSpy).toHaveBeenCalled();
76
+
warnSpy.mockRestore();
77
+
});
78
+
});
79
+
80
+
describe("destroyAppContext", () => {
81
+
it("shuts down ForumAgent if present", async () => {
82
+
const ctx = await createAppContext(config);
83
+
const shutdownSpy = vi.spyOn(ctx.forumAgent!, "shutdown");
84
+
85
+
await destroyAppContext(ctx);
86
+
87
+
expect(shutdownSpy).toHaveBeenCalled();
88
+
});
89
+
90
+
it("handles null ForumAgent gracefully", async () => {
91
+
config.forumHandle = undefined;
92
+
config.forumPassword = undefined;
93
+
const ctx = await createAppContext(config);
94
+
95
+
await expect(destroyAppContext(ctx)).resolves.not.toThrow();
96
+
});
97
+
});
98
+
});
+22
apps/appview/src/lib/__tests__/config.test.ts
+22
apps/appview/src/lib/__tests__/config.test.ts
···
181
warnSpy.mockRestore();
182
});
183
});
184
+
185
+
describe("Forum credentials", () => {
186
+
it("loads forum credentials from environment", async () => {
187
+
process.env.FORUM_HANDLE = "forum.example.com";
188
+
process.env.FORUM_PASSWORD = "test-password";
189
+
190
+
const config = await loadConfig();
191
+
192
+
expect(config.forumHandle).toBe("forum.example.com");
193
+
expect(config.forumPassword).toBe("test-password");
194
+
});
195
+
196
+
it("allows missing forum credentials (optional)", async () => {
197
+
delete process.env.FORUM_HANDLE;
198
+
delete process.env.FORUM_PASSWORD;
199
+
200
+
const config = await loadConfig();
201
+
202
+
expect(config.forumHandle).toBeUndefined();
203
+
expect(config.forumPassword).toBeUndefined();
204
+
});
205
+
});
206
});
+234
apps/appview/src/lib/__tests__/forum-agent.test.ts
+234
apps/appview/src/lib/__tests__/forum-agent.test.ts
···
···
1
+
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
2
+
import { ForumAgent } from "../forum-agent.js";
3
+
import { AtpAgent } from "@atproto/api";
4
+
5
+
// Mock @atproto/api
6
+
vi.mock("@atproto/api", () => ({
7
+
AtpAgent: vi.fn(),
8
+
}));
9
+
10
+
describe("ForumAgent", () => {
11
+
let mockAgent: any;
12
+
let mockLogin: any;
13
+
let agent: ForumAgent | null = null;
14
+
15
+
beforeEach(() => {
16
+
mockLogin = vi.fn();
17
+
mockAgent = {
18
+
login: mockLogin,
19
+
session: null,
20
+
};
21
+
(AtpAgent as any).mockImplementation(() => mockAgent);
22
+
});
23
+
24
+
afterEach(async () => {
25
+
if (agent) {
26
+
await agent.shutdown();
27
+
agent = null;
28
+
}
29
+
vi.clearAllMocks();
30
+
});
31
+
32
+
describe("initialization", () => {
33
+
it("starts with 'initializing' status", () => {
34
+
agent = new ForumAgent(
35
+
"https://pds.example.com",
36
+
"forum.example.com",
37
+
"password"
38
+
);
39
+
40
+
const status = agent.getStatus();
41
+
expect(status.status).toBe("initializing");
42
+
expect(status.authenticated).toBe(false);
43
+
});
44
+
45
+
it("transitions to 'authenticated' on successful login", async () => {
46
+
mockLogin.mockResolvedValueOnce(undefined);
47
+
mockAgent.session = {
48
+
did: "did:plc:test",
49
+
accessJwt: "token",
50
+
refreshJwt: "refresh",
51
+
};
52
+
53
+
agent = new ForumAgent(
54
+
"https://pds.example.com",
55
+
"forum.example.com",
56
+
"password"
57
+
);
58
+
await agent.initialize();
59
+
60
+
const status = agent.getStatus();
61
+
expect(status.status).toBe("authenticated");
62
+
expect(status.authenticated).toBe(true);
63
+
expect(agent.isAuthenticated()).toBe(true);
64
+
expect(agent.getAgent()).toBe(mockAgent);
65
+
});
66
+
});
67
+
68
+
describe("shutdown", () => {
69
+
it("cleans up timers on shutdown", async () => {
70
+
mockLogin.mockResolvedValueOnce(undefined);
71
+
mockAgent.session = { did: "did:plc:test", accessJwt: "token" };
72
+
73
+
agent = new ForumAgent(
74
+
"https://pds.example.com",
75
+
"forum.example.com",
76
+
"password"
77
+
);
78
+
await agent.initialize();
79
+
80
+
expect(agent.isAuthenticated()).toBe(true);
81
+
82
+
await agent.shutdown();
83
+
84
+
// Agent should still be authenticated but timers are cleared
85
+
// (shutdown only clears timers, doesn't invalidate session)
86
+
expect(agent.isAuthenticated()).toBe(true);
87
+
});
88
+
});
89
+
90
+
describe("error classification", () => {
91
+
it("fails permanently on auth errors (no retry)", async () => {
92
+
const authError = new Error("Invalid identifier or password");
93
+
mockLogin.mockRejectedValueOnce(authError);
94
+
95
+
agent = new ForumAgent(
96
+
"https://pds.example.com",
97
+
"forum.example.com",
98
+
"wrong-password"
99
+
);
100
+
await agent.initialize();
101
+
102
+
const status = agent.getStatus();
103
+
expect(status.status).toBe("failed");
104
+
expect(status.authenticated).toBe(false);
105
+
expect(status.error).toContain("invalid credentials");
106
+
expect(mockLogin).toHaveBeenCalledTimes(1); // No retry
107
+
});
108
+
109
+
it("retries on network errors with exponential backoff", async () => {
110
+
vi.useFakeTimers();
111
+
112
+
const networkError = new Error("ECONNREFUSED");
113
+
(networkError as any).code = "ECONNREFUSED";
114
+
mockLogin.mockRejectedValueOnce(networkError);
115
+
116
+
agent = new ForumAgent(
117
+
"https://pds.example.com",
118
+
"forum.example.com",
119
+
"password"
120
+
);
121
+
await agent.initialize();
122
+
123
+
const status = agent.getStatus();
124
+
expect(status.status).toBe("retrying");
125
+
expect(status.authenticated).toBe(false);
126
+
expect(status.retryCount).toBe(1);
127
+
expect(status.nextRetryAt).toBeDefined();
128
+
expect(mockLogin).toHaveBeenCalledTimes(1);
129
+
130
+
// Fast-forward to next retry (10 seconds)
131
+
mockLogin.mockResolvedValueOnce(undefined);
132
+
mockAgent.session = { did: "did:plc:test", accessJwt: "token" };
133
+
134
+
await vi.advanceTimersByTimeAsync(10000);
135
+
136
+
const statusAfterRetry = agent.getStatus();
137
+
expect(statusAfterRetry.status).toBe("authenticated");
138
+
expect(statusAfterRetry.authenticated).toBe(true);
139
+
expect(mockLogin).toHaveBeenCalledTimes(2);
140
+
141
+
vi.useRealTimers();
142
+
});
143
+
144
+
it("stops retrying after max attempts", async () => {
145
+
vi.useFakeTimers();
146
+
147
+
const networkError = new Error("ETIMEDOUT");
148
+
(networkError as any).code = "ETIMEDOUT";
149
+
mockLogin.mockRejectedValue(networkError);
150
+
151
+
agent = new ForumAgent(
152
+
"https://pds.example.com",
153
+
"forum.example.com",
154
+
"password"
155
+
);
156
+
await agent.initialize();
157
+
158
+
// Advance through all retry attempts (5 retries)
159
+
const retryDelays = [10000, 30000, 60000, 300000, 600000];
160
+
for (let i = 0; i < 5; i++) {
161
+
const delay = retryDelays[i];
162
+
await vi.advanceTimersByTimeAsync(delay);
163
+
}
164
+
165
+
const status = agent.getStatus();
166
+
expect(status.status).toBe("failed");
167
+
expect(status.error).toContain("max retries");
168
+
expect(mockLogin).toHaveBeenCalledTimes(6); // Initial + 5 retries
169
+
170
+
vi.useRealTimers();
171
+
});
172
+
});
173
+
174
+
describe("session refresh", () => {
175
+
it("schedules proactive refresh after successful auth", async () => {
176
+
vi.useFakeTimers();
177
+
178
+
mockLogin.mockResolvedValueOnce(undefined);
179
+
mockAgent.session = { did: "did:plc:test", accessJwt: "token" };
180
+
181
+
agent = new ForumAgent(
182
+
"https://pds.example.com",
183
+
"forum.example.com",
184
+
"password"
185
+
);
186
+
await agent.initialize();
187
+
188
+
expect(agent.isAuthenticated()).toBe(true);
189
+
190
+
// Fast-forward 30 minutes to trigger refresh
191
+
const mockResumeSession = vi.fn().mockResolvedValue(undefined);
192
+
mockAgent.resumeSession = mockResumeSession;
193
+
194
+
await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
195
+
196
+
expect(mockResumeSession).toHaveBeenCalled();
197
+
198
+
vi.useRealTimers();
199
+
});
200
+
201
+
it("retries if refresh fails with network error", async () => {
202
+
vi.useFakeTimers();
203
+
204
+
// Initial auth succeeds
205
+
mockLogin.mockResolvedValueOnce(undefined);
206
+
mockAgent.session = { did: "did:plc:test", accessJwt: "token" };
207
+
208
+
agent = new ForumAgent(
209
+
"https://pds.example.com",
210
+
"forum.example.com",
211
+
"password"
212
+
);
213
+
await agent.initialize();
214
+
215
+
// Simulate refresh failure followed by re-auth failure
216
+
const networkError = new Error("ECONNREFUSED");
217
+
(networkError as any).code = "ECONNREFUSED";
218
+
const mockResumeSession = vi.fn().mockRejectedValueOnce(networkError);
219
+
mockAgent.resumeSession = mockResumeSession;
220
+
221
+
// Re-auth will also fail (network error)
222
+
mockLogin.mockRejectedValueOnce(networkError);
223
+
224
+
await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
225
+
226
+
// Should transition to retrying status after refresh fails and re-auth fails
227
+
const status = agent.getStatus();
228
+
expect(status.status).toBe("retrying");
229
+
expect(status.authenticated).toBe(false);
230
+
231
+
vi.useRealTimers();
232
+
});
233
+
});
234
+
});
+2
apps/appview/src/lib/__tests__/test-context.ts
+2
apps/appview/src/lib/__tests__/test-context.ts
···
61
const stubOAuthStateStore = { destroy: () => {} } as any;
62
const stubOAuthSessionStore = { destroy: () => {} } as any;
63
const stubCookieSessionStore = { destroy: () => {} } as any;
64
65
return {
66
db,
···
70
oauthStateStore: stubOAuthStateStore,
71
oauthSessionStore: stubOAuthSessionStore,
72
cookieSessionStore: stubCookieSessionStore,
73
cleanup: async () => {
74
// Clean up test data (order matters due to FKs: posts -> memberships -> users -> categories -> forums)
75
// Delete all test-specific DIDs (including dynamically generated ones)
···
61
const stubOAuthStateStore = { destroy: () => {} } as any;
62
const stubOAuthSessionStore = { destroy: () => {} } as any;
63
const stubCookieSessionStore = { destroy: () => {} } as any;
64
+
const stubForumAgent = null; // Mock ForumAgent is null by default (can be overridden in tests)
65
66
return {
67
db,
···
71
oauthStateStore: stubOAuthStateStore,
72
oauthSessionStore: stubOAuthSessionStore,
73
cookieSessionStore: stubCookieSessionStore,
74
+
forumAgent: stubForumAgent,
75
cleanup: async () => {
76
// Clean up test data (order matters due to FKs: posts -> memberships -> users -> categories -> forums)
77
// Delete all test-specific DIDs (including dynamically generated ones)
+28
apps/appview/src/lib/app-context.ts
+28
apps/appview/src/lib/app-context.ts
···
4
import { NodeOAuthClient } from "@atproto/oauth-client-node";
5
import { OAuthStateStore, OAuthSessionStore } from "./oauth-stores.js";
6
import { CookieSessionStore } from "./cookie-session-store.js";
7
import type { AppConfig } from "./config.js";
8
9
/**
···
18
oauthStateStore: OAuthStateStore;
19
oauthSessionStore: OAuthSessionStore;
20
cookieSessionStore: CookieSessionStore;
21
}
22
23
/**
···
78
allowHttp: process.env.NODE_ENV !== "production",
79
});
80
81
return {
82
config,
83
db,
···
86
oauthStateStore,
87
oauthSessionStore,
88
cookieSessionStore,
89
};
90
}
91
···
94
*/
95
export async function destroyAppContext(ctx: AppContext): Promise<void> {
96
await ctx.firehose.stop();
97
98
// Clean up OAuth store timers
99
ctx.oauthStateStore.destroy();
···
4
import { NodeOAuthClient } from "@atproto/oauth-client-node";
5
import { OAuthStateStore, OAuthSessionStore } from "./oauth-stores.js";
6
import { CookieSessionStore } from "./cookie-session-store.js";
7
+
import { ForumAgent } from "./forum-agent.js";
8
import type { AppConfig } from "./config.js";
9
10
/**
···
19
oauthStateStore: OAuthStateStore;
20
oauthSessionStore: OAuthSessionStore;
21
cookieSessionStore: CookieSessionStore;
22
+
forumAgent: ForumAgent | null;
23
}
24
25
/**
···
80
allowHttp: process.env.NODE_ENV !== "production",
81
});
82
83
+
// Initialize ForumAgent (soft failure - never throws)
84
+
let forumAgent: ForumAgent | null = null;
85
+
if (config.forumHandle && config.forumPassword) {
86
+
forumAgent = new ForumAgent(
87
+
config.pdsUrl,
88
+
config.forumHandle,
89
+
config.forumPassword
90
+
);
91
+
await forumAgent.initialize();
92
+
} else {
93
+
console.warn(
94
+
JSON.stringify({
95
+
event: "forumAgent.credentialsMissing",
96
+
service: "AppContext",
97
+
operation: "createAppContext",
98
+
reason: "Missing FORUM_HANDLE or FORUM_PASSWORD environment variables",
99
+
timestamp: new Date().toISOString(),
100
+
})
101
+
);
102
+
}
103
+
104
return {
105
config,
106
db,
···
109
oauthStateStore,
110
oauthSessionStore,
111
cookieSessionStore,
112
+
forumAgent,
113
};
114
}
115
···
118
*/
119
export async function destroyAppContext(ctx: AppContext): Promise<void> {
120
await ctx.firehose.stop();
121
+
122
+
if (ctx.forumAgent) {
123
+
await ctx.forumAgent.shutdown();
124
+
}
125
126
// Clean up OAuth store timers
127
ctx.oauthStateStore.destroy();
+6
apps/appview/src/lib/config.ts
+6
apps/appview/src/lib/config.ts
···
9
sessionSecret: string;
10
sessionTtlDays: number;
11
redisUrl?: string;
12
}
13
14
export function loadConfig(): AppConfig {
···
25
sessionSecret: process.env.SESSION_SECRET ?? "",
26
sessionTtlDays: parseInt(process.env.SESSION_TTL_DAYS ?? "7", 10),
27
redisUrl: process.env.REDIS_URL,
28
};
29
30
validateOAuthConfig(config);
···
9
sessionSecret: string;
10
sessionTtlDays: number;
11
redisUrl?: string;
12
+
// Forum credentials (optional - for server-side PDS writes)
13
+
forumHandle?: string;
14
+
forumPassword?: string;
15
}
16
17
export function loadConfig(): AppConfig {
···
28
sessionSecret: process.env.SESSION_SECRET ?? "",
29
sessionTtlDays: parseInt(process.env.SESSION_TTL_DAYS ?? "7", 10),
30
redisUrl: process.env.REDIS_URL,
31
+
// Forum credentials (optional - for server-side PDS writes)
32
+
forumHandle: process.env.FORUM_HANDLE,
33
+
forumPassword: process.env.FORUM_PASSWORD,
34
};
35
36
validateOAuthConfig(config);
+16
-26
apps/appview/src/lib/firehose.ts
+16
-26
apps/appview/src/lib/firehose.ts
···
23
export class FirehoseService {
24
private jetstream: Jetstream;
25
private indexer: Indexer;
26
-
private isRunning = false;
27
private cursorManager: CursorManager;
28
private circuitBreaker: CircuitBreaker;
29
private reconnectionManager: ReconnectionManager;
···
129
// Apply all handlers from the registry
130
this.handlerRegistry.applyTo(this.jetstream);
131
132
-
// Listen to all commits to track cursor
133
this.jetstream.on("commit", async (event) => {
134
await this.cursorManager.update(event.time_us);
135
});
136
···
145
* Start the firehose subscription
146
*/
147
async start() {
148
-
if (this.isRunning) {
149
console.warn("Firehose service is already running");
150
return;
151
}
···
165
166
console.log(`Starting Jetstream firehose subscription to ${this.jetstreamUrl}`);
167
await this.jetstream.start();
168
-
this.isRunning = true;
169
this.reconnectionManager.reset();
170
console.log("Jetstream firehose subscription started successfully");
171
} catch (error) {
···
178
* Stop the firehose subscription
179
*/
180
async stop() {
181
-
if (!this.isRunning) {
182
return;
183
}
184
185
console.log("Stopping Jetstream firehose subscription");
186
await this.jetstream.close();
187
-
this.isRunning = false;
188
console.log("Jetstream firehose subscription stopped");
189
}
190
191
/**
192
-
* Check if the firehose is healthy and actively indexing
193
*/
194
-
isHealthy(): boolean {
195
-
return this.isRunning;
196
}
197
198
/**
199
-
* Get detailed health status for monitoring
200
*/
201
-
getHealthStatus(): {
202
-
isRunning: boolean;
203
-
reconnectAttempts: number;
204
-
consecutiveFailures: number;
205
-
maxReconnectAttempts: number;
206
-
maxConsecutiveFailures: number;
207
-
} {
208
-
return {
209
-
isRunning: this.isRunning,
210
-
reconnectAttempts: this.reconnectionManager.getAttemptCount(),
211
-
consecutiveFailures: this.circuitBreaker.getFailureCount(),
212
-
maxReconnectAttempts: 10,
213
-
maxConsecutiveFailures: 100,
214
-
};
215
}
216
217
/**
···
220
private async handleReconnect() {
221
try {
222
await this.reconnectionManager.attemptReconnect(async () => {
223
-
this.isRunning = false;
224
await this.start();
225
});
226
} catch {
227
console.error(
228
`[FATAL] Firehose indexing has stopped. The appview will continue serving stale data.`
229
);
230
-
this.isRunning = false;
231
}
232
}
233
···
23
export class FirehoseService {
24
private jetstream: Jetstream;
25
private indexer: Indexer;
26
+
private running = false;
27
+
private lastEventTime: Date | null = null;
28
private cursorManager: CursorManager;
29
private circuitBreaker: CircuitBreaker;
30
private reconnectionManager: ReconnectionManager;
···
130
// Apply all handlers from the registry
131
this.handlerRegistry.applyTo(this.jetstream);
132
133
+
// Listen to all commits to track cursor and last event time
134
this.jetstream.on("commit", async (event) => {
135
+
this.lastEventTime = new Date();
136
await this.cursorManager.update(event.time_us);
137
});
138
···
147
* Start the firehose subscription
148
*/
149
async start() {
150
+
if (this.running) {
151
console.warn("Firehose service is already running");
152
return;
153
}
···
167
168
console.log(`Starting Jetstream firehose subscription to ${this.jetstreamUrl}`);
169
await this.jetstream.start();
170
+
this.running = true;
171
this.reconnectionManager.reset();
172
console.log("Jetstream firehose subscription started successfully");
173
} catch (error) {
···
180
* Stop the firehose subscription
181
*/
182
async stop() {
183
+
if (!this.running) {
184
return;
185
}
186
187
console.log("Stopping Jetstream firehose subscription");
188
await this.jetstream.close();
189
+
this.running = false;
190
console.log("Jetstream firehose subscription stopped");
191
}
192
193
/**
194
+
* Check if the firehose is currently running
195
*/
196
+
isRunning(): boolean {
197
+
return this.running;
198
}
199
200
/**
201
+
* Get the timestamp of the last received event
202
*/
203
+
getLastEventTime(): Date | null {
204
+
return this.lastEventTime;
205
}
206
207
/**
···
210
private async handleReconnect() {
211
try {
212
await this.reconnectionManager.attemptReconnect(async () => {
213
+
this.running = false;
214
await this.start();
215
});
216
} catch {
217
console.error(
218
`[FATAL] Firehose indexing has stopped. The appview will continue serving stale data.`
219
);
220
+
this.running = false;
221
}
222
}
223
+318
apps/appview/src/lib/forum-agent.ts
+318
apps/appview/src/lib/forum-agent.ts
···
···
1
+
import { AtpAgent } from "@atproto/api";
2
+
3
+
/**
4
+
* Check if an error is an authentication error (wrong credentials).
5
+
* These should NOT be retried to avoid account lockouts.
6
+
*/
7
+
function isAuthError(error: unknown): boolean {
8
+
if (!(error instanceof Error)) return false;
9
+
10
+
const message = error.message.toLowerCase();
11
+
return (
12
+
message.includes("invalid identifier") ||
13
+
message.includes("invalid password") ||
14
+
message.includes("authentication failed") ||
15
+
message.includes("unauthorized")
16
+
);
17
+
}
18
+
19
+
/**
20
+
* Check if an error is a network error (transient failure).
21
+
* These are safe to retry with exponential backoff.
22
+
*/
23
+
function isNetworkError(error: unknown): boolean {
24
+
if (!(error instanceof Error)) return false;
25
+
26
+
const code = (error as any).code;
27
+
const message = error.message.toLowerCase();
28
+
29
+
return (
30
+
code === "ECONNREFUSED" ||
31
+
code === "ETIMEDOUT" ||
32
+
code === "ENOTFOUND" ||
33
+
code === "ENETUNREACH" ||
34
+
code === "ECONNRESET" ||
35
+
message.includes("network") ||
36
+
message.includes("fetch failed") ||
37
+
message.includes("service unavailable")
38
+
);
39
+
}
40
+
41
+
export type ForumAgentStatus =
42
+
| "initializing"
43
+
| "authenticated"
44
+
| "retrying"
45
+
| "failed"
46
+
| "unavailable";
47
+
48
+
export interface ForumAgentState {
49
+
status: ForumAgentStatus;
50
+
authenticated: boolean;
51
+
lastAuthAttempt?: Date;
52
+
nextRetryAt?: Date;
53
+
retryCount?: number;
54
+
error?: string;
55
+
}
56
+
57
+
/**
58
+
* ForumAgent manages authentication as the Forum DID for server-side PDS writes.
59
+
* Handles session lifecycle with smart retry logic and graceful degradation.
60
+
*/
61
+
export class ForumAgent {
62
+
private agent: AtpAgent;
63
+
private status: ForumAgentStatus = "initializing";
64
+
private authenticated = false;
65
+
private retryCount = 0;
66
+
private readonly maxRetries = 5;
67
+
private refreshTimer: NodeJS.Timeout | null = null;
68
+
private retryTimer: NodeJS.Timeout | null = null;
69
+
private isRefreshing = false;
70
+
private lastError: string | null = null;
71
+
private lastAuthAttempt: Date | null = null;
72
+
private nextRetryAt: Date | null = null;
73
+
74
+
constructor(
75
+
private readonly pdsUrl: string,
76
+
private readonly handle: string,
77
+
private readonly password: string
78
+
) {
79
+
this.agent = new AtpAgent({ service: pdsUrl });
80
+
}
81
+
82
+
/**
83
+
* Initialize the agent by attempting authentication.
84
+
* Never throws - returns gracefully even on failure.
85
+
*/
86
+
async initialize(): Promise<void> {
87
+
await this.attemptAuth();
88
+
}
89
+
90
+
/**
91
+
* Check if the agent is authenticated and ready for use.
92
+
*/
93
+
isAuthenticated(): boolean {
94
+
return this.authenticated;
95
+
}
96
+
97
+
/**
98
+
* Get the underlying AtpAgent for PDS operations.
99
+
* Returns null if not authenticated.
100
+
*/
101
+
getAgent(): AtpAgent | null {
102
+
return this.authenticated ? this.agent : null;
103
+
}
104
+
105
+
/**
106
+
* Get current agent status for health reporting.
107
+
*/
108
+
getStatus(): ForumAgentState {
109
+
const state: ForumAgentState = {
110
+
status: this.status,
111
+
authenticated: this.authenticated,
112
+
};
113
+
114
+
if (this.lastAuthAttempt) {
115
+
state.lastAuthAttempt = this.lastAuthAttempt;
116
+
}
117
+
118
+
if (this.status === "retrying") {
119
+
state.retryCount = this.retryCount;
120
+
if (this.nextRetryAt) {
121
+
state.nextRetryAt = this.nextRetryAt;
122
+
}
123
+
}
124
+
125
+
if (this.lastError) {
126
+
state.error = this.lastError;
127
+
}
128
+
129
+
return state;
130
+
}
131
+
132
+
/**
133
+
* Attempt to authenticate with the PDS.
134
+
* Implements smart retry logic and error classification.
135
+
*/
136
+
private async attemptAuth(): Promise<void> {
137
+
try {
138
+
this.lastAuthAttempt = new Date();
139
+
await this.agent.login({
140
+
identifier: this.handle,
141
+
password: this.password,
142
+
});
143
+
144
+
// Success!
145
+
this.status = "authenticated";
146
+
this.authenticated = true;
147
+
this.retryCount = 0;
148
+
this.lastError = null;
149
+
this.nextRetryAt = null;
150
+
151
+
console.info(
152
+
JSON.stringify({
153
+
event: "forumAgent.auth.success",
154
+
service: "ForumAgent",
155
+
handle: this.handle,
156
+
did: this.agent.session?.did,
157
+
timestamp: new Date().toISOString(),
158
+
})
159
+
);
160
+
161
+
// Schedule proactive session refresh
162
+
this.scheduleRefresh();
163
+
} catch (error) {
164
+
this.authenticated = false;
165
+
166
+
// Check error type for smart retry
167
+
if (isAuthError(error)) {
168
+
// Permanent failure - don't retry to avoid account lockouts
169
+
this.status = "failed";
170
+
this.lastError = "Authentication failed: invalid credentials";
171
+
this.retryCount = 0;
172
+
this.nextRetryAt = null;
173
+
174
+
console.error(
175
+
JSON.stringify({
176
+
event: "forumAgent.auth.permanentFailure",
177
+
service: "ForumAgent",
178
+
handle: this.handle,
179
+
error: error instanceof Error ? error.message : String(error),
180
+
timestamp: new Date().toISOString(),
181
+
})
182
+
);
183
+
return;
184
+
}
185
+
186
+
if (isNetworkError(error) && this.retryCount < this.maxRetries) {
187
+
// Transient failure - retry with exponential backoff
188
+
this.status = "retrying";
189
+
// Retry delays: 10s, 30s, 1m, 5m, 10m (max)
190
+
const retryDelays = [10000, 30000, 60000, 300000, 600000];
191
+
const delay = retryDelays[Math.min(this.retryCount, retryDelays.length - 1)];
192
+
this.retryCount++;
193
+
this.nextRetryAt = new Date(Date.now() + delay);
194
+
this.lastError = "Connection to PDS temporarily unavailable";
195
+
196
+
console.warn(
197
+
JSON.stringify({
198
+
event: "forumAgent.auth.retrying",
199
+
service: "ForumAgent",
200
+
handle: this.handle,
201
+
attempt: this.retryCount,
202
+
maxAttempts: this.maxRetries,
203
+
retryInMs: delay,
204
+
error: error instanceof Error ? error.message : String(error),
205
+
timestamp: new Date().toISOString(),
206
+
})
207
+
);
208
+
209
+
this.retryTimer = setTimeout(() => {
210
+
this.attemptAuth();
211
+
}, delay);
212
+
return;
213
+
}
214
+
215
+
// Unknown error or max retries exceeded
216
+
this.status = "failed";
217
+
this.lastError =
218
+
this.retryCount >= this.maxRetries
219
+
? "Auth failed after max retries"
220
+
: "Authentication failed";
221
+
this.nextRetryAt = null;
222
+
223
+
console.error(
224
+
JSON.stringify({
225
+
event: "forumAgent.auth.failed",
226
+
service: "ForumAgent",
227
+
handle: this.handle,
228
+
attempts: this.retryCount + 1,
229
+
reason:
230
+
this.retryCount >= this.maxRetries
231
+
? "max retries exceeded"
232
+
: "unknown error",
233
+
error: error instanceof Error ? error.message : String(error),
234
+
timestamp: new Date().toISOString(),
235
+
})
236
+
);
237
+
}
238
+
}
239
+
240
+
/**
241
+
* Schedule proactive session refresh to prevent expiry.
242
+
* Runs every 30 minutes to keep session alive.
243
+
*/
244
+
private scheduleRefresh(): void {
245
+
// Clear any existing timer
246
+
if (this.refreshTimer) {
247
+
clearTimeout(this.refreshTimer);
248
+
}
249
+
250
+
// Schedule refresh check every 30 minutes
251
+
this.refreshTimer = setTimeout(async () => {
252
+
await this.refreshSession();
253
+
}, 30 * 60 * 1000); // 30 minutes
254
+
}
255
+
256
+
/**
257
+
* Attempt to refresh the current session.
258
+
* Falls back to full re-auth if refresh fails.
259
+
*/
260
+
private async refreshSession(): Promise<void> {
261
+
if (!this.agent || !this.authenticated || !this.agent.session) {
262
+
return;
263
+
}
264
+
265
+
// Prevent concurrent refresh
266
+
if (this.isRefreshing) {
267
+
return;
268
+
}
269
+
270
+
this.isRefreshing = true;
271
+
try {
272
+
await this.agent.resumeSession(this.agent.session);
273
+
274
+
console.debug(
275
+
JSON.stringify({
276
+
event: "forumAgent.session.refreshed",
277
+
service: "ForumAgent",
278
+
did: this.agent.session?.did,
279
+
timestamp: new Date().toISOString(),
280
+
})
281
+
);
282
+
283
+
// Schedule next refresh
284
+
this.scheduleRefresh();
285
+
} catch (error) {
286
+
console.warn(
287
+
JSON.stringify({
288
+
event: "forumAgent.session.refreshFailed",
289
+
service: "ForumAgent",
290
+
error: error instanceof Error ? error.message : String(error),
291
+
timestamp: new Date().toISOString(),
292
+
})
293
+
);
294
+
295
+
// Refresh failed - transition to retrying and attempt full re-auth
296
+
this.authenticated = false;
297
+
this.status = "retrying";
298
+
this.retryCount = 0;
299
+
await this.attemptAuth();
300
+
} finally {
301
+
this.isRefreshing = false;
302
+
}
303
+
}
304
+
305
+
/**
306
+
* Clean up resources (timers, etc).
307
+
*/
308
+
async shutdown(): Promise<void> {
309
+
if (this.refreshTimer) {
310
+
clearTimeout(this.refreshTimer);
311
+
this.refreshTimer = null;
312
+
}
313
+
if (this.retryTimer) {
314
+
clearTimeout(this.retryTimer);
315
+
this.retryTimer = null;
316
+
}
317
+
}
318
+
}
+154
-17
apps/appview/src/routes/__tests__/health.test.ts
+154
-17
apps/appview/src/routes/__tests__/health.test.ts
···
1
-
import { describe, it, expect } from "vitest";
2
import { Hono } from "hono";
3
-
import { apiRoutes } from "../index.js";
4
5
-
const app = new Hono().route("/api", apiRoutes);
6
7
-
describe("GET /api/healthz", () => {
8
-
it("returns 200 with ok status", async () => {
9
-
const res = await app.request("/api/healthz");
10
expect(res.status).toBe(200);
11
-
const body = await res.json();
12
-
expect(body).toEqual({ status: "ok", version: "0.1.0" });
13
});
14
15
-
it("returns application/json content type", async () => {
16
-
const res = await app.request("/api/healthz");
17
-
expect(res.headers.get("content-type")).toContain("application/json");
18
});
19
-
});
20
21
-
describe("GET /api/healthz/ready", () => {
22
-
it("returns 200 with ready status", async () => {
23
-
const res = await app.request("/api/healthz/ready");
24
expect(res.status).toBe(200);
25
-
const body = await res.json();
26
-
expect(body).toEqual({ status: "ready" });
27
});
28
});
···
1
+
import { describe, it, expect, beforeEach } from "vitest";
2
import { Hono } from "hono";
3
+
import { createHealthRoutes } from "../health.js";
4
+
import type { AppContext } from "../../lib/app-context.js";
5
+
6
+
describe("GET /health", () => {
7
+
let app: Hono;
8
+
let ctx: AppContext;
9
+
10
+
beforeEach(() => {
11
+
// Mock AppContext with healthy defaults
12
+
ctx = {
13
+
config: {} as any,
14
+
db: {
15
+
execute: async () => ({ rows: [] }),
16
+
} as any,
17
+
firehose: {
18
+
isRunning: () => true,
19
+
getLastEventTime: () => new Date(),
20
+
} as any,
21
+
oauthClient: {} as any,
22
+
oauthStateStore: {} as any,
23
+
oauthSessionStore: {} as any,
24
+
cookieSessionStore: {} as any,
25
+
forumAgent: {
26
+
isAuthenticated: () => true,
27
+
getStatus: () => ({
28
+
status: "authenticated" as const,
29
+
authenticated: true,
30
+
}),
31
+
} as any,
32
+
};
33
+
34
+
app = new Hono().route("/", createHealthRoutes(ctx));
35
+
});
36
37
+
it("returns 200 with healthy status when all services up", async () => {
38
+
const res = await app.request("/health");
39
40
expect(res.status).toBe(200);
41
+
const data = await res.json();
42
+
expect(data.status).toBe("healthy");
43
+
expect(data.timestamp).toBeDefined();
44
+
expect(data.services.database.status).toBe("up");
45
+
expect(data.services.firehose.status).toBe("up");
46
+
expect(data.services.firehose.last_event_at).toBeDefined();
47
+
expect(data.services.forumAgent.status).toBe("authenticated");
48
+
});
49
+
50
+
it("returns degraded status when ForumAgent not authenticated", async () => {
51
+
ctx.forumAgent = {
52
+
isAuthenticated: () => false,
53
+
getStatus: () => ({
54
+
status: "retrying" as const,
55
+
authenticated: false,
56
+
retryCount: 2,
57
+
nextRetryAt: new Date(Date.now() + 60000),
58
+
error: "Connection to PDS temporarily unavailable",
59
+
}),
60
+
} as any;
61
+
62
+
const res = await app.request("/health");
63
+
64
+
expect(res.status).toBe(200);
65
+
const data = await res.json();
66
+
expect(data.status).toBe("degraded");
67
+
expect(data.services.forumAgent.status).toBe("retrying");
68
+
expect(data.services.forumAgent.retry_count).toBe(2);
69
+
expect(data.services.forumAgent.next_retry_at).toBeDefined();
70
+
});
71
+
72
+
it("returns unhealthy status when database is down", async () => {
73
+
ctx.db = {
74
+
execute: async () => {
75
+
throw new Error("Database connection failed");
76
+
},
77
+
} as any;
78
+
79
+
const res = await app.request("/health");
80
+
81
+
expect(res.status).toBe(200);
82
+
const data = await res.json();
83
+
expect(data.status).toBe("unhealthy");
84
+
expect(data.services.database.status).toBe("down");
85
});
86
87
+
it("returns unhealthy status when firehose is down", async () => {
88
+
ctx.firehose = {
89
+
isRunning: () => false,
90
+
getLastEventTime: () => null,
91
+
} as any;
92
+
93
+
const res = await app.request("/health");
94
+
95
+
expect(res.status).toBe(200);
96
+
const data = await res.json();
97
+
expect(data.status).toBe("unhealthy");
98
+
expect(data.services.firehose.status).toBe("down");
99
+
expect(data.services.firehose.last_event_at).toBeUndefined();
100
});
101
+
102
+
it("handles null forumAgent gracefully", async () => {
103
+
ctx.forumAgent = null;
104
+
105
+
const res = await app.request("/health");
106
107
expect(res.status).toBe(200);
108
+
const data = await res.json();
109
+
expect(data.status).toBe("degraded");
110
+
expect(data.services.forumAgent.status).toBe("unavailable");
111
+
expect(data.services.forumAgent.authenticated).toBe(false);
112
+
});
113
+
114
+
it("does not expose sensitive data", async () => {
115
+
const res = await app.request("/health");
116
+
const data = await res.json();
117
+
118
+
// Should not contain DIDs, handles, or configuration details
119
+
const jsonStr = JSON.stringify(data);
120
+
expect(jsonStr).not.toContain("did:plc");
121
+
expect(jsonStr).not.toContain("forum.example.com");
122
+
expect(jsonStr).not.toContain("password");
123
+
expect(jsonStr).not.toContain("DATABASE_URL");
124
+
});
125
+
126
+
it("includes database latency", async () => {
127
+
const res = await app.request("/health");
128
+
const data = await res.json();
129
+
130
+
expect(data.services.database.latency_ms).toBeGreaterThanOrEqual(0);
131
+
});
132
+
133
+
it("includes ForumAgent error message when in error state", async () => {
134
+
ctx.forumAgent = {
135
+
isAuthenticated: () => false,
136
+
getStatus: () => ({
137
+
status: "failed" as const,
138
+
authenticated: false,
139
+
error: "Invalid credentials",
140
+
}),
141
+
} as any;
142
+
143
+
const res = await app.request("/health");
144
+
const data = await res.json();
145
+
146
+
expect(data.services.forumAgent.error).toBe("Invalid credentials");
147
+
});
148
+
149
+
it("includes optional ForumAgent fields when present", async () => {
150
+
const lastAuthAttempt = new Date();
151
+
ctx.forumAgent = {
152
+
isAuthenticated: () => true,
153
+
getStatus: () => ({
154
+
status: "authenticated" as const,
155
+
authenticated: true,
156
+
lastAuthAttempt,
157
+
}),
158
+
} as any;
159
+
160
+
const res = await app.request("/health");
161
+
const data = await res.json();
162
+
163
+
expect(data.services.forumAgent.last_auth_attempt).toBeDefined();
164
});
165
});
+130
apps/appview/src/routes/health.ts
+130
apps/appview/src/routes/health.ts
···
1
import { Hono } from "hono";
2
+
import type { AppContext } from "../lib/app-context.js";
3
4
+
/**
5
+
* Overall health status of the application.
6
+
* - healthy: All services up and running
7
+
* - degraded: Core services up, but some features unavailable (e.g. ForumAgent down)
8
+
* - unhealthy: Critical services down (database or firehose)
9
+
*/
10
+
type HealthStatus = "healthy" | "degraded" | "unhealthy";
11
+
12
+
/**
13
+
* Health check response structure
14
+
*/
15
+
interface HealthResponse {
16
+
status: HealthStatus;
17
+
timestamp: string;
18
+
services: {
19
+
database: {
20
+
status: "up" | "down";
21
+
latency_ms: number;
22
+
};
23
+
firehose: {
24
+
status: "up" | "down";
25
+
connected: boolean;
26
+
last_event_at?: string;
27
+
};
28
+
forumAgent: {
29
+
status: string;
30
+
authenticated: boolean;
31
+
last_auth_attempt?: string;
32
+
retry_count?: number;
33
+
next_retry_at?: string;
34
+
error?: string;
35
+
};
36
+
};
37
+
}
38
+
39
+
/**
40
+
* Health check endpoint for monitoring and operational visibility.
41
+
* Always returns 200 OK (check response body for actual status).
42
+
*
43
+
* Security: This endpoint is public (no auth required) but does not expose
44
+
* sensitive data like DIDs, handles, credentials, or configuration details.
45
+
*/
46
+
export function createHealthRoutes(ctx: AppContext) {
47
+
const app = new Hono();
48
+
49
+
app.get("/health", async (c) => {
50
+
const timestamp = new Date().toISOString();
51
+
52
+
// Check database connectivity
53
+
let dbStatus: "up" | "down" = "up";
54
+
let dbLatency = 0;
55
+
try {
56
+
const start = Date.now();
57
+
await ctx.db.execute("SELECT 1");
58
+
dbLatency = Date.now() - start;
59
+
} catch (error) {
60
+
dbStatus = "down";
61
+
console.error(
62
+
JSON.stringify({
63
+
event: "healthCheck.databaseFailed",
64
+
timestamp,
65
+
error: error instanceof Error ? error.message : String(error),
66
+
})
67
+
);
68
+
}
69
+
70
+
// Check firehose status
71
+
const firehoseStatus = ctx.firehose.isRunning() ? "up" : "down";
72
+
const lastEventAt = ctx.firehose.getLastEventTime();
73
+
74
+
// Check ForumAgent status
75
+
const forumAgentState = ctx.forumAgent?.getStatus() ?? {
76
+
status: "unavailable" as const,
77
+
authenticated: false,
78
+
};
79
+
80
+
// Build response
81
+
const response: HealthResponse = {
82
+
status: "healthy" as HealthStatus,
83
+
timestamp,
84
+
services: {
85
+
database: {
86
+
status: dbStatus,
87
+
latency_ms: dbLatency,
88
+
},
89
+
firehose: {
90
+
status: firehoseStatus,
91
+
connected: firehoseStatus === "up",
92
+
last_event_at: lastEventAt?.toISOString(),
93
+
},
94
+
forumAgent: {
95
+
status: forumAgentState.status,
96
+
authenticated: forumAgentState.authenticated,
97
+
},
98
+
},
99
+
};
100
+
101
+
// Add optional fields for ForumAgent
102
+
if (forumAgentState.lastAuthAttempt) {
103
+
response.services.forumAgent.last_auth_attempt =
104
+
forumAgentState.lastAuthAttempt.toISOString();
105
+
}
106
+
107
+
if (forumAgentState.status === "retrying") {
108
+
response.services.forumAgent.retry_count = forumAgentState.retryCount;
109
+
if (forumAgentState.nextRetryAt) {
110
+
response.services.forumAgent.next_retry_at =
111
+
forumAgentState.nextRetryAt.toISOString();
112
+
}
113
+
}
114
+
115
+
if (forumAgentState.error) {
116
+
response.services.forumAgent.error = forumAgentState.error;
117
+
}
118
+
119
+
// Determine overall status
120
+
if (dbStatus === "down" || firehoseStatus === "down") {
121
+
response.status = "unhealthy";
122
+
} else if (forumAgentState.status !== "authenticated") {
123
+
response.status = "degraded";
124
+
}
125
+
126
+
return c.json(response);
127
+
});
128
+
129
+
return app;
130
+
}
131
+
132
+
// Export legacy health routes for backward compatibility
133
export const healthRoutes = new Hono()
134
.get("/", (c) => c.json({ status: "ok", version: "0.1.0" }))
135
.get("/ready", (c) => c.json({ status: "ready" }));
+2
-1
apps/appview/src/routes/index.ts
+2
-1
apps/appview/src/routes/index.ts
···
1
import { Hono } from "hono";
2
import type { AppContext } from "../lib/app-context.js";
3
-
import { healthRoutes } from "./health.js";
4
import { createForumRoutes } from "./forum.js";
5
import { createCategoriesRoutes } from "./categories.js";
6
import { createTopicsRoutes } from "./topics.js";
···
13
export function createApiRoutes(ctx: AppContext) {
14
return new Hono()
15
.route("/healthz", healthRoutes)
16
.route("/auth", createAuthRoutes(ctx))
17
.route("/forum", createForumRoutes(ctx))
18
.route("/categories", createCategoriesRoutes(ctx))
···
1
import { Hono } from "hono";
2
import type { AppContext } from "../lib/app-context.js";
3
+
import { healthRoutes, createHealthRoutes } from "./health.js";
4
import { createForumRoutes } from "./forum.js";
5
import { createCategoriesRoutes } from "./categories.js";
6
import { createTopicsRoutes } from "./topics.js";
···
13
export function createApiRoutes(ctx: AppContext) {
14
return new Hono()
15
.route("/healthz", healthRoutes)
16
+
.route("/", createHealthRoutes(ctx))
17
.route("/auth", createAuthRoutes(ctx))
18
.route("/forum", createForumRoutes(ctx))
19
.route("/categories", createCategoriesRoutes(ctx))
+108
-3
bruno/AppView API/Health/Check Health.bru
+108
-3
bruno/AppView API/Health/Check Health.bru
···
5
}
6
7
get {
8
+
url: {{appview_url}}/api/health
9
+
}
10
+
11
+
assert {
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
23
docs {
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
}
+2
-1
docs/atproto-forum-plan.md
+2
-1
docs/atproto-forum-plan.md
···
169
- [x] Implement AT Proto OAuth flow (user login via their PDS) — **Complete:** OAuth 2.1 implementation using `@atproto/oauth-client-node` library with PKCE flow, state validation, automatic token refresh, and DPoP. Supports any AT Protocol PDS (not limited to bsky.social). Routes in `apps/appview/src/routes/auth.ts` (ATB-14)
170
- [x] On first login: create `membership` record on user's PDS — **Complete:** Fire-and-forget membership creation integrated into OAuth callback. Helper function `createMembershipForUser()` checks for duplicates, writes `space.atbb.membership` record to user's PDS. Login succeeds even if membership creation fails (graceful degradation). 9 tests (5 unit + 4 integration) verify architectural contract. Implementation in `apps/appview/src/lib/membership.ts` and `apps/appview/src/routes/auth.ts:163-188` (ATB-15, PR #27)
171
- [x] Session management (JWT or similar, backed by DID verification) — **Complete:** Three-layer session architecture using `@atproto/oauth-client-node` library with OAuth session store (`oauth-stores.ts`), cookie-to-DID mapping (`cookie-session-store.ts`), and HTTP-only cookies. Sessions include DID, handle, PDS URL, access tokens with automatic refresh, expiry. Automatic cleanup every 5 minutes. Authentication middleware (`requireAuth`, `optionalAuth`) implemented in `apps/appview/src/middleware/auth.ts` (ATB-14)
172
-
- [ ] Role assignment: admin can set roles via Forum DID records
173
- [ ] Middleware: permission checks on write endpoints
174
175
#### Phase 3: Moderation Basics (Week 6–7)
···
169
- [x] Implement AT Proto OAuth flow (user login via their PDS) — **Complete:** OAuth 2.1 implementation using `@atproto/oauth-client-node` library with PKCE flow, state validation, automatic token refresh, and DPoP. Supports any AT Protocol PDS (not limited to bsky.social). Routes in `apps/appview/src/routes/auth.ts` (ATB-14)
170
- [x] On first login: create `membership` record on user's PDS — **Complete:** Fire-and-forget membership creation integrated into OAuth callback. Helper function `createMembershipForUser()` checks for duplicates, writes `space.atbb.membership` record to user's PDS. Login succeeds even if membership creation fails (graceful degradation). 9 tests (5 unit + 4 integration) verify architectural contract. Implementation in `apps/appview/src/lib/membership.ts` and `apps/appview/src/routes/auth.ts:163-188` (ATB-15, PR #27)
171
- [x] Session management (JWT or similar, backed by DID verification) — **Complete:** Three-layer session architecture using `@atproto/oauth-client-node` library with OAuth session store (`oauth-stores.ts`), cookie-to-DID mapping (`cookie-session-store.ts`), and HTTP-only cookies. Sessions include DID, handle, PDS URL, access tokens with automatic refresh, expiry. Automatic cleanup every 5 minutes. Authentication middleware (`requireAuth`, `optionalAuth`) implemented in `apps/appview/src/middleware/auth.ts` (ATB-14)
172
+
- [x] Forum DID authenticated agent for server-side PDS writes — **Complete:** `ForumAgent` service authenticates as Forum DID on startup with smart retry logic (network errors retry with exponential backoff, auth errors fail permanently). Integrated into `AppContext` with proactive session refresh every 30 minutes. Graceful degradation (server starts even if auth fails). Health endpoint (`GET /api/health`) exposes granular ForumAgent status. Implementation in `apps/appview/src/lib/forum-agent.ts`, health endpoint in `apps/appview/src/routes/health.ts` (ATB-18)
173
+
- [ ] Role assignment: admin can set roles via Forum DID records (ATB-17)
174
- [ ] Middleware: permission checks on write endpoints
175
176
#### Phase 3: Moderation Basics (Week 6–7)
+47
-9
docs/plans/2026-02-13-atb-18-forum-agent-design.md
+47
-9
docs/plans/2026-02-13-atb-18-forum-agent-design.md
···
425
## Acceptance Criteria
426
427
- [x] Design validated with stakeholder
428
-
- [ ] `ForumAgent` service authenticates as Forum DID on AppView startup
429
-
- [ ] Available via `ctx.forumAgent` in AppContext
430
-
- [ ] Auto-refreshes expired sessions proactively
431
-
- [ ] Graceful degradation if auth fails (server starts, write ops return 503)
432
-
- [ ] Smart retry logic: network errors retry with backoff, auth errors fail permanently
433
-
- [ ] Health endpoint exposes ForumAgent status with granular states
434
-
- [ ] Unit tests with mocked PDS
435
-
- [ ] Integration tests verifying agent is wired into AppContext
436
-
- [ ] Health endpoint tests verify no sensitive data exposure
437
438
## Implementation Notes
439
···
442
- Never expose credentials, DIDs, or detailed errors in health endpoint
443
- Log all auth attempts with structured context for debugging
444
- Distinguish network errors (safe to retry) from auth errors (fail permanently)
···
425
## Acceptance Criteria
426
427
- [x] Design validated with stakeholder
428
+
- [x] `ForumAgent` service authenticates as Forum DID on AppView startup
429
+
- [x] Available via `ctx.forumAgent` in AppContext
430
+
- [x] Auto-refreshes expired sessions proactively
431
+
- [x] Graceful degradation if auth fails (server starts, write ops return 503)
432
+
- [x] Smart retry logic: network errors retry with backoff, auth errors fail permanently
433
+
- [x] Health endpoint exposes ForumAgent status with granular states
434
+
- [x] Unit tests with mocked PDS
435
+
- [x] Integration tests verifying agent is wired into AppContext
436
+
- [x] Health endpoint tests verify no sensitive data exposure
437
438
## Implementation Notes
439
···
442
- Never expose credentials, DIDs, or detailed errors in health endpoint
443
- Log all auth attempts with structured context for debugging
444
- Distinguish network errors (safe to retry) from auth errors (fail permanently)
445
+
446
+
## Usage
447
+
448
+
### Checking ForumAgent Availability in Routes
449
+
450
+
```typescript
451
+
export function createModActionRoutes(ctx: AppContext) {
452
+
return new Hono().post("/", async (c) => {
453
+
// Check if ForumAgent is available
454
+
if (!ctx.forumAgent?.isAuthenticated()) {
455
+
return c.json(
456
+
{ error: "Forum write operations temporarily unavailable" },
457
+
503
458
+
);
459
+
}
460
+
461
+
const agent = ctx.forumAgent.getAgent()!;
462
+
// Use agent to write records to Forum PDS...
463
+
});
464
+
}
465
+
```
466
+
467
+
### Monitoring Health
468
+
469
+
```bash
470
+
# Check overall health
471
+
curl http://localhost:3000/api/health
472
+
473
+
# Check ForumAgent status specifically
474
+
curl http://localhost:3000/api/health | jq .services.forumAgent
475
+
```
476
+
477
+
### Environment Variables
478
+
479
+
```
480
+
FORUM_HANDLE=forum.example.com
481
+
FORUM_PASSWORD=app-password-here
482
+
```
+1598
docs/plans/2026-02-13-atb-18-forum-agent.md
+1598
docs/plans/2026-02-13-atb-18-forum-agent.md
···
···
1
+
# ATB-18 Forum DID Agent Implementation Plan
2
+
3
+
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4
+
5
+
**Goal:** Implement a ForumAgent service that authenticates as the Forum DID on AppView startup, manages session lifecycle with smart retry logic, and exposes operational status via a health endpoint.
6
+
7
+
**Architecture:** Create a `ForumAgent` class that wraps `@atproto/api` AtpAgent, integrates into AppContext via dependency injection, implements graceful degradation with smart retry (network errors retry with backoff, auth errors fail permanently), and exposes granular status states for operational visibility.
8
+
9
+
**Tech Stack:** TypeScript, @atproto/api (AtpAgent), Hono (routes), Vitest (testing), Drizzle ORM (database health check)
10
+
11
+
---
12
+
13
+
## Task 1: Add Forum Credentials to Configuration
14
+
15
+
**Files:**
16
+
- Modify: `apps/appview/src/lib/config.ts`
17
+
- Modify: `apps/appview/src/lib/__tests__/config.test.ts`
18
+
19
+
**Step 1: Write failing test for forum credentials**
20
+
21
+
Add to `apps/appview/src/lib/__tests__/config.test.ts`:
22
+
23
+
```typescript
24
+
describe("loadConfig", () => {
25
+
// ... existing tests ...
26
+
27
+
it("loads forum credentials from environment", () => {
28
+
process.env.FORUM_HANDLE = "forum.example.com";
29
+
process.env.FORUM_PASSWORD = "test-password";
30
+
31
+
const config = loadConfig();
32
+
33
+
expect(config.forumHandle).toBe("forum.example.com");
34
+
expect(config.forumPassword).toBe("test-password");
35
+
});
36
+
37
+
it("allows missing forum credentials (optional)", () => {
38
+
delete process.env.FORUM_HANDLE;
39
+
delete process.env.FORUM_PASSWORD;
40
+
41
+
const config = loadConfig();
42
+
43
+
expect(config.forumHandle).toBeUndefined();
44
+
expect(config.forumPassword).toBeUndefined();
45
+
});
46
+
});
47
+
```
48
+
49
+
**Step 2: Run test to verify it fails**
50
+
51
+
```bash
52
+
pnpm --filter @atbb/appview test src/lib/__tests__/config.test.ts
53
+
```
54
+
55
+
Expected: FAIL with "Property 'forumHandle' does not exist on type 'AppConfig'"
56
+
57
+
**Step 3: Add forum credentials to config**
58
+
59
+
In `apps/appview/src/lib/config.ts`, add to `AppConfig` interface:
60
+
61
+
```typescript
62
+
export interface AppConfig {
63
+
port: number;
64
+
databaseUrl: string;
65
+
jetstreamUrl: string;
66
+
pdsUrl: string;
67
+
oauthPublicUrl: string;
68
+
sessionSecret: string;
69
+
sessionTtlDays: number;
70
+
redisUrl?: string;
71
+
forumHandle?: string; // ← NEW
72
+
forumPassword?: string; // ← NEW
73
+
}
74
+
```
75
+
76
+
Add to `loadConfig()` function:
77
+
78
+
```typescript
79
+
export function loadConfig(): AppConfig {
80
+
return {
81
+
port: parseInt(process.env.PORT || "3000", 10),
82
+
databaseUrl: process.env.DATABASE_URL ?? "",
83
+
jetstreamUrl: process.env.JETSTREAM_URL ?? "wss://jetstream2.us-east.bsky.network/subscribe",
84
+
pdsUrl: process.env.PDS_URL ?? "",
85
+
oauthPublicUrl: process.env.OAUTH_PUBLIC_URL ?? "",
86
+
sessionSecret: process.env.SESSION_SECRET ?? "",
87
+
sessionTtlDays: parseInt(process.env.SESSION_TTL_DAYS || "7", 10),
88
+
redisUrl: process.env.REDIS_URL,
89
+
forumHandle: process.env.FORUM_HANDLE, // ← NEW
90
+
forumPassword: process.env.FORUM_PASSWORD, // ← NEW
91
+
};
92
+
}
93
+
```
94
+
95
+
**Step 4: Run test to verify it passes**
96
+
97
+
```bash
98
+
pnpm --filter @atbb/appview test src/lib/__tests__/config.test.ts
99
+
```
100
+
101
+
Expected: PASS (all config tests passing)
102
+
103
+
**Step 5: Commit**
104
+
105
+
```bash
106
+
git add apps/appview/src/lib/config.ts apps/appview/src/lib/__tests__/config.test.ts
107
+
git commit -m "feat(appview): add forum credentials to config
108
+
109
+
- Add forumHandle and forumPassword to AppConfig
110
+
- Load from FORUM_HANDLE and FORUM_PASSWORD env vars
111
+
- Make credentials optional (undefined if not set)
112
+
- Add tests for loading forum credentials"
113
+
```
114
+
115
+
---
116
+
117
+
## Task 2: Create ForumAgent Class with Status Types
118
+
119
+
**Files:**
120
+
- Create: `apps/appview/src/lib/forum-agent.ts`
121
+
- Create: `apps/appview/src/lib/__tests__/forum-agent.test.ts`
122
+
123
+
**Step 1: Write failing test for ForumAgent initialization**
124
+
125
+
Create `apps/appview/src/lib/__tests__/forum-agent.test.ts`:
126
+
127
+
```typescript
128
+
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
129
+
import { ForumAgent } from "../forum-agent.js";
130
+
import { AtpAgent } from "@atproto/api";
131
+
132
+
// Mock @atproto/api
133
+
vi.mock("@atproto/api", () => ({
134
+
AtpAgent: vi.fn(),
135
+
}));
136
+
137
+
describe("ForumAgent", () => {
138
+
let mockAgent: any;
139
+
let mockLogin: any;
140
+
141
+
beforeEach(() => {
142
+
mockLogin = vi.fn();
143
+
mockAgent = {
144
+
login: mockLogin,
145
+
session: null,
146
+
};
147
+
(AtpAgent as any).mockImplementation(() => mockAgent);
148
+
});
149
+
150
+
afterEach(() => {
151
+
vi.clearAllMocks();
152
+
});
153
+
154
+
describe("initialization", () => {
155
+
it("starts with 'initializing' status", () => {
156
+
const agent = new ForumAgent(
157
+
"https://pds.example.com",
158
+
"forum.example.com",
159
+
"password"
160
+
);
161
+
162
+
const status = agent.getStatus();
163
+
expect(status.status).toBe("initializing");
164
+
expect(status.authenticated).toBe(false);
165
+
});
166
+
167
+
it("transitions to 'authenticated' on successful login", async () => {
168
+
mockLogin.mockResolvedValueOnce(undefined);
169
+
mockAgent.session = {
170
+
did: "did:plc:test",
171
+
accessJwt: "token",
172
+
refreshJwt: "refresh",
173
+
};
174
+
175
+
const agent = new ForumAgent(
176
+
"https://pds.example.com",
177
+
"forum.example.com",
178
+
"password"
179
+
);
180
+
await agent.initialize();
181
+
182
+
const status = agent.getStatus();
183
+
expect(status.status).toBe("authenticated");
184
+
expect(status.authenticated).toBe(true);
185
+
expect(agent.isAuthenticated()).toBe(true);
186
+
expect(agent.getAgent()).toBe(mockAgent);
187
+
});
188
+
});
189
+
});
190
+
```
191
+
192
+
**Step 2: Run test to verify it fails**
193
+
194
+
```bash
195
+
pnpm --filter @atbb/appview test src/lib/__tests__/forum-agent.test.ts
196
+
```
197
+
198
+
Expected: FAIL with "Cannot find module '../forum-agent.js'"
199
+
200
+
**Step 3: Create ForumAgent class with basic structure**
201
+
202
+
Create `apps/appview/src/lib/forum-agent.ts`:
203
+
204
+
```typescript
205
+
import { AtpAgent } from "@atproto/api";
206
+
207
+
export type ForumAgentStatus =
208
+
| "initializing"
209
+
| "authenticated"
210
+
| "retrying"
211
+
| "failed"
212
+
| "unavailable";
213
+
214
+
export interface ForumAgentState {
215
+
status: ForumAgentStatus;
216
+
authenticated: boolean;
217
+
lastAuthAttempt?: Date;
218
+
nextRetryAt?: Date;
219
+
retryCount?: number;
220
+
error?: string;
221
+
}
222
+
223
+
/**
224
+
* ForumAgent manages authentication as the Forum DID for server-side PDS writes.
225
+
* Handles session lifecycle with smart retry logic and graceful degradation.
226
+
*/
227
+
export class ForumAgent {
228
+
private agent: AtpAgent | null = null;
229
+
private status: ForumAgentStatus = "initializing";
230
+
private authenticated = false;
231
+
private retryCount = 0;
232
+
private readonly maxRetries = 5;
233
+
private refreshTimer: NodeJS.Timeout | null = null;
234
+
private retryTimer: NodeJS.Timeout | null = null;
235
+
private lastError: string | null = null;
236
+
private lastAuthAttempt: Date | null = null;
237
+
private nextRetryAt: Date | null = null;
238
+
239
+
constructor(
240
+
private readonly pdsUrl: string,
241
+
private readonly handle: string,
242
+
private readonly password: string
243
+
) {
244
+
this.agent = new AtpAgent({ service: pdsUrl });
245
+
}
246
+
247
+
/**
248
+
* Initialize the agent by attempting authentication.
249
+
* Never throws - returns gracefully even on failure.
250
+
*/
251
+
async initialize(): Promise<void> {
252
+
await this.attemptAuth();
253
+
}
254
+
255
+
/**
256
+
* Check if the agent is authenticated and ready for use.
257
+
*/
258
+
isAuthenticated(): boolean {
259
+
return this.authenticated;
260
+
}
261
+
262
+
/**
263
+
* Get the underlying AtpAgent for PDS operations.
264
+
* Returns null if not authenticated.
265
+
*/
266
+
getAgent(): AtpAgent | null {
267
+
return this.authenticated ? this.agent : null;
268
+
}
269
+
270
+
/**
271
+
* Get current agent status for health reporting.
272
+
*/
273
+
getStatus(): ForumAgentState {
274
+
const state: ForumAgentState = {
275
+
status: this.status,
276
+
authenticated: this.authenticated,
277
+
};
278
+
279
+
if (this.lastAuthAttempt) {
280
+
state.lastAuthAttempt = this.lastAuthAttempt;
281
+
}
282
+
283
+
if (this.status === "retrying") {
284
+
state.retryCount = this.retryCount;
285
+
if (this.nextRetryAt) {
286
+
state.nextRetryAt = this.nextRetryAt;
287
+
}
288
+
}
289
+
290
+
if (this.lastError) {
291
+
state.error = this.lastError;
292
+
}
293
+
294
+
return state;
295
+
}
296
+
297
+
/**
298
+
* Attempt to authenticate with the PDS.
299
+
* Implements smart retry logic and error classification.
300
+
*/
301
+
private async attemptAuth(): Promise<void> {
302
+
try {
303
+
this.lastAuthAttempt = new Date();
304
+
await this.agent!.login({
305
+
identifier: this.handle,
306
+
password: this.password,
307
+
});
308
+
309
+
// Success!
310
+
this.status = "authenticated";
311
+
this.authenticated = true;
312
+
this.retryCount = 0;
313
+
this.lastError = null;
314
+
this.nextRetryAt = null;
315
+
316
+
console.info("Forum DID authentication successful", {
317
+
service: "ForumAgent",
318
+
handle: this.handle,
319
+
did: this.agent!.session?.did,
320
+
});
321
+
322
+
// TODO: Schedule proactive session refresh
323
+
} catch (error) {
324
+
// TODO: Implement error classification and retry logic
325
+
this.status = "failed";
326
+
this.authenticated = false;
327
+
this.lastError = "Authentication failed";
328
+
console.error("Forum DID authentication failed", {
329
+
service: "ForumAgent",
330
+
handle: this.handle,
331
+
error: error instanceof Error ? error.message : String(error),
332
+
});
333
+
}
334
+
}
335
+
336
+
/**
337
+
* Clean up resources (timers, etc).
338
+
*/
339
+
async shutdown(): Promise<void> {
340
+
if (this.refreshTimer) {
341
+
clearTimeout(this.refreshTimer);
342
+
this.refreshTimer = null;
343
+
}
344
+
if (this.retryTimer) {
345
+
clearTimeout(this.retryTimer);
346
+
this.retryTimer = null;
347
+
}
348
+
}
349
+
}
350
+
```
351
+
352
+
**Step 4: Run test to verify it passes**
353
+
354
+
```bash
355
+
pnpm --filter @atbb/appview test src/lib/__tests__/forum-agent.test.ts
356
+
```
357
+
358
+
Expected: PASS (2 tests passing)
359
+
360
+
**Step 5: Commit**
361
+
362
+
```bash
363
+
git add apps/appview/src/lib/forum-agent.ts apps/appview/src/lib/__tests__/forum-agent.test.ts
364
+
git commit -m "feat(appview): create ForumAgent class with basic structure
365
+
366
+
- Define ForumAgentStatus and ForumAgentState types
367
+
- Implement initialization with status tracking
368
+
- Add getStatus(), isAuthenticated(), getAgent() methods
369
+
- Add shutdown() for resource cleanup
370
+
- Add tests for initialization and successful auth"
371
+
```
372
+
373
+
---
374
+
375
+
## Task 3: Implement Error Classification and Retry Logic
376
+
377
+
**Files:**
378
+
- Modify: `apps/appview/src/lib/forum-agent.ts`
379
+
- Modify: `apps/appview/src/lib/__tests__/forum-agent.test.ts`
380
+
381
+
**Step 1: Write failing tests for error classification**
382
+
383
+
Add to `apps/appview/src/lib/__tests__/forum-agent.test.ts`:
384
+
385
+
```typescript
386
+
describe("error classification", () => {
387
+
it("fails permanently on auth errors (no retry)", async () => {
388
+
const authError = new Error("Invalid identifier or password");
389
+
mockLogin.mockRejectedValueOnce(authError);
390
+
391
+
const agent = new ForumAgent(
392
+
"https://pds.example.com",
393
+
"forum.example.com",
394
+
"wrong-password"
395
+
);
396
+
await agent.initialize();
397
+
398
+
const status = agent.getStatus();
399
+
expect(status.status).toBe("failed");
400
+
expect(status.authenticated).toBe(false);
401
+
expect(status.error).toContain("invalid credentials");
402
+
expect(mockLogin).toHaveBeenCalledTimes(1); // No retry
403
+
});
404
+
405
+
it("retries on network errors with exponential backoff", async () => {
406
+
vi.useFakeTimers();
407
+
408
+
const networkError = new Error("ECONNREFUSED");
409
+
(networkError as any).code = "ECONNREFUSED";
410
+
mockLogin.mockRejectedValueOnce(networkError);
411
+
412
+
const agent = new ForumAgent(
413
+
"https://pds.example.com",
414
+
"forum.example.com",
415
+
"password"
416
+
);
417
+
await agent.initialize();
418
+
419
+
const status = agent.getStatus();
420
+
expect(status.status).toBe("retrying");
421
+
expect(status.authenticated).toBe(false);
422
+
expect(status.retryCount).toBe(1);
423
+
expect(status.nextRetryAt).toBeDefined();
424
+
expect(mockLogin).toHaveBeenCalledTimes(1);
425
+
426
+
// Fast-forward to next retry (10 seconds)
427
+
mockLogin.mockResolvedValueOnce(undefined);
428
+
mockAgent.session = { did: "did:plc:test", accessJwt: "token" };
429
+
430
+
await vi.advanceTimersByTimeAsync(10000);
431
+
432
+
const statusAfterRetry = agent.getStatus();
433
+
expect(statusAfterRetry.status).toBe("authenticated");
434
+
expect(statusAfterRetry.authenticated).toBe(true);
435
+
expect(mockLogin).toHaveBeenCalledTimes(2);
436
+
437
+
vi.useRealTimers();
438
+
});
439
+
440
+
it("stops retrying after max attempts", async () => {
441
+
vi.useFakeTimers();
442
+
443
+
const networkError = new Error("ETIMEDOUT");
444
+
(networkError as any).code = "ETIMEDOUT";
445
+
mockLogin.mockRejectedValue(networkError);
446
+
447
+
const agent = new ForumAgent(
448
+
"https://pds.example.com",
449
+
"forum.example.com",
450
+
"password"
451
+
);
452
+
await agent.initialize();
453
+
454
+
// Advance through all retry attempts (5 retries)
455
+
for (let i = 0; i < 5; i++) {
456
+
const delay = Math.min(10000 * Math.pow(2, i), 600000);
457
+
await vi.advanceTimersByTimeAsync(delay);
458
+
}
459
+
460
+
const status = agent.getStatus();
461
+
expect(status.status).toBe("failed");
462
+
expect(status.error).toContain("max retries");
463
+
expect(mockLogin).toHaveBeenCalledTimes(6); // Initial + 5 retries
464
+
465
+
vi.useRealTimers();
466
+
});
467
+
});
468
+
```
469
+
470
+
**Step 2: Run test to verify it fails**
471
+
472
+
```bash
473
+
pnpm --filter @atbb/appview test src/lib/__tests__/forum-agent.test.ts
474
+
```
475
+
476
+
Expected: FAIL (tests expect retry behavior but not implemented)
477
+
478
+
**Step 3: Implement error classification helpers**
479
+
480
+
In `apps/appview/src/lib/forum-agent.ts`, add error classification functions before the class:
481
+
482
+
```typescript
483
+
/**
484
+
* Check if an error is an authentication error (wrong credentials).
485
+
* These should NOT be retried to avoid account lockouts.
486
+
*/
487
+
function isAuthError(error: unknown): boolean {
488
+
if (!(error instanceof Error)) return false;
489
+
490
+
const message = error.message.toLowerCase();
491
+
return (
492
+
message.includes("invalid identifier") ||
493
+
message.includes("invalid password") ||
494
+
message.includes("authentication failed") ||
495
+
message.includes("unauthorized")
496
+
);
497
+
}
498
+
499
+
/**
500
+
* Check if an error is a network error (transient failure).
501
+
* These are safe to retry with exponential backoff.
502
+
*/
503
+
function isNetworkError(error: unknown): boolean {
504
+
if (!(error instanceof Error)) return false;
505
+
506
+
const code = (error as any).code;
507
+
const message = error.message.toLowerCase();
508
+
509
+
return (
510
+
code === "ECONNREFUSED" ||
511
+
code === "ETIMEDOUT" ||
512
+
code === "ENOTFOUND" ||
513
+
code === "ENETUNREACH" ||
514
+
code === "ECONNRESET" ||
515
+
message.includes("network") ||
516
+
message.includes("fetch failed") ||
517
+
message.includes("service unavailable")
518
+
);
519
+
}
520
+
```
521
+
522
+
**Step 4: Implement retry logic in attemptAuth**
523
+
524
+
Replace the `attemptAuth` method in `apps/appview/src/lib/forum-agent.ts`:
525
+
526
+
```typescript
527
+
private async attemptAuth(): Promise<void> {
528
+
try {
529
+
this.lastAuthAttempt = new Date();
530
+
await this.agent!.login({
531
+
identifier: this.handle,
532
+
password: this.password,
533
+
});
534
+
535
+
// Success!
536
+
this.status = "authenticated";
537
+
this.authenticated = true;
538
+
this.retryCount = 0;
539
+
this.lastError = null;
540
+
this.nextRetryAt = null;
541
+
542
+
const logLevel = this.retryCount > 0 ? "info" : "debug";
543
+
console[logLevel]("Forum DID authentication successful", {
544
+
service: "ForumAgent",
545
+
handle: this.handle,
546
+
did: this.agent!.session?.did,
547
+
retriedAfterFailures: this.retryCount > 0,
548
+
});
549
+
550
+
// TODO: Schedule proactive session refresh
551
+
} catch (error) {
552
+
this.authenticated = false;
553
+
554
+
// Check error type for smart retry
555
+
if (isAuthError(error)) {
556
+
// Permanent failure - don't retry to avoid account lockouts
557
+
this.status = "failed";
558
+
this.lastError = "Authentication failed: invalid credentials";
559
+
this.retryCount = 0;
560
+
this.nextRetryAt = null;
561
+
562
+
console.error("Forum DID auth failed permanently (invalid credentials)", {
563
+
service: "ForumAgent",
564
+
handle: this.handle,
565
+
error: error instanceof Error ? error.message : String(error),
566
+
});
567
+
return;
568
+
}
569
+
570
+
if (isNetworkError(error) && this.retryCount < this.maxRetries) {
571
+
// Transient failure - retry with exponential backoff
572
+
this.status = "retrying";
573
+
const delay = Math.min(10000 * Math.pow(2, this.retryCount), 600000);
574
+
this.retryCount++;
575
+
this.nextRetryAt = new Date(Date.now() + delay);
576
+
this.lastError = "Connection to PDS temporarily unavailable";
577
+
578
+
console.warn("Forum DID auth failed, will retry", {
579
+
service: "ForumAgent",
580
+
handle: this.handle,
581
+
attempt: this.retryCount,
582
+
maxAttempts: this.maxRetries,
583
+
retryIn: `${delay}ms`,
584
+
error: error instanceof Error ? error.message : String(error),
585
+
});
586
+
587
+
this.retryTimer = setTimeout(() => {
588
+
this.attemptAuth();
589
+
}, delay);
590
+
return;
591
+
}
592
+
593
+
// Unknown error or max retries exceeded
594
+
this.status = "failed";
595
+
this.lastError = this.retryCount >= this.maxRetries
596
+
? "Auth failed after max retries"
597
+
: "Authentication failed";
598
+
this.nextRetryAt = null;
599
+
600
+
console.error("Forum DID auth failed", {
601
+
service: "ForumAgent",
602
+
handle: this.handle,
603
+
attempts: this.retryCount + 1,
604
+
reason: this.retryCount >= this.maxRetries ? "max retries exceeded" : "unknown error",
605
+
error: error instanceof Error ? error.message : String(error),
606
+
});
607
+
}
608
+
}
609
+
```
610
+
611
+
**Step 5: Run test to verify it passes**
612
+
613
+
```bash
614
+
pnpm --filter @atbb/appview test src/lib/__tests__/forum-agent.test.ts
615
+
```
616
+
617
+
Expected: PASS (all 5 tests passing)
618
+
619
+
**Step 6: Commit**
620
+
621
+
```bash
622
+
git add apps/appview/src/lib/forum-agent.ts apps/appview/src/lib/__tests__/forum-agent.test.ts
623
+
git commit -m "feat(appview): implement error classification and retry logic in ForumAgent
624
+
625
+
- Add isAuthError() and isNetworkError() helpers
626
+
- Auth errors fail permanently (no retry, prevent lockouts)
627
+
- Network errors retry with exponential backoff (10s, 30s, 1m, 5m, 10m)
628
+
- Stop retrying after 5 failed attempts
629
+
- Update status to 'retrying' during retry attempts
630
+
- Add comprehensive tests for error classification and retry behavior"
631
+
```
632
+
633
+
---
634
+
635
+
## Task 4: Implement Proactive Session Refresh
636
+
637
+
**Files:**
638
+
- Modify: `apps/appview/src/lib/forum-agent.ts`
639
+
- Modify: `apps/appview/src/lib/__tests__/forum-agent.test.ts`
640
+
641
+
**Step 1: Write failing test for session refresh**
642
+
643
+
Add to `apps/appview/src/lib/__tests__/forum-agent.test.ts`:
644
+
645
+
```typescript
646
+
describe("session refresh", () => {
647
+
it("schedules proactive refresh after successful auth", async () => {
648
+
vi.useFakeTimers();
649
+
650
+
mockLogin.mockResolvedValueOnce(undefined);
651
+
mockAgent.session = { did: "did:plc:test", accessJwt: "token" };
652
+
653
+
const agent = new ForumAgent(
654
+
"https://pds.example.com",
655
+
"forum.example.com",
656
+
"password"
657
+
);
658
+
await agent.initialize();
659
+
660
+
expect(agent.isAuthenticated()).toBe(true);
661
+
662
+
// Fast-forward 30 minutes to trigger refresh
663
+
const mockResumeSession = vi.fn().mockResolvedValue(undefined);
664
+
mockAgent.resumeSession = mockResumeSession;
665
+
666
+
await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
667
+
668
+
expect(mockResumeSession).toHaveBeenCalled();
669
+
670
+
vi.useRealTimers();
671
+
});
672
+
673
+
it("retries if refresh fails with network error", async () => {
674
+
vi.useFakeTimers();
675
+
676
+
mockLogin.mockResolvedValueOnce(undefined);
677
+
mockAgent.session = { did: "did:plc:test", accessJwt: "token" };
678
+
679
+
const agent = new ForumAgent(
680
+
"https://pds.example.com",
681
+
"forum.example.com",
682
+
"password"
683
+
);
684
+
await agent.initialize();
685
+
686
+
// Simulate refresh failure
687
+
const networkError = new Error("ECONNREFUSED");
688
+
(networkError as any).code = "ECONNREFUSED";
689
+
const mockResumeSession = vi.fn().mockRejectedValueOnce(networkError);
690
+
mockAgent.resumeSession = mockResumeSession;
691
+
692
+
await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
693
+
694
+
// Should transition to retrying status
695
+
const status = agent.getStatus();
696
+
expect(status.status).toBe("retrying");
697
+
expect(status.authenticated).toBe(false);
698
+
699
+
vi.useRealTimers();
700
+
});
701
+
});
702
+
```
703
+
704
+
**Step 2: Run test to verify it fails**
705
+
706
+
```bash
707
+
pnpm --filter @atbb/appview test src/lib/__tests__/forum-agent.test.ts
708
+
```
709
+
710
+
Expected: FAIL (refresh not implemented)
711
+
712
+
**Step 3: Implement session refresh**
713
+
714
+
In `apps/appview/src/lib/forum-agent.ts`, add a method to schedule refresh:
715
+
716
+
```typescript
717
+
/**
718
+
* Schedule proactive session refresh to prevent expiry.
719
+
* Runs every 30 minutes to keep session alive.
720
+
*/
721
+
private scheduleRefresh(): void {
722
+
// Clear any existing timer
723
+
if (this.refreshTimer) {
724
+
clearTimeout(this.refreshTimer);
725
+
}
726
+
727
+
// Schedule refresh check every 30 minutes
728
+
this.refreshTimer = setTimeout(async () => {
729
+
await this.refreshSession();
730
+
}, 30 * 60 * 1000); // 30 minutes
731
+
}
732
+
733
+
/**
734
+
* Attempt to refresh the current session.
735
+
* Falls back to full re-auth if refresh fails.
736
+
*/
737
+
private async refreshSession(): Promise<void> {
738
+
if (!this.agent || !this.authenticated) {
739
+
return;
740
+
}
741
+
742
+
try {
743
+
await this.agent.resumeSession(this.agent.session!);
744
+
745
+
console.debug("Forum DID session refreshed successfully", {
746
+
service: "ForumAgent",
747
+
did: this.agent.session?.did,
748
+
});
749
+
750
+
// Schedule next refresh
751
+
this.scheduleRefresh();
752
+
} catch (error) {
753
+
console.warn("Forum DID session refresh failed, will re-authenticate", {
754
+
service: "ForumAgent",
755
+
error: error instanceof Error ? error.message : String(error),
756
+
});
757
+
758
+
// Refresh failed - transition to retrying and attempt full re-auth
759
+
this.authenticated = false;
760
+
this.retryCount = 0;
761
+
await this.attemptAuth();
762
+
}
763
+
}
764
+
```
765
+
766
+
Update the `attemptAuth` method to call `scheduleRefresh` on success:
767
+
768
+
```typescript
769
+
// In attemptAuth(), after setting authenticated = true:
770
+
this.scheduleRefresh();
771
+
```
772
+
773
+
**Step 4: Run test to verify it passes**
774
+
775
+
```bash
776
+
pnpm --filter @atbb/appview test src/lib/__tests__/forum-agent.test.ts
777
+
```
778
+
779
+
Expected: PASS (all 7 tests passing)
780
+
781
+
**Step 5: Commit**
782
+
783
+
```bash
784
+
git add apps/appview/src/lib/forum-agent.ts apps/appview/src/lib/__tests__/forum-agent.test.ts
785
+
git commit -m "feat(appview): implement proactive session refresh in ForumAgent
786
+
787
+
- Add scheduleRefresh() to run every 30 minutes
788
+
- Add refreshSession() using agent.resumeSession()
789
+
- Fall back to full re-auth if refresh fails
790
+
- Add tests for session refresh and refresh failure handling"
791
+
```
792
+
793
+
---
794
+
795
+
## Task 5: Integrate ForumAgent into AppContext
796
+
797
+
**Files:**
798
+
- Modify: `apps/appview/src/lib/app-context.ts`
799
+
- Modify: `apps/appview/src/lib/__tests__/app-context.test.ts`
800
+
801
+
**Step 1: Write failing test for ForumAgent in context**
802
+
803
+
Create `apps/appview/src/lib/__tests__/app-context.test.ts`:
804
+
805
+
```typescript
806
+
import { describe, it, expect, vi, beforeEach } from "vitest";
807
+
import { createAppContext, destroyAppContext } from "../app-context.js";
808
+
import type { AppConfig } from "../config.js";
809
+
810
+
// Mock dependencies
811
+
vi.mock("@atbb/db", () => ({
812
+
createDb: vi.fn(() => ({})),
813
+
}));
814
+
815
+
vi.mock("../firehose.js", () => ({
816
+
FirehoseService: vi.fn(() => ({
817
+
start: vi.fn(),
818
+
stop: vi.fn(),
819
+
})),
820
+
}));
821
+
822
+
vi.mock("@atproto/oauth-client-node", () => ({
823
+
NodeOAuthClient: vi.fn(() => ({
824
+
clientMetadata: {},
825
+
})),
826
+
}));
827
+
828
+
vi.mock("../oauth-stores.js", () => ({
829
+
OAuthStateStore: vi.fn(() => ({ destroy: vi.fn() })),
830
+
OAuthSessionStore: vi.fn(() => ({ destroy: vi.fn() })),
831
+
}));
832
+
833
+
vi.mock("../cookie-session-store.js", () => ({
834
+
CookieSessionStore: vi.fn(() => ({ destroy: vi.fn() })),
835
+
}));
836
+
837
+
vi.mock("../forum-agent.js", () => ({
838
+
ForumAgent: vi.fn(() => ({
839
+
initialize: vi.fn(),
840
+
shutdown: vi.fn(),
841
+
isAuthenticated: vi.fn(() => true),
842
+
})),
843
+
}));
844
+
845
+
describe("AppContext", () => {
846
+
let config: AppConfig;
847
+
848
+
beforeEach(() => {
849
+
config = {
850
+
port: 3000,
851
+
databaseUrl: "postgres://localhost/test",
852
+
jetstreamUrl: "wss://jetstream.example.com",
853
+
pdsUrl: "https://pds.example.com",
854
+
oauthPublicUrl: "http://localhost:3000",
855
+
sessionSecret: "test-secret",
856
+
sessionTtlDays: 7,
857
+
forumHandle: "forum.example.com",
858
+
forumPassword: "test-password",
859
+
};
860
+
});
861
+
862
+
describe("createAppContext", () => {
863
+
it("creates ForumAgent when credentials are provided", async () => {
864
+
const ctx = await createAppContext(config);
865
+
866
+
expect(ctx.forumAgent).toBeDefined();
867
+
expect(ctx.forumAgent).not.toBeNull();
868
+
});
869
+
870
+
it("sets forumAgent to null when credentials are missing", async () => {
871
+
config.forumHandle = undefined;
872
+
config.forumPassword = undefined;
873
+
874
+
const ctx = await createAppContext(config);
875
+
876
+
expect(ctx.forumAgent).toBeNull();
877
+
});
878
+
});
879
+
880
+
describe("destroyAppContext", () => {
881
+
it("shuts down ForumAgent if present", async () => {
882
+
const ctx = await createAppContext(config);
883
+
const shutdownSpy = vi.spyOn(ctx.forumAgent!, "shutdown");
884
+
885
+
await destroyAppContext(ctx);
886
+
887
+
expect(shutdownSpy).toHaveBeenCalled();
888
+
});
889
+
890
+
it("handles null ForumAgent gracefully", async () => {
891
+
config.forumHandle = undefined;
892
+
config.forumPassword = undefined;
893
+
const ctx = await createAppContext(config);
894
+
895
+
await expect(destroyAppContext(ctx)).resolves.not.toThrow();
896
+
});
897
+
});
898
+
});
899
+
```
900
+
901
+
**Step 2: Run test to verify it fails**
902
+
903
+
```bash
904
+
pnpm --filter @atbb/appview test src/lib/__tests__/app-context.test.ts
905
+
```
906
+
907
+
Expected: FAIL (forumAgent not in context)
908
+
909
+
**Step 3: Add ForumAgent to AppContext**
910
+
911
+
In `apps/appview/src/lib/app-context.ts`, update imports:
912
+
913
+
```typescript
914
+
import { ForumAgent } from "./forum-agent.js";
915
+
```
916
+
917
+
Update the `AppContext` interface:
918
+
919
+
```typescript
920
+
export interface AppContext {
921
+
config: AppConfig;
922
+
db: Database;
923
+
firehose: FirehoseService;
924
+
oauthClient: NodeOAuthClient;
925
+
oauthStateStore: OAuthStateStore;
926
+
oauthSessionStore: OAuthSessionStore;
927
+
cookieSessionStore: CookieSessionStore;
928
+
forumAgent: ForumAgent | null; // ← NEW
929
+
}
930
+
```
931
+
932
+
Update `createAppContext` function to initialize ForumAgent:
933
+
934
+
```typescript
935
+
export async function createAppContext(config: AppConfig): Promise<AppContext> {
936
+
const db = createDb(config.databaseUrl);
937
+
const firehose = new FirehoseService(db, config.jetstreamUrl);
938
+
939
+
// Initialize OAuth stores
940
+
const oauthStateStore = new OAuthStateStore();
941
+
const oauthSessionStore = new OAuthSessionStore();
942
+
const cookieSessionStore = new CookieSessionStore();
943
+
944
+
// ... existing OAuth client setup ...
945
+
946
+
// Initialize ForumAgent (soft failure - never throws)
947
+
let forumAgent: ForumAgent | null = null;
948
+
if (config.forumHandle && config.forumPassword) {
949
+
forumAgent = new ForumAgent(
950
+
config.pdsUrl,
951
+
config.forumHandle,
952
+
config.forumPassword
953
+
);
954
+
await forumAgent.initialize();
955
+
} else {
956
+
console.warn("Forum DID credentials not configured - write operations disabled");
957
+
}
958
+
959
+
return {
960
+
config,
961
+
db,
962
+
firehose,
963
+
oauthClient,
964
+
oauthStateStore,
965
+
oauthSessionStore,
966
+
cookieSessionStore,
967
+
forumAgent, // ← NEW
968
+
};
969
+
}
970
+
```
971
+
972
+
Update `destroyAppContext` to clean up ForumAgent:
973
+
974
+
```typescript
975
+
export async function destroyAppContext(ctx: AppContext): Promise<void> {
976
+
await ctx.firehose.stop();
977
+
978
+
if (ctx.forumAgent) {
979
+
await ctx.forumAgent.shutdown();
980
+
}
981
+
982
+
// Clean up OAuth store timers
983
+
ctx.oauthStateStore.destroy();
984
+
ctx.oauthSessionStore.destroy();
985
+
ctx.cookieSessionStore.destroy();
986
+
987
+
// Future: close database connection when needed
988
+
}
989
+
```
990
+
991
+
**Step 4: Run test to verify it passes**
992
+
993
+
```bash
994
+
pnpm --filter @atbb/appview test src/lib/__tests__/app-context.test.ts
995
+
```
996
+
997
+
Expected: PASS (all 4 tests passing)
998
+
999
+
**Step 5: Commit**
1000
+
1001
+
```bash
1002
+
git add apps/appview/src/lib/app-context.ts apps/appview/src/lib/__tests__/app-context.test.ts
1003
+
git commit -m "feat(appview): integrate ForumAgent into AppContext
1004
+
1005
+
- Add forumAgent to AppContext interface (nullable)
1006
+
- Initialize ForumAgent in createAppContext if credentials provided
1007
+
- Clean up ForumAgent in destroyAppContext
1008
+
- Add tests for ForumAgent integration with AppContext"
1009
+
```
1010
+
1011
+
---
1012
+
1013
+
## Task 6: Create Health Endpoint
1014
+
1015
+
**Files:**
1016
+
- Create: `apps/appview/src/routes/health.ts`
1017
+
- Create: `apps/appview/src/routes/__tests__/health.test.ts`
1018
+
- Modify: `apps/appview/src/routes/index.ts`
1019
+
1020
+
**Step 1: Write failing test for health endpoint**
1021
+
1022
+
Create `apps/appview/src/routes/__tests__/health.test.ts`:
1023
+
1024
+
```typescript
1025
+
import { describe, it, expect, beforeEach } from "vitest";
1026
+
import { Hono } from "hono";
1027
+
import { createHealthRoutes } from "../health.js";
1028
+
import type { AppContext } from "../../lib/app-context.js";
1029
+
1030
+
describe("GET /health", () => {
1031
+
let app: Hono;
1032
+
let ctx: AppContext;
1033
+
1034
+
beforeEach(() => {
1035
+
// Mock AppContext
1036
+
ctx = {
1037
+
config: {} as any,
1038
+
db: {} as any,
1039
+
firehose: {
1040
+
isRunning: () => true,
1041
+
getLastEventTime: () => new Date(),
1042
+
} as any,
1043
+
oauthClient: {} as any,
1044
+
oauthStateStore: {} as any,
1045
+
oauthSessionStore: {} as any,
1046
+
cookieSessionStore: {} as any,
1047
+
forumAgent: {
1048
+
isAuthenticated: () => true,
1049
+
getStatus: () => ({
1050
+
status: "authenticated" as const,
1051
+
authenticated: true,
1052
+
}),
1053
+
} as any,
1054
+
};
1055
+
1056
+
app = new Hono().route("/", createHealthRoutes(ctx));
1057
+
});
1058
+
1059
+
it("returns 200 with healthy status when all services up", async () => {
1060
+
const res = await app.request("/health");
1061
+
1062
+
expect(res.status).toBe(200);
1063
+
const data = await res.json();
1064
+
expect(data.status).toBe("healthy");
1065
+
expect(data.timestamp).toBeDefined();
1066
+
expect(data.services.database.status).toBe("up");
1067
+
expect(data.services.firehose.status).toBe("up");
1068
+
expect(data.services.forumAgent.status).toBe("authenticated");
1069
+
});
1070
+
1071
+
it("returns degraded status when ForumAgent not authenticated", async () => {
1072
+
ctx.forumAgent = {
1073
+
isAuthenticated: () => false,
1074
+
getStatus: () => ({
1075
+
status: "retrying" as const,
1076
+
authenticated: false,
1077
+
retryCount: 2,
1078
+
nextRetryAt: new Date(Date.now() + 60000),
1079
+
error: "Connection to PDS temporarily unavailable",
1080
+
}),
1081
+
} as any;
1082
+
1083
+
const res = await app.request("/health");
1084
+
1085
+
expect(res.status).toBe(200);
1086
+
const data = await res.json();
1087
+
expect(data.status).toBe("degraded");
1088
+
expect(data.services.forumAgent.status).toBe("retrying");
1089
+
expect(data.services.forumAgent.retry_count).toBe(2);
1090
+
expect(data.services.forumAgent.next_retry_at).toBeDefined();
1091
+
});
1092
+
1093
+
it("does not expose sensitive data", async () => {
1094
+
const res = await app.request("/health");
1095
+
const data = await res.json();
1096
+
1097
+
// Should not contain DIDs, handles, or configuration details
1098
+
const jsonStr = JSON.stringify(data);
1099
+
expect(jsonStr).not.toContain("did:plc");
1100
+
expect(jsonStr).not.toContain("forum.example.com");
1101
+
expect(jsonStr).not.toContain("password");
1102
+
expect(jsonStr).not.toContain("DATABASE_URL");
1103
+
});
1104
+
});
1105
+
```
1106
+
1107
+
**Step 2: Run test to verify it fails**
1108
+
1109
+
```bash
1110
+
pnpm --filter @atbb/appview test src/routes/__tests__/health.test.ts
1111
+
```
1112
+
1113
+
Expected: FAIL (module not found)
1114
+
1115
+
**Step 3: Create health endpoint**
1116
+
1117
+
Create `apps/appview/src/routes/health.ts`:
1118
+
1119
+
```typescript
1120
+
import { Hono } from "hono";
1121
+
import type { AppContext } from "../lib/app-context.js";
1122
+
1123
+
/**
1124
+
* Overall health status of the application.
1125
+
* - healthy: All services up and running
1126
+
* - degraded: Core services up, but some features unavailable (e.g. ForumAgent down)
1127
+
* - unhealthy: Critical services down (database or firehose)
1128
+
*/
1129
+
type HealthStatus = "healthy" | "degraded" | "unhealthy";
1130
+
1131
+
/**
1132
+
* Health check endpoint for monitoring and operational visibility.
1133
+
* Always returns 200 OK (check response body for actual status).
1134
+
*
1135
+
* Security: This endpoint is public (no auth required) but does not expose
1136
+
* sensitive data like DIDs, handles, credentials, or configuration details.
1137
+
*/
1138
+
export function createHealthRoutes(ctx: AppContext) {
1139
+
const app = new Hono();
1140
+
1141
+
app.get("/health", async (c) => {
1142
+
const timestamp = new Date().toISOString();
1143
+
1144
+
// Check database connectivity
1145
+
let dbStatus: "up" | "down" = "up";
1146
+
let dbLatency = 0;
1147
+
try {
1148
+
const start = Date.now();
1149
+
await ctx.db.execute("SELECT 1");
1150
+
dbLatency = Date.now() - start;
1151
+
} catch (error) {
1152
+
dbStatus = "down";
1153
+
console.error("Database health check failed", {
1154
+
error: error instanceof Error ? error.message : String(error),
1155
+
});
1156
+
}
1157
+
1158
+
// Check firehose status
1159
+
const firehoseStatus = ctx.firehose.isRunning() ? "up" : "down";
1160
+
const lastEventAt = ctx.firehose.getLastEventTime();
1161
+
1162
+
// Check ForumAgent status
1163
+
const forumAgentState = ctx.forumAgent?.getStatus() ?? {
1164
+
status: "unavailable" as const,
1165
+
authenticated: false,
1166
+
};
1167
+
1168
+
// Build response
1169
+
const response: any = {
1170
+
status: "healthy" as HealthStatus,
1171
+
timestamp,
1172
+
services: {
1173
+
database: {
1174
+
status: dbStatus,
1175
+
latency_ms: dbLatency,
1176
+
},
1177
+
firehose: {
1178
+
status: firehoseStatus,
1179
+
connected: ctx.firehose.isRunning(),
1180
+
last_event_at: lastEventAt?.toISOString(),
1181
+
},
1182
+
forumAgent: {
1183
+
status: forumAgentState.status,
1184
+
authenticated: forumAgentState.authenticated,
1185
+
},
1186
+
},
1187
+
};
1188
+
1189
+
// Add optional fields for ForumAgent
1190
+
if (forumAgentState.lastAuthAttempt) {
1191
+
response.services.forumAgent.last_auth_attempt =
1192
+
forumAgentState.lastAuthAttempt.toISOString();
1193
+
}
1194
+
1195
+
if (forumAgentState.status === "retrying") {
1196
+
response.services.forumAgent.retry_count = forumAgentState.retryCount;
1197
+
if (forumAgentState.nextRetryAt) {
1198
+
response.services.forumAgent.next_retry_at =
1199
+
forumAgentState.nextRetryAt.toISOString();
1200
+
}
1201
+
}
1202
+
1203
+
if (forumAgentState.error) {
1204
+
response.services.forumAgent.error = forumAgentState.error;
1205
+
}
1206
+
1207
+
// Determine overall status
1208
+
if (dbStatus === "down" || firehoseStatus === "down") {
1209
+
response.status = "unhealthy";
1210
+
} else if (forumAgentState.status !== "authenticated") {
1211
+
response.status = "degraded";
1212
+
}
1213
+
1214
+
return c.json(response);
1215
+
});
1216
+
1217
+
return app;
1218
+
}
1219
+
```
1220
+
1221
+
**Step 4: Run test to verify it passes**
1222
+
1223
+
```bash
1224
+
pnpm --filter @atbb/appview test src/routes/__tests__/health.test.ts
1225
+
```
1226
+
1227
+
Expected: PASS (all 3 tests passing)
1228
+
1229
+
**Step 5: Wire up health routes in main API**
1230
+
1231
+
In `apps/appview/src/routes/index.ts`, add import and route:
1232
+
1233
+
```typescript
1234
+
import { createHealthRoutes } from "./health.js";
1235
+
1236
+
export function createApiRoutes(ctx: AppContext) {
1237
+
const app = new Hono();
1238
+
1239
+
app.route("/auth", createAuthRoutes(ctx));
1240
+
app.route("/forum", createForumRoutes(ctx));
1241
+
app.route("/categories", createCategoryRoutes(ctx));
1242
+
app.route("/topics", createTopicRoutes(ctx));
1243
+
app.route("/posts", createPostRoutes(ctx));
1244
+
app.route("/", createHealthRoutes(ctx)); // ← NEW: Mount at /api/health
1245
+
1246
+
return app;
1247
+
}
1248
+
```
1249
+
1250
+
**Step 6: Test the integration**
1251
+
1252
+
```bash
1253
+
pnpm --filter @atbb/appview test src/routes/__tests__/routing.test.ts
1254
+
```
1255
+
1256
+
Expected: PASS (routing tests still pass)
1257
+
1258
+
**Step 7: Commit**
1259
+
1260
+
```bash
1261
+
git add apps/appview/src/routes/health.ts apps/appview/src/routes/__tests__/health.test.ts apps/appview/src/routes/index.ts
1262
+
git commit -m "feat(appview): add health endpoint with service status reporting
1263
+
1264
+
- Create GET /api/health endpoint (public, no auth required)
1265
+
- Report status: healthy, degraded, unhealthy
1266
+
- Include database, firehose, and forumAgent status
1267
+
- Expose granular ForumAgent states (authenticated, retrying, failed, etc)
1268
+
- Include retry countdown when ForumAgent is retrying
1269
+
- Security: no sensitive data exposed (no DIDs, handles, credentials)
1270
+
- Add comprehensive tests for health endpoint"
1271
+
```
1272
+
1273
+
---
1274
+
1275
+
## Task 7: Update Test Context for ForumAgent
1276
+
1277
+
**Files:**
1278
+
- Modify: `apps/appview/src/lib/__tests__/test-context.ts`
1279
+
1280
+
**Step 1: Add ForumAgent mock to test context**
1281
+
1282
+
In `apps/appview/src/lib/__tests__/test-context.ts`, add ForumAgent import and mock:
1283
+
1284
+
```typescript
1285
+
import type { ForumAgent } from "../forum-agent.js";
1286
+
1287
+
export interface TestContext {
1288
+
config: AppConfig;
1289
+
db: Database;
1290
+
firehose: FirehoseService;
1291
+
oauthClient: NodeOAuthClient;
1292
+
oauthStateStore: OAuthStateStore;
1293
+
oauthSessionStore: OAuthSessionStore;
1294
+
cookieSessionStore: CookieSessionStore;
1295
+
forumAgent: ForumAgent | null; // ← NEW
1296
+
cleanup: () => Promise<void>;
1297
+
}
1298
+
1299
+
export async function createTestContext(): Promise<TestContext> {
1300
+
// ... existing setup ...
1301
+
1302
+
// Mock ForumAgent (null by default for tests)
1303
+
const forumAgent = null;
1304
+
1305
+
return {
1306
+
config,
1307
+
db,
1308
+
firehose,
1309
+
oauthClient,
1310
+
oauthStateStore,
1311
+
oauthSessionStore,
1312
+
cookieSessionStore,
1313
+
forumAgent, // ← NEW
1314
+
cleanup: async () => {
1315
+
// Cleanup logic
1316
+
},
1317
+
};
1318
+
}
1319
+
```
1320
+
1321
+
**Step 2: Run all tests to verify nothing broke**
1322
+
1323
+
```bash
1324
+
pnpm --filter @atbb/appview test
1325
+
```
1326
+
1327
+
Expected: PASS (all tests passing)
1328
+
1329
+
**Step 3: Commit**
1330
+
1331
+
```bash
1332
+
git add apps/appview/src/lib/__tests__/test-context.ts
1333
+
git commit -m "test(appview): add ForumAgent to test context
1334
+
1335
+
- Add forumAgent: null to TestContext interface
1336
+
- Ensures route tests have proper context shape
1337
+
- Mock ForumAgent is null by default (can be overridden in tests)"
1338
+
```
1339
+
1340
+
---
1341
+
1342
+
## Task 8: Manual Integration Testing
1343
+
1344
+
**Files:**
1345
+
- None (manual testing)
1346
+
1347
+
**Step 1: Build the project**
1348
+
1349
+
```bash
1350
+
pnpm build
1351
+
```
1352
+
1353
+
Expected: Successful build with no errors
1354
+
1355
+
**Step 2: Start the development server**
1356
+
1357
+
In one terminal:
1358
+
1359
+
```bash
1360
+
pnpm --filter @atbb/appview dev
1361
+
```
1362
+
1363
+
Expected: Server starts on port 3000
1364
+
1365
+
**Step 3: Test health endpoint**
1366
+
1367
+
In another terminal:
1368
+
1369
+
```bash
1370
+
curl http://localhost:3000/api/health | jq
1371
+
```
1372
+
1373
+
Expected response:
1374
+
1375
+
```json
1376
+
{
1377
+
"status": "degraded",
1378
+
"timestamp": "2026-02-13T...",
1379
+
"services": {
1380
+
"database": {
1381
+
"status": "up",
1382
+
"latency_ms": 5
1383
+
},
1384
+
"firehose": {
1385
+
"status": "up",
1386
+
"connected": true,
1387
+
"last_event_at": "2026-02-13T..."
1388
+
},
1389
+
"forumAgent": {
1390
+
"status": "unavailable",
1391
+
"authenticated": false
1392
+
}
1393
+
}
1394
+
}
1395
+
```
1396
+
1397
+
**Step 4: Test with forum credentials**
1398
+
1399
+
Set environment variables in `.env`:
1400
+
1401
+
```
1402
+
FORUM_HANDLE=your-handle.bsky.social
1403
+
FORUM_PASSWORD=your-app-password
1404
+
```
1405
+
1406
+
Restart server and check health:
1407
+
1408
+
```bash
1409
+
curl http://localhost:3000/api/health | jq .services.forumAgent
1410
+
```
1411
+
1412
+
Expected (if credentials are valid):
1413
+
1414
+
```json
1415
+
{
1416
+
"status": "authenticated",
1417
+
"authenticated": true,
1418
+
"last_auth_attempt": "2026-02-13T..."
1419
+
}
1420
+
```
1421
+
1422
+
**Step 5: Document manual test results**
1423
+
1424
+
Create a comment in the PR or Linear issue documenting:
1425
+
- Health endpoint returns correct status
1426
+
- ForumAgent authenticates successfully with valid credentials
1427
+
- ForumAgent shows "unavailable" when credentials missing
1428
+
- No sensitive data exposed in health endpoint
1429
+
1430
+
**No commit needed** (manual testing only)
1431
+
1432
+
---
1433
+
1434
+
## Task 9: Update Documentation
1435
+
1436
+
**Files:**
1437
+
- Modify: `docs/plans/2026-02-13-atb-18-forum-agent-design.md`
1438
+
- Create: `apps/appview/README.md` (if doesn't exist) or update existing
1439
+
1440
+
**Step 1: Mark design document as implemented**
1441
+
1442
+
In `docs/plans/2026-02-13-atb-18-forum-agent-design.md`, update acceptance criteria:
1443
+
1444
+
```markdown
1445
+
## Acceptance Criteria
1446
+
1447
+
- [x] Design validated with stakeholder
1448
+
- [x] `ForumAgent` service authenticates as Forum DID on AppView startup
1449
+
- [x] Available via `ctx.forumAgent` in AppContext
1450
+
- [x] Auto-refreshes expired sessions proactively
1451
+
- [x] Graceful degradation if auth fails (server starts, write ops return 503)
1452
+
- [x] Smart retry logic: network errors retry with backoff, auth errors fail permanently
1453
+
- [x] Health endpoint exposes ForumAgent status with granular states
1454
+
- [x] Unit tests with mocked PDS
1455
+
- [x] Integration tests verifying agent is wired into AppContext
1456
+
- [x] Health endpoint tests verify no sensitive data exposure
1457
+
```
1458
+
1459
+
**Step 2: Add usage documentation**
1460
+
1461
+
Add a section to the design doc:
1462
+
1463
+
```markdown
1464
+
## Usage
1465
+
1466
+
### Checking ForumAgent Availability in Routes
1467
+
1468
+
```typescript
1469
+
export function createModActionRoutes(ctx: AppContext) {
1470
+
return new Hono().post("/", async (c) => {
1471
+
// Check if ForumAgent is available
1472
+
if (!ctx.forumAgent?.isAuthenticated()) {
1473
+
return c.json(
1474
+
{ error: "Forum write operations temporarily unavailable" },
1475
+
503
1476
+
);
1477
+
}
1478
+
1479
+
const agent = ctx.forumAgent.getAgent()!;
1480
+
// Use agent to write records to Forum PDS...
1481
+
});
1482
+
}
1483
+
```
1484
+
1485
+
### Monitoring Health
1486
+
1487
+
```bash
1488
+
# Check overall health
1489
+
curl http://localhost:3000/api/health
1490
+
1491
+
# Check ForumAgent status specifically
1492
+
curl http://localhost:3000/api/health | jq .services.forumAgent
1493
+
```
1494
+
1495
+
### Environment Variables
1496
+
1497
+
```
1498
+
FORUM_HANDLE=forum.example.com
1499
+
FORUM_PASSWORD=app-password-here
1500
+
```
1501
+
```
1502
+
1503
+
**Step 3: Commit documentation updates**
1504
+
1505
+
```bash
1506
+
git add docs/plans/2026-02-13-atb-18-forum-agent-design.md
1507
+
git commit -m "docs: mark ATB-18 implementation complete and add usage guide
1508
+
1509
+
- Update acceptance criteria to show all items complete
1510
+
- Add usage examples for checking ForumAgent availability in routes
1511
+
- Add monitoring examples for health endpoint
1512
+
- Document required environment variables"
1513
+
```
1514
+
1515
+
---
1516
+
1517
+
## Task 10: Update Linear Issue and Project Plan
1518
+
1519
+
**Files:**
1520
+
- None (external updates)
1521
+
1522
+
**Step 1: Update Linear issue ATB-18**
1523
+
1524
+
1. Go to https://linear.app/atbb/issue/ATB-18
1525
+
2. Change status to "Done"
1526
+
3. Add comment:
1527
+
1528
+
```
1529
+
Implementation complete ✅
1530
+
1531
+
All acceptance criteria met:
1532
+
- ForumAgent service authenticates on startup with smart retry logic
1533
+
- Integrated into AppContext (ctx.forumAgent)
1534
+
- Proactive session refresh every 30 minutes
1535
+
- Graceful degradation (server starts even if auth fails)
1536
+
- Error classification: auth errors fail permanently, network errors retry with backoff
1537
+
- Health endpoint at /api/health with granular status states
1538
+
- Comprehensive test coverage (unit + integration)
1539
+
- No sensitive data exposed in health endpoint
1540
+
1541
+
Files changed:
1542
+
- apps/appview/src/lib/forum-agent.ts (new)
1543
+
- apps/appview/src/lib/config.ts (forum credentials)
1544
+
- apps/appview/src/lib/app-context.ts (integration)
1545
+
- apps/appview/src/routes/health.ts (new endpoint)
1546
+
- Full test coverage in __tests__ directories
1547
+
1548
+
Ready for code review.
1549
+
```
1550
+
1551
+
**Step 2: Update project plan**
1552
+
1553
+
In `docs/atproto-forum-plan.md`, find ATB-18 and mark complete:
1554
+
1555
+
```markdown
1556
+
- [x] **ATB-18:** Forum DID authenticated agent for server-side PDS writes
1557
+
- Status: Complete (2026-02-13)
1558
+
- Implementation: apps/appview/src/lib/forum-agent.ts
1559
+
- Includes smart retry, session refresh, health reporting
1560
+
```
1561
+
1562
+
**Step 3: Commit plan update**
1563
+
1564
+
```bash
1565
+
git add docs/atproto-forum-plan.md
1566
+
git commit -m "docs: mark ATB-18 complete in project plan
1567
+
1568
+
ForumAgent service implemented with:
1569
+
- Graceful degradation and smart retry logic
1570
+
- Proactive session refresh
1571
+
- Health endpoint integration
1572
+
- Comprehensive test coverage"
1573
+
```
1574
+
1575
+
---
1576
+
1577
+
## Completion
1578
+
1579
+
**All tasks complete!**
1580
+
1581
+
Run final verification:
1582
+
1583
+
```bash
1584
+
# Run all tests
1585
+
pnpm test
1586
+
1587
+
# Run typecheck
1588
+
pnpm turbo lint
1589
+
1590
+
# Build project
1591
+
pnpm build
1592
+
```
1593
+
1594
+
Expected: All passing ✅
1595
+
1596
+
**Ready for code review!**
1597
+
1598
+
Use @superpowers:requesting-code-review to trigger PR review process.