feat(dify-builder): add non-reactive trace ring buffer

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Charles YaoandClaude Opus 4.8 committed 2026-09-04 02:50:17 -07:00
1 parent 31a972e961
commit aa4e49df23
2 files changed
+120

No files matched your search

@@ -0,0 +1,57 @@
import { createTraceBuffer, readTraceState, readTraceVersion } from '../trace-buffer'
describe('createTraceBuffer', () => {
it('stamps a monotonic seq (starting at 1) and an ISO timestamp on each append', () => {
const buffer = createTraceBuffer()
buffer.append({ dir: 'out', kind: 'action', payload: { a: 1 } })
buffer.append({ dir: 'in', kind: 'progress', payload: { b: 2 }, version: 3, state: 'build.execution' })
const { entries, truncated } = buffer.snapshot()
expect(entries.map((e) => e.seq)).toEqual([1, 2])
expect(entries[0].dir).toBe('out')
expect(entries[1]).toMatchObject({ dir: 'in', kind: 'progress', version: 3, state: 'build.execution' })
expect(entries[1].ts).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/)
expect(truncated).toBe(false)
})
it('keeps only the last `cap` entries and flags truncated on overflow', () => {
const buffer = createTraceBuffer(2)
buffer.append({ dir: 'in', kind: 'a', payload: {} })
buffer.append({ dir: 'in', kind: 'b', payload: {} })
buffer.append({ dir: 'in', kind: 'c', payload: {} })
const { entries, truncated } = buffer.snapshot()
expect(entries.map((e) => e.kind)).toEqual(['b', 'c'])
expect(entries.map((e) => e.seq)).toEqual([2, 3])
expect(truncated).toBe(true)
})
it('snapshot returns a copy that does not mutate the buffer', () => {
const buffer = createTraceBuffer()
buffer.append({ dir: 'in', kind: 'a', payload: {} })
const first = buffer.snapshot()
first.entries.push({ seq: 99, ts: 'x', dir: 'in', kind: 'z', payload: {} })
expect(buffer.snapshot().entries).toHaveLength(1)
})
it('clear resets entries, seq, and truncated', () => {
const buffer = createTraceBuffer(1)
buffer.append({ dir: 'in', kind: 'a', payload: {} })
buffer.append({ dir: 'in', kind: 'b', payload: {} })
buffer.clear()
expect(buffer.snapshot()).toEqual({ entries: [], truncated: false })
buffer.append({ dir: 'in', kind: 'c', payload: {} })
expect(buffer.snapshot().entries[0].seq).toBe(1)
})
it('readTraceVersion prefers version, falls back to at_version, else undefined', () => {
expect(readTraceVersion({ version: 5, at_version: 4 })).toBe(5)
expect(readTraceVersion({ at_version: 4 })).toBe(4)
expect(readTraceVersion({})).toBeUndefined()
expect(readTraceVersion(null)).toBeUndefined()
})
it('readTraceState returns a string state or undefined', () => {
expect(readTraceState({ state: 'build.publish' })).toBe('build.publish')
expect(readTraceState({})).toBeUndefined()
expect(readTraceState('x')).toBeUndefined()
})
})
@@ -0,0 +1,63 @@
export type TraceDirection = 'in' | 'out'
export type TraceEntry = {
seq: number
ts: string
dir: TraceDirection
kind: string
payload: unknown
version?: number
state?: string
}
export type TraceInput = Omit<TraceEntry, 'seq' | 'ts'>
export type TraceSnapshot = {
entries: TraceEntry[]
truncated: boolean
}
export type TraceBuffer = {
append: (input: TraceInput) => void
snapshot: () => TraceSnapshot
clear: () => void
}
export const TRACE_BUFFER_CAP = 2000
export const createTraceBuffer = (cap: number = TRACE_BUFFER_CAP): TraceBuffer => {
let entries: TraceEntry[] = []
let seq = 0
let truncated = false
return {
append(input) {
seq += 1
entries.push({ ...input, seq, ts: new Date().toISOString() })
if (entries.length > cap) {
entries.shift()
truncated = true
}
},
snapshot() {
return { entries: entries.slice(), truncated }
},
clear() {
entries = []
seq = 0
truncated = false
},
}
}
export const readTraceVersion = (data: unknown): number | undefined => {
if (typeof data !== 'object' || data === null) return undefined
const record = data as Record<string, unknown>
const value = record.version ?? record.at_version
return typeof value === 'number' ? value : undefined
}
export const readTraceState = (data: unknown): string | undefined => {
if (typeof data !== 'object' || data === null) return undefined
const value = (data as Record<string, unknown>).state
return typeof value === 'string' ? value : undefined
}