Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(entity-change): r7-l17 skip safe schema v1 extensions

Josué94d235f15808
diff --git a/control-ui/lib/__tests__/entityChangeStream.test.ts b/control-ui/lib/__tests__/entityChangeStream.test.ts
index 4ee1953bc..008cc330e 100644
--- a/control-ui/lib/__tests__/entityChangeStream.test.ts
+++ b/control-ui/lib/__tests__/entityChangeStream.test.ts
@@ -24,17 +24,40 @@ describe('parseEntityChangeFrame', () => {
})
})
- it('turns unknown versions and event types into a full safe resynchronization', () => {
+ it('skips unknown scopes, close reasons, and forward-compatible event types', () => {
expect(
+ parseEntityChangeFrame(
+ JSON.stringify({
+ schemaVersion: 1,
+ type: 'scope.invalidated',
+ cursor: CURSOR,
+ scopes: ['future-scope'],
+ })
+ )
+ ).toBeNull()
+ expect(
+ parseEntityChangeFrame(
+ JSON.stringify({
+ schemaVersion: 1,
+ type: 'stream.closing',
+ cursor: CURSOR,
+ reason: 'future-reason',
+ })
+ )
+ ).toBeNull()
+ expect(
+ parseEntityChangeFrame(
+ JSON.stringify({ schemaVersion: 1, type: 'future.event', cursor: CURSOR })
+ )
+ ).toBeNull()
+ })
+
+ it('rejects unsupported schemas instead of forcing a resync of visible state', () => {
+ expect(() =>
parseEntityChangeFrame(
JSON.stringify({ schemaVersion: 2, type: 'future.event', cursor: CURSOR })
)
- ).toEqual({
- schemaVersion: 1,
- type: 'resync_required',
- cursor: CURSOR,
- scopes: ['gfs', 'authorization'],
- })
+ ).toThrow('Unsupported entity-change schema version')
})
it('rejects malformed JSON and invalid cursors', () => {
diff --git a/control-ui/lib/entityChangeStream.ts b/control-ui/lib/entityChangeStream.ts
index 6ef39ca4c..b0593e35a 100644
--- a/control-ui/lib/entityChangeStream.ts
+++ b/control-ui/lib/entityChangeStream.ts
@@ -17,7 +17,7 @@ export function entityChangeStreamUrl(cursor?: string): string {
return controlApiUrl(`/api/v1/gfs/entity-changes/stream${query}`)
}
-/** Parse one NDJSON frame. Unknown versions/types fail safe into full invalidation. */
+/** Parse one NDJSON frame. Safe v1 extensions are skipped; unsupported schemas are rejected. */
export function parseEntityChangeFrame(line: string): EntityChangeFrame | null {
if (!line.trim()) return null
let value: unknown
@@ -32,39 +32,42 @@ export function parseEntityChangeFrame(line: string): EntityChangeFrame | null {
throw new Error('Invalid entity-change cursor')
}
if (frame.schemaVersion !== 1 || typeof frame.type !== 'string') {
+ throw new Error('Unsupported entity-change schema version')
+ }
+ if (frame.type === 'resync_required' || frame.type === 'scope.invalidated') {
+ if (!Array.isArray(frame.scopes) || frame.scopes.length === 0) {
+ throw new Error('Invalid entity-change scopes')
+ }
+ const scopes = frame.scopes.filter(
+ (scope): scope is 'gfs' | 'authorization' => scope === 'gfs' || scope === 'authorization'
+ )
+ if (scopes.length === 0) return null
return {
schemaVersion: 1,
- type: 'resync_required',
+ type: frame.type,
cursor: frame.cursor,
- scopes: ['gfs', 'authorization'],
+ scopes,
}
}
- if (
- frame.type === 'resync_required' ||
- frame.type === 'scope.invalidated' ||
- frame.type === 'heartbeat' ||
- frame.type === 'stream.closing'
- ) {
- const scopes = Array.isArray(frame.scopes)
- ? frame.scopes.filter(
- (scope): scope is 'gfs' | 'authorization' => scope === 'gfs' || scope === 'authorization'
- )
- : undefined
+ if (frame.type === 'heartbeat') {
+ if (typeof frame.observedAt !== 'string') throw new Error('Invalid entity-change heartbeat')
return {
schemaVersion: 1,
- type: frame.type,
+ type: 'heartbeat',
cursor: frame.cursor,
- ...(scopes ? { scopes } : {}),
- ...(typeof frame.observedAt === 'string' ? { observedAt: frame.observedAt } : {}),
- ...(typeof frame.reason === 'string'
- ? { reason: frame.reason as EntityChangeFrame['reason'] }
- : {}),
+ observedAt: frame.observedAt,
}
}
- return {
- schemaVersion: 1,
- type: 'resync_required',
- cursor: frame.cursor,
- scopes: ['gfs', 'authorization'],
+ if (frame.type === 'stream.closing') {
+ const reasons = ['max_lifetime', 'session_expired', 'server_shutdown', 'slow_consumer']
+ if (typeof frame.reason !== 'string' || !reasons.includes(frame.reason)) return null
+ return {
+ schemaVersion: 1,
+ type: 'stream.closing',
+ cursor: frame.cursor,
+ reason: frame.reason as EntityChangeFrame['reason'],
+ }
}
+ // Schema v1 extensions are defined to be safely ignorable by older clients.
+ return null
}
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 3f31465c3..493cd0aeb 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.679",
+ "version": "0.1.680",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.679",
+ "version": "0.1.680",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
diff --git a/control-ui/package.json b/control-ui/package.json
index b21a9f8a7..9e8d224fc 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.679",
+ "version": "0.1.680",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/desktop-app/src/__tests__/authClient.entityChanges.test.ts b/desktop-app/src/__tests__/authClient.entityChanges.test.ts
index 070ffd9bf..0c29d5eb5 100644
--- a/desktop-app/src/__tests__/authClient.entityChanges.test.ts
+++ b/desktop-app/src/__tests__/authClient.entityChanges.test.ts
@@ -20,14 +20,17 @@ function stream(lines: unknown[]): ReadableStream<Uint8Array> {
describe('AuthClient.openEntityChangeStream', () => {
beforeEach(() => vi.unstubAllGlobals())
- it('validates coarse feed frames and turns unknown versions into full resync', async () => {
+ it('skips forward-compatible frames without interrupting later supported events', async () => {
vi.stubGlobal(
'fetch',
vi.fn().mockResolvedValue({
ok: true,
body: stream([
{ schemaVersion: 1, type: 'scope.invalidated', cursor: CURSOR, scopes: ['gfs'] },
- { schemaVersion: 2, type: 'future.event', cursor: CURSOR, entityId: 'private-id' },
+ { schemaVersion: 1, type: 'scope.invalidated', cursor: CURSOR, scopes: ['future-scope'] },
+ { schemaVersion: 1, type: 'stream.closing', cursor: CURSOR, reason: 'future-reason' },
+ { schemaVersion: 1, type: 'future.event', cursor: CURSOR, entityId: 'private-id' },
+ { schemaVersion: 1, type: 'heartbeat', cursor: CURSOR, observedAt: 'now' },
]),
})
)
@@ -41,12 +44,7 @@ describe('AuthClient.openEntityChangeStream', () => {
expect(events).toEqual([
{ type: 'open' },
{ schemaVersion: 1, type: 'scope.invalidated', cursor: CURSOR, scopes: ['gfs'] },
- {
- schemaVersion: 1,
- type: 'resync_required',
- cursor: CURSOR,
- scopes: ['gfs', 'authorization'],
- },
+ { schemaVersion: 1, type: 'heartbeat', cursor: CURSOR, observedAt: 'now' },
])
expect(JSON.stringify(events)).not.toContain('private-id')
expect(fetch).toHaveBeenCalledWith(
@@ -57,6 +55,30 @@ describe('AuthClient.openEntityChangeStream', () => {
)
})
+ it('rejects an unsupported schema without converting it into a destructive resync', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn().mockResolvedValue({
+ ok: true,
+ body: stream([
+ { schemaVersion: 1, type: 'scope.invalidated', cursor: CURSOR, scopes: ['gfs'] },
+ { schemaVersion: 2, type: 'future.event', cursor: CURSOR, entityId: 'private-id' },
+ ]),
+ })
+ )
+ const events: Array<Record<string, unknown>> = []
+ await expect(
+ new AuthClient().openEntityChangeStream(
+ 'session-token',
+ null,
+ event => events.push(event as unknown as Record<string, unknown>),
+ new AbortController().signal
+ )
+ ).rejects.toThrow('unsupported schema version')
+ expect(events.map(event => event.type)).toEqual(['open', 'scope.invalidated'])
+ expect(JSON.stringify(events)).not.toContain('private-id')
+ })
+
it('rejects malformed cursors rather than exposing arbitrary stream payloads', async () => {
vi.stubGlobal(
'fetch',
@@ -74,6 +96,6 @@ describe('AuthClient.openEntityChangeStream', () => {
() => undefined,
new AbortController().signal
)
- ).rejects.toThrow('unsupported frame')
+ ).rejects.toThrow('invalid cursor')
})
})
diff --git a/desktop-app/src/authClient.ts b/desktop-app/src/authClient.ts
index e3c182ace..596e9c4f6 100644
--- a/desktop-app/src/authClient.ts
+++ b/desktop-app/src/authClient.ts
@@ -36,23 +36,17 @@ function isRecord(value: unknown): value is Record<string, unknown> {
}
function parseEntityChangeStreamFrame(value: unknown): EntityChangeStreamEvent | null {
- if (!isRecord(value)) return null
+ if (!isRecord(value)) throw new Error('Entity change stream contained a malformed frame')
const cursor = typeof value.cursor === 'string' ? value.cursor : ''
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(cursor)) {
- return null
+ throw new Error('Entity change stream contained an invalid cursor')
}
if (value.schemaVersion !== 1 || typeof value.type !== 'string') {
- return {
- type: 'resync_required',
- schemaVersion: 1,
- cursor,
- scopes: ['gfs', 'authorization'],
- }
+ throw new Error('Entity change stream contained an unsupported schema version')
}
if (value.type === 'resync_required' || value.type === 'scope.invalidated') {
- if (!Array.isArray(value.scopes) || value.scopes.length === 0) {
- return null
- }
+ if (!Array.isArray(value.scopes) || value.scopes.length === 0)
+ throw new Error('Entity change stream contained invalid scopes')
const scopes = value.scopes.filter(
(scope): scope is 'gfs' | 'authorization' => scope === 'gfs' || scope === 'authorization'
)
@@ -66,7 +60,7 @@ function parseEntityChangeStreamFrame(value: unknown): EntityChangeStreamEvent |
}
if (value.type === 'heartbeat') {
if (typeof value.observedAt !== 'string') {
- return null
+ throw new Error('Entity change stream contained an invalid heartbeat')
}
return {
type: 'heartbeat',
@@ -90,12 +84,8 @@ function parseEntityChangeStreamFrame(value: unknown): EntityChangeStreamEvent |
>['reason'],
}
}
- return {
- type: 'resync_required',
- schemaVersion: 1,
- cursor,
- scopes: ['gfs', 'authorization'],
- }
+ // Schema v1 extensions are defined to be safely ignorable by older clients.
+ return null
}
function parsePendingWorkflowApproval(value: unknown): PendingWorkflowApproval | null {
@@ -610,7 +600,7 @@ export class AuthClient {
throw new Error('Entity change stream contained invalid JSON')
}
const frame = parseEntityChangeStreamFrame(decoded)
- if (!frame) throw new Error('Entity change stream contained an unsupported frame')
+ if (!frame) return
onEvent(frame)
}
const processChunk = (chunk: string) => {