BitSquare/Codeman
2
0
Fork 0
mirror of https://github.com/Ark0N/Codeman.git synced 2026-10-06 23:49:41 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat(api): establish stable HTTP contract — uniform {success,data} envelope, status codes, /api/v1

Browse Source 
Point 1 of the v1.0 lock-in: commit to a stable HTTP API (the cleanest, fullest form).

Core (centralized):
- Every JSON /api response now uses ONE envelope via a Fastify preSerialization hook (src/web/server.ts): success -> { success:true, data:<payload> }; error -> { success:false, error, errorCode } with a conventional HTTP status. Non-JSON routes (file-raw, tail-file SSE, download, screenshots, /q redirect, WS) are skipped.
- Error-code -> HTTP status is a single source of truth (httpStatusForErrorCode in src/types/api.ts): 400/401/404/409/422/429/500. Expanded ApiErrorCode (added UNAUTHORIZED, CONFLICT, RATE_LIMITED). Errors are no longer HTTP 200.
- Versioned alias: /api/v1/* rewrites to /api/* (rewriteApiV1Url), so external clients pin to a stable surface while the bundled UI keeps using /api/*.
- Handlers stripped of manual 'success:true' (50 across 14 route files) so they return bare payloads the hook wraps uniformly; fixed the mux DELETE {success:<bool>} envelope collision (-> {killed}).

Frontend (48 call sites across 10 files):
- _apiJson() auto-unwraps { success:true, data } -> data (null on error), so most bare-shape readers are transparent. Raw-fetch sites relocate payload reads under .data; success/res.ok/error checks unchanged.

Docs: new docs/api-reference.md (envelope, status table, error codes, /api/v1, SSE); versioning-policy.md flipped — the HTTP/SSE API is now part of the stable, SemVer-covered surface.

Verification: full unit/route suite green (2680 passed) incl. ~166 updated assertions across 24 test files; typecheck/lint/format/frontend-syntax clean; a headless-chromium smoke loaded the migrated UI and drove the panels with 0 console/page errors; /api/status and /api/v1/status confirmed returning the uniform envelope live.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
arkon
2026-06-10 01:30:43 +02:00
co-authored by Claude Opus 4.8
parent 5b3024b327
commit 458fb81cbe
49 changed files with 929 additions and 554 deletions
Download Patch File Download Diff File Expand all files Collapse all files
test/ralph-integration.test.ts
+87 -87
View File
@@ -61,7 +61,7 @@ describe('Ralph Integration Tests', () => {
const data = await res.json();
expect(res.status).toBe(200);
expect(Array.isArray(data)).toBe(true);
expect(Array.isArray(data.data)).toBe(true);
});
it('should create a new session via quick-start', async () => {
@@ -76,8 +76,8 @@ describe('Ralph Integration Tests', () => {
const data = await res.json();
expect(data.success).toBe(true);
expect(data.sessionId).toBeDefined();
createdSessions.push(data.sessionId);
expect(data.data.sessionId).toBeDefined();
createdSessions.push(data.data.sessionId);
});
it('should get session details by ID', async () => {
@@ -91,15 +91,15 @@ describe('Ralph Integration Tests', () => {
body: JSON.stringify({ caseName }),
});
const createData = await createRes.json();
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
// Get session details
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}`);
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}`);
const data = await res.json();
expect(res.status).toBe(200);
expect(data.id).toBe(createData.sessionId);
expect(data.workingDir).toContain(caseName);
expect(data.data.id).toBe(createData.data.sessionId);
expect(data.data.workingDir).toContain(caseName);
});
it('should return error for non-existent session', async () => {
@@ -122,7 +122,7 @@ describe('Ralph Integration Tests', () => {
body: JSON.stringify({ caseName }),
});
const createData = await createRes.json();
const sessionId = createData.sessionId;
const sessionId = createData.data.sessionId;
// Delete session
const deleteRes = await fetch(`${baseUrl}/api/sessions/${sessionId}`, {
@@ -152,13 +152,13 @@ describe('Ralph Integration Tests', () => {
const data = await res.json();
expect(data.success).toBe(true);
expect(data.sessionId).toBeDefined();
createdSessions.push(data.sessionId);
expect(data.data.sessionId).toBeDefined();
createdSessions.push(data.data.sessionId);
// Verify mode
const sessionRes = await fetch(`${baseUrl}/api/sessions/${data.sessionId}`);
const sessionRes = await fetch(`${baseUrl}/api/sessions/${data.data.sessionId}`);
const sessionData = await sessionRes.json();
expect(sessionData.mode).toBe('shell');
expect(sessionData.data.mode).toBe('shell');
});
});
@@ -175,9 +175,9 @@ describe('Ralph Integration Tests', () => {
body: JSON.stringify({ caseName }),
});
const createData = await createRes.json();
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-state`);
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-state`);
const data = await res.json();
expect(res.status).toBe(200);
@@ -206,7 +206,7 @@ describe('Ralph Integration Tests', () => {
const data = await res.json();
expect(res.status).toBe(200);
expect(Array.isArray(data)).toBe(true);
expect(Array.isArray(data.data)).toBe(true);
});
it('should create a new case', async () => {
@@ -244,7 +244,7 @@ describe('Ralph Integration Tests', () => {
});
const data = await res.json();
expect(res.status).toBe(200);
expect(res.status).toBe(409);
expect(data.success).toBe(false);
expect(data.error).toContain('already exists');
});
@@ -265,15 +265,15 @@ describe('Ralph Integration Tests', () => {
const data = await res.json();
expect(res.status).toBe(200);
expect(data.name).toBe(caseName);
expect(data.path).toContain(caseName);
expect(data.data.name).toBe(caseName);
expect(data.data.path).toContain(caseName);
});
it('should return error for non-existent case', async () => {
const res = await fetch(`${baseUrl}/api/cases/non-existent-case-12345`);
const data = await res.json();
expect(res.status).toBe(200);
expect(res.status).toBe(404);
expect(data.error).toBe('Case not found');
});
});
@@ -286,18 +286,18 @@ describe('Ralph Integration Tests', () => {
const data = await res.json();
expect(res.status).toBe(200);
expect(data.sessions).toBeDefined();
expect(data.scheduledRuns).toBeDefined();
expect(data.respawnStatus).toBeDefined();
expect(data.timestamp).toBeDefined();
expect(data.data.sessions).toBeDefined();
expect(data.data.scheduledRuns).toBeDefined();
expect(data.data.respawnStatus).toBeDefined();
expect(data.data.timestamp).toBeDefined();
});
it('should include sessions array in status', async () => {
const res = await fetch(`${baseUrl}/api/status`);
const data = await res.json();
expect(Array.isArray(data.sessions)).toBe(true);
expect(typeof data.timestamp).toBe('number');
expect(Array.isArray(data.data.sessions)).toBe(true);
expect(typeof data.data.timestamp).toBe('number');
});
});
@@ -309,9 +309,9 @@ describe('Ralph Integration Tests', () => {
const data = await res.json();
expect(res.status).toBe(200);
expect(data.sessions).toBeDefined();
expect(Array.isArray(data.sessions)).toBe(true);
expect(typeof data.muxAvailable).toBe('boolean');
expect(data.data.sessions).toBeDefined();
expect(Array.isArray(data.data.sessions)).toBe(true);
expect(typeof data.data.muxAvailable).toBe('boolean');
});
});
@@ -328,9 +328,9 @@ describe('Ralph Integration Tests', () => {
body: JSON.stringify({ caseName }),
});
const createData = await createRes.json();
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/input`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/input`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ input: 'test input' }),
@@ -351,9 +351,9 @@ describe('Ralph Integration Tests', () => {
body: JSON.stringify({ caseName }),
});
const createData = await createRes.json();
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/input`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/input`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ input: null }),
@@ -393,12 +393,12 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
// Wait for session to be ready
await new Promise((r) => setTimeout(r, 200));
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/resize`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/resize`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ cols: 120, rows: 40 }),
@@ -420,12 +420,12 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
// Wait for session to be ready
await new Promise((r) => setTimeout(r, 200));
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/resize`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/resize`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ cols: -1, rows: 40 }),
@@ -452,9 +452,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/auto-compact`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/auto-compact`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true, threshold: 100000 }),
@@ -489,9 +489,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/auto-compact`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/auto-compact`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true, threshold: -100 }),
@@ -516,9 +516,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/auto-clear`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/auto-clear`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true, threshold: 150000 }),
@@ -553,9 +553,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/auto-clear`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/auto-clear`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true, threshold: -50 }),
@@ -582,9 +582,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true }),
@@ -606,9 +606,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ reset: true }),
@@ -643,9 +643,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ reset: 'full' }),
@@ -667,9 +667,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true, completionPhrase: 'DONE' }),
@@ -680,7 +680,7 @@ describe('Ralph Integration Tests', () => {
expect(data.success).toBe(true);
// Verify the state was updated
const stateRes = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-state`);
const stateRes = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-state`);
const stateData = await stateRes.json();
expect(stateData.success).toBe(true);
@@ -698,9 +698,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ disableAutoEnable: true }),
@@ -726,9 +726,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-state`);
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-state`);
const data = await res.json();
expect(res.status).toBe(200);
@@ -750,17 +750,17 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
// Enable ralph tracking
await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true, completionPhrase: 'TASK_DONE' }),
});
// Check state
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-state`);
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-state`);
const data = await res.json();
expect(data.success).toBe(true);
@@ -779,17 +779,17 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
// Enable first
await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true }),
});
// Then reset
const resetRes = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
const resetRes = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ reset: true }),
@@ -799,7 +799,7 @@ describe('Ralph Integration Tests', () => {
expect(resetData.success).toBe(true);
// Check that todos are cleared
const stateRes = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-state`);
const stateRes = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-state`);
const stateData = await stateRes.json();
expect(stateData.success).toBe(true);
@@ -817,24 +817,24 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
// Enable tracking
await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true }),
});
// Soft reset (keep enabled)
await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ reset: true }),
});
// Check state
const stateRes = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-state`);
const stateRes = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-state`);
const stateData = await stateRes.json();
expect(stateData.success).toBe(true);
@@ -852,24 +852,24 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
// Enable tracking
await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ enabled: true }),
});
// Full reset
await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-config`, {
await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-config`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ reset: 'full' }),
});
// Check state
const stateRes = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/ralph-state`);
const stateRes = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/ralph-state`);
const stateData = await stateRes.json();
expect(stateData.success).toBe(true);
@@ -891,13 +891,13 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/respawn`);
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/respawn`);
const data = await res.json();
expect(res.status).toBe(200);
expect(data.enabled).toBe(false);
expect(data.data.enabled).toBe(false);
});
it('should return error for respawn start on non-existent session', async () => {
@@ -924,14 +924,14 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/respawn/stop`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/respawn/stop`, {
method: 'POST',
});
const data = await res.json();
expect(res.status).toBe(200);
expect(res.status).toBe(404);
expect(data.success).toBe(false);
expect(data.errorCode).toBe('NOT_FOUND');
});
@@ -947,9 +947,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/respawn/config`, {
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/respawn/config`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ idleTimeoutMs: 10000 }),
@@ -958,7 +958,7 @@ describe('Ralph Integration Tests', () => {
expect(res.status).toBe(200);
expect(data.success).toBe(true);
expect(data.config.idleTimeoutMs).toBe(10000);
expect(data.data.config.idleTimeoutMs).toBe(10000);
});
});
@@ -976,9 +976,9 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/output`);
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/output`);
const data = await res.json();
expect(res.status).toBe(200);
@@ -1008,14 +1008,14 @@ describe('Ralph Integration Tests', () => {
});
const createData = await createRes.json();
expect(createData.success).toBe(true);
createdSessions.push(createData.sessionId);
createdSessions.push(createData.data.sessionId);
const res = await fetch(`${baseUrl}/api/sessions/${createData.sessionId}/terminal`);
const res = await fetch(`${baseUrl}/api/sessions/${createData.data.sessionId}/terminal`);
const data = await res.json();
expect(res.status).toBe(200);
expect(data.terminalBuffer).toBeDefined();
expect(data.status).toBeDefined();
expect(data.data.terminalBuffer).toBeDefined();
expect(data.data.status).toBeDefined();
});
it('should return error for terminal of non-existent session', async () => {