Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(external-rest-api): proxy entity change streams
Josué2585f315efc1
diff --git a/external-rest-api/package-lock.json b/external-rest-api/package-lock.jsonindex e1e4e2674..81c281065 100644--- a/external-rest-api/package-lock.json+++ b/external-rest-api/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-external-rest-api",- "version": "0.1.84",+ "version": "0.1.85","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-external-rest-api",- "version": "0.1.84",+ "version": "0.1.85","dependencies": {"cors": "^2.8.5","express": "^4.21.2",diff --git a/external-rest-api/package.json b/external-rest-api/package.jsonindex fd127fe32..ce716823a 100644--- a/external-rest-api/package.json+++ b/external-rest-api/package.json@@ -1,6 +1,6 @@{"name": "clerum-external-rest-api",- "version": "0.1.84",+ "version": "0.1.85","description": "External REST API for profile, team management, and RPC token brokerage","main": "dist/main.js","engines": {diff --git a/external-rest-api/src/app.ts b/external-rest-api/src/app.tsindex c606c899a..43af58971 100644--- a/external-rest-api/src/app.ts+++ b/external-rest-api/src/app.ts@@ -6,6 +6,7 @@ import { createAuthRouter } from './routes/auth.js'import { createContextSharedFilesystemsRouter } from './routes/contextSharedFilesystems.js'import { createDesktopRouter } from './routes/desktop.js'import { createDirectoryRouter } from './routes/directory.js'+import { createEntityChangesRouter } from './routes/entityChanges.js'import { createGfsRouter } from './routes/gfs.js'import { createHealthRouter } from './routes/health.js'import { createInvitationsRouter } from './routes/invitations.js'@@ -71,6 +72,7 @@ export function createApp() {api.use(createDirectoryRouter())api.use(createRpcRouter())api.use(createNotificationsRouter())+ api.use(createEntityChangesRouter())api.use(createUserApprovalDecisionsRouter())api.use(createOauthGrantsRouter())// PUBLIC (no auth) — provider redirect target; passthrough to control-api.diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.tsindex f70725a95..9aa61a7a8 100644--- a/external-rest-api/src/releaseManifest.ts+++ b/external-rest-api/src/releaseManifest.ts@@ -8,7 +8,7 @@ export type ReleaseManifest = {export const releaseManifest: ReleaseManifest = {releaseId: 'v0.9.0',- externalRestApiVersion: '0.1.84',+ externalRestApiVersion: '0.1.85',rpcProxyVersion: '0.1.89',desktopVersion: '0.9.0',minimumDesktopVersion: '0.1.252',diff --git a/external-rest-api/src/routes/entityChanges.ts b/external-rest-api/src/routes/entityChanges.tsnew file mode 100644index 000000000..1dc4a2316--- /dev/null+++ b/external-rest-api/src/routes/entityChanges.ts@@ -0,0 +1,71 @@+import { type NextFunction, type Response, Router } from 'express'+import { Readable } from 'node:stream'+import { pipeline } from 'node:stream/promises'+import { ControlApiError, controlApiStreamRequest } from '../controlApiClient.js'+import { type AuthedRequest, extractAuthToken, requireAuth } from '../middleware/auth.js'++function forwardError(error: unknown, res: Response, next: NextFunction): void {+ if (error instanceof ControlApiError && error.status >= 400 && error.status <= 599) {+ const body =+ error.status < 500 && error.body && typeof error.body === 'object'+ ? error.body+ : { error: 'Entity change stream unavailable' }+ for (const [name, value] of Object.entries(error.headers)) res.setHeader(name, value)+ res.status(error.status).json(body)+ return+ }+ next(error)+}++export function createEntityChangesRouter(): Router {+ const router = Router()+ router.get('/entity-changes/stream', requireAuth, async (req: AuthedRequest, res, next) => {+ const abortController = new AbortController()+ const abort = () => abortController.abort()+ req.on('aborted', abort)+ const abortIfPremature = () => {+ if (!res.writableEnded) abort()+ }+ res.on('close', abortIfPremature)+ try {+ const cursor = String(req.query?.cursor || '').trim()+ const upstream = await controlApiStreamRequest('GET', '/external/entity-changes/stream', {+ query: cursor ? { cursor } : undefined,+ userSessionToken: extractAuthToken(req),+ signal: abortController.signal,+ })+ if (!upstream.body) {+ res.status(502).json({ error: 'Entity change stream unavailable' })+ return+ }+ res.status(upstream.status)+ res.setHeader(+ 'content-type',+ upstream.headers.get('content-type') || 'application/x-ndjson; charset=utf-8'+ )+ res.setHeader(+ 'cache-control',+ upstream.headers.get('cache-control') || 'no-cache, no-transform'+ )+ res.setHeader('connection', 'keep-alive')+ res.setHeader('x-accel-buffering', 'no')+ const requestId = upstream.headers.get('x-request-id')+ if (requestId) res.setHeader('x-request-id', requestId)+ res.flushHeaders?.()+ await pipeline(+ Readable.fromWeb(+ upstream.body as unknown as import('node:stream/web').ReadableStream<Uint8Array>+ ),+ res,+ { signal: abortController.signal }+ )+ } catch (error) {+ if (abortController.signal.aborted || res.destroyed) return+ forwardError(error, res, next)+ } finally {+ req.off('aborted', abort)+ res.off('close', abortIfPremature)+ }+ })+ return router+}diff --git a/external-rest-api/test/routes.entityChanges.test.ts b/external-rest-api/test/routes.entityChanges.test.tsnew file mode 100644index 000000000..d6aafd62f--- /dev/null+++ b/external-rest-api/test/routes.entityChanges.test.ts@@ -0,0 +1,176 @@+import { beforeEach, describe, expect, it, vi } from 'vitest'+import express from 'express'+import { get as httpGet } from 'node:http'+import request from 'supertest'+import { createEntityChangesRouter } from '../src/routes/entityChanges.js'++const authTokenMock = vi.hoisted(() => ({ verifyToken: vi.fn() }))+const controlApiClientMock = vi.hoisted(() => ({+ controlApiStreamRequest: vi.fn(),+ ControlApiError: class ControlApiError extends Error {+ status: number+ body: unknown+ headers: Record<string, string>+ constructor(message: string, status: number, body: unknown, headers = {}) {+ super(message)+ this.status = status+ this.body = body+ this.headers = headers+ }+ },+}))++vi.mock('../src/authToken.js', () => authTokenMock)+vi.mock('../src/controlApiClient.js', () => controlApiClientMock)++function makeNdjsonStream(line: string): ReadableStream<Uint8Array> {+ const encoder = new TextEncoder()+ return new ReadableStream<Uint8Array>({+ start(controller) {+ controller.enqueue(encoder.encode(`${line}\n`))+ controller.close()+ },+ })+}++describe('routes/entityChanges', () => {+ const claims = {+ userId: 'user-1',+ email: '[email protected]',+ teamId: 'team-1',+ role: 'member' as const,+ exp: 9_999_999_999,+ }++ beforeEach(() => {+ authTokenMock.verifyToken.mockReset()+ controlApiClientMock.controlApiStreamRequest.mockReset()+ })++ function makeApp() {+ const app = express()+ app.use(createEntityChangesRouter())+ return app+ }++ it('requires an authenticated Desktop session before opening the stream', async () => {+ await request(makeApp()).get('/entity-changes/stream').expect(401)+ expect(controlApiClientMock.controlApiStreamRequest).not.toHaveBeenCalled()+ })++ it('passes the authenticated stream through as NDJSON without buffering into JSON', async () => {+ authTokenMock.verifyToken.mockReturnValueOnce(claims)+ const frame = JSON.stringify({+ schemaVersion: 1,+ type: 'scope.invalidated',+ cursor: 'd119f895-1ef8-4e73-8f08-f9754919682a',+ scopes: ['gfs'],+ })+ controlApiClientMock.controlApiStreamRequest.mockResolvedValueOnce({+ status: 200,+ headers: new Headers({+ 'content-type': 'application/x-ndjson; charset=utf-8',+ 'cache-control': 'no-cache, no-transform',+ }),+ body: makeNdjsonStream(frame),+ })++ const response = await request(makeApp())+ .get('/entity-changes/stream?cursor=d119f895-1ef8-4e73-8f08-f9754919682a')+ .set('authorization', 'Bearer session-token')+ .expect(200)++ expect(response.text.trim()).toBe(frame)+ expect(response.headers['content-type']).toContain('application/x-ndjson')+ expect(response.headers['x-accel-buffering']).toBe('no')+ expect(controlApiClientMock.controlApiStreamRequest).toHaveBeenCalledWith(+ 'GET',+ '/external/entity-changes/stream',+ expect.objectContaining({+ query: { cursor: 'd119f895-1ef8-4e73-8f08-f9754919682a' },+ userSessionToken: 'session-token',+ signal: expect.any(AbortSignal),+ })+ )+ })++ it('propagates authorization and cursor errors from control-api', async () => {+ authTokenMock.verifyToken.mockReturnValueOnce(claims)+ const error = new controlApiClientMock.ControlApiError(+ 'expired cursor',+ 410,+ { error: 'resync_required' },+ { 'retry-after': '1' }+ )+ controlApiClientMock.controlApiStreamRequest.mockRejectedValueOnce(error)+ const app = makeApp()+ app.use(+ (err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {+ const status = (err as { status?: number }).status ?? 500+ res.status(status).json({ error: 'unexpected' })+ }+ )++ const response = await request(app)+ .get('/entity-changes/stream?cursor=d119f895-1ef8-4e73-8f08-f9754919682a')+ .set('authorization', 'Bearer session-token')+ .expect(410)+ expect(response.body).toEqual({ error: 'resync_required' })+ expect(response.headers['retry-after']).toBe('1')+ })++ it('preserves upstream server error status without exposing internal response details', async () => {+ authTokenMock.verifyToken.mockReturnValueOnce(claims)+ controlApiClientMock.controlApiStreamRequest.mockRejectedValueOnce(+ new controlApiClientMock.ControlApiError(+ 'database password must not escape',+ 503,+ { error: 'database password must not escape' },+ { 'retry-after': '2' }+ )+ )+ const response = await request(makeApp())+ .get('/entity-changes/stream')+ .set('authorization', 'Bearer session-token')+ .expect(503)+ expect(response.body).toEqual({ error: 'Entity change stream unavailable' })+ expect(response.text).not.toContain('database password')+ expect(response.headers['retry-after']).toBe('2')+ })++ it('cancels the upstream request when the authenticated client disconnects', async () => {+ authTokenMock.verifyToken.mockReturnValueOnce(claims)+ let upstreamSignal: AbortSignal | undefined+ controlApiClientMock.controlApiStreamRequest.mockImplementationOnce(+ (_method: string, _path: string, options: { signal: AbortSignal }) =>+ new Promise((_resolve, reject) => {+ upstreamSignal = options.signal+ options.signal.addEventListener('abort', () => reject(new Error('aborted')), {+ once: true,+ })+ })+ )+ const server = makeApp().listen(0, '127.0.0.1')+ await new Promise<void>(resolve => server.once('listening', () => resolve()))+ const address = server.address()+ if (!address || typeof address === 'string') throw new Error('test server did not bind TCP')+ const client = httpGet(+ {+ hostname: '127.0.0.1',+ port: address.port,+ path: '/entity-changes/stream',+ headers: { authorization: 'Bearer session-token' },+ },+ response => response.resume()+ )+ client.on('error', () => undefined)+ try {+ await vi.waitFor(() => expect(upstreamSignal).toBeDefined())+ client.destroy()+ await vi.waitFor(() => expect(upstreamSignal?.aborted).toBe(true))+ } finally {+ client.destroy()+ await new Promise<void>(resolve => server.close(() => resolve()))+ }+ })+})