BitSquare/Codeman
2
0
Fork 0
mirror of https://github.com/Ark0N/Codeman.git synced 2026-10-09 08:59:40 +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/routes/session-routes.test.ts
+77 -21
View File
@@ -3,10 +3,22 @@
*
* Uses app.inject() (Fastify's built-in test helper) — no real HTTP ports needed.
* Port: N/A (app.inject doesn't open ports)
*
* These tests assert the UNIFORM response envelope (stable HTTP contract):
* success -> 2xx, { success: true, data: <payload> }
* error -> 4xx/5xx, { success: false, error, errorCode }
* The production server applies this via a preSerialization hook (server.ts).
* The shared route harness doesn't install it, so we build a local harness here
* that mirrors production: the same preSerialization envelope hook + the shared
* route error handler, so assertions match the real wire format.
*/
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
import Fastify, { type FastifyInstance } from 'fastify';
import fastifyCookie from '@fastify/cookie';
import { createMockRouteContext, type MockRouteContext } from '../mocks/index.js';
import { installRouteErrorHandler } from '../../src/web/route-error-handler.js';
import { ApiErrorCode, httpStatusForErrorCode } from '../../src/types.js';
// Mock execFile so the send-key route's `tmux` invocation is observable (not run for real).
const { execFile } = vi.hoisted(() => ({ execFile: vi.fn() }));
@@ -17,11 +29,55 @@ vi.mock('node:child_process', async (orig) => {
import { registerSessionRoutes } from '../../src/web/routes/session-routes.js';
interface LocalHarness {
app: FastifyInstance;
ctx: MockRouteContext;
}
/**
* Build a Fastify instance that mirrors production's uniform-envelope behavior
* (server.ts preSerialization hook) so the test wire format matches the contract:
* bare payloads become { success: true, data }, and { success:false } error
* envelopes get the conventional HTTP status from their errorCode.
*/
async function createEnvelopeHarness(
registerFn: (app: FastifyInstance, ctx: MockRouteContext) => void
): Promise<LocalHarness> {
const app = Fastify({ logger: false });
await app.register(fastifyCookie);
const ctx = createMockRouteContext();
registerFn(app, ctx);
// Mirror production uniform response envelope (server.ts).
app.addHook('preSerialization', (req, reply, payload: unknown, done) => {
if (!req.url.startsWith('/api')) return done(null, payload);
if (payload === null || typeof payload !== 'object') return done(null, payload);
if (Buffer.isBuffer(payload) || typeof (payload as { pipe?: unknown }).pipe === 'function') {
return done(null, payload);
}
const p = payload as { success?: unknown; errorCode?: unknown };
if (p.success === false) {
if (reply.statusCode === 200 && typeof p.errorCode === 'string') {
reply.code(httpStatusForErrorCode(p.errorCode as ApiErrorCode));
}
return done(null, payload);
}
if (p.success === true) return done(null, payload);
return done(null, { success: true, data: payload });
});
installRouteErrorHandler(app);
await app.ready();
return { app, ctx };
}
describe('session-routes', () => {
let harness: RouteTestHarness;
let harness: LocalHarness;
beforeEach(async () => {
harness = await createRouteTestHarness(registerSessionRoutes);
harness = await createEnvelopeHarness(registerSessionRoutes);
});
afterEach(async () => {
@@ -73,15 +129,15 @@ describe('session-routes', () => {
const res = await harness.app.inject({ method: 'GET', url: '/api/sessions' });
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(Array.isArray(body)).toBe(true);
expect(body).toHaveLength(1);
expect(Array.isArray(body.data)).toBe(true);
expect(body.data).toHaveLength(1);
});
it('returns empty array when no sessions', async () => {
harness.ctx.sessions.clear();
const res = await harness.app.inject({ method: 'GET', url: '/api/sessions' });
expect(res.statusCode).toBe(200);
expect(JSON.parse(res.body)).toEqual([]);
expect(JSON.parse(res.body).data).toEqual([]);
});
});
@@ -95,7 +151,7 @@ describe('session-routes', () => {
});
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body.id).toBe(harness.ctx._sessionId);
expect(body.data.id).toBe(harness.ctx._sessionId);
});
it('returns error for unknown session', async () => {
@@ -129,7 +185,7 @@ describe('session-routes', () => {
method: 'DELETE',
url: '/api/sessions/nonexistent',
});
expect(res.statusCode).toBe(200);
expect(res.statusCode).toBe(404);
const body = JSON.parse(res.body);
expect(body.success).toBe(false);
});
@@ -163,7 +219,7 @@ describe('session-routes', () => {
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body.success).toBe(true);
expect(body.name).toBe('new-name');
expect(body.data.name).toBe('new-name');
expect(harness.ctx.persistSessionState).toHaveBeenCalled();
expect(harness.ctx.broadcast).toHaveBeenCalledWith('session:updated', expect.anything());
});
@@ -192,7 +248,7 @@ describe('session-routes', () => {
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body.success).toBe(true);
expect(body.color).toBe('blue');
expect(body.data.color).toBe('blue');
});
it('rejects invalid color', async () => {
@@ -201,7 +257,7 @@ describe('session-routes', () => {
url: `/api/sessions/${harness.ctx._sessionId}/color`,
payload: { color: 'neon-rainbow' },
});
expect(res.statusCode).toBe(200);
expect(res.statusCode).toBe(400);
const body = JSON.parse(res.body);
expect(body.success).toBe(false);
});
@@ -304,7 +360,7 @@ describe('session-routes', () => {
});
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body.terminalBuffer).toBeDefined();
expect(body.data.terminalBuffer).toBeDefined();
});
it('returns error for unknown session', async () => {
@@ -361,7 +417,7 @@ describe('session-routes', () => {
url: `/api/sessions/${harness.ctx._sessionId}/run`,
payload: { prompt: 'test' },
});
expect(res.statusCode).toBe(200);
expect(res.statusCode).toBe(409);
const body = JSON.parse(res.body);
expect(body.success).toBe(false);
});
@@ -397,7 +453,7 @@ describe('session-routes', () => {
method: 'POST',
url: `/api/sessions/${harness.ctx._sessionId}/interactive`,
});
expect(res.statusCode).toBe(200);
expect(res.statusCode).toBe(409);
const body = JSON.parse(res.body);
expect(body.success).toBe(false);
});
@@ -423,7 +479,7 @@ describe('session-routes', () => {
method: 'POST',
url: `/api/sessions/${harness.ctx._sessionId}/shell`,
});
expect(res.statusCode).toBe(200);
expect(res.statusCode).toBe(409);
const body = JSON.parse(res.body);
expect(body.success).toBe(false);
});
@@ -512,8 +568,8 @@ describe('session-routes', () => {
});
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body).toHaveProperty('sessions');
expect(Array.isArray(body.sessions)).toBe(true);
expect(body.data).toHaveProperty('sessions');
expect(Array.isArray(body.data.sessions)).toBe(true);
});
it('sessions have required fields', async () => {
@@ -522,7 +578,7 @@ describe('session-routes', () => {
url: '/api/history/sessions',
});
const body = JSON.parse(res.body);
for (const session of body.sessions) {
for (const session of body.data.sessions) {
expect(session).toHaveProperty('sessionId');
expect(session).toHaveProperty('workingDir');
expect(session).toHaveProperty('projectKey');
@@ -539,7 +595,7 @@ describe('session-routes', () => {
url: '/api/history/sessions',
});
const body = JSON.parse(res.body);
const dates = body.sessions.map((s: { lastModified: string }) => new Date(s.lastModified).getTime());
const dates = body.data.sessions.map((s: { lastModified: string }) => new Date(s.lastModified).getTime());
for (let i = 1; i < dates.length; i++) {
expect(dates[i - 1]).toBeGreaterThanOrEqual(dates[i]);
}
@@ -551,7 +607,7 @@ describe('session-routes', () => {
url: '/api/history/sessions',
});
const body = JSON.parse(res.body);
expect(body.sessions.length).toBeLessThanOrEqual(50);
expect(body.data.sessions.length).toBeLessThanOrEqual(50);
});
});
@@ -572,7 +628,7 @@ describe('session-routes', () => {
expect(res.statusCode).toBe(200);
const body = JSON.parse(res.body);
expect(body.success).toBe(true);
expect(body.session).toBeDefined();
expect(body.data.session).toBeDefined();
});
it('rejects invalid resumeSessionId format', async () => {