Skip to content

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.json
index 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.json
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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()))
+ }
+ })
+})