@bsv/overlay-express
Version:
BSV Blockchain Overlay Express
190 lines • 6.48 kB
JavaScript
/**
* Consumes the go-chaintracks (Arcade) reorg SSE stream (`GET /v2/reorg/stream`)
* and normalizes each `ReorgEvent` into the overlay engine's `handleReorg` input.
*
* The stream emits `data: <JSON>\n\n` frames (no `event:`/`id:` lines) with
* `: keepalive` comment frames in between. Because there are no event ids, a
* reconnect cannot replay events missed while disconnected — so every (re)connect
* triggers an `onConnect` catch-up (the engine's revalidation sweep).
*/
/**
* Parses a single SSE data frame (a go-chaintracks `ReorgEvent` JSON document)
* into `handleReorg` input. Returns `null` for malformed frames.
*
* `ReorgEvent` = { orphanedHashes: string[], commonAncestor: BlockHeader|null,
* newTip: BlockHeader, depth: number }. Block hashes are go-sdk `chainhash.Hash`
* values marshaled as reversed (display) hex; they are lower-cased here to match
* the overlay's stored block hashes.
*/
export function parseReorgEvent(frame) {
let event;
try {
event = JSON.parse(frame);
}
catch {
return null;
}
const newTipHeight = event?.newTip?.height;
if (typeof newTipHeight !== 'number') {
return null;
}
const orphanedBlockHashes = Array.isArray(event.orphanedHashes)
? event.orphanedHashes
.filter((hash) => typeof hash === 'string')
.map((hash) => hash.toLowerCase())
: [];
const ancestorHeight = event?.commonAncestor?.height;
const depth = event?.depth;
let rebuildFromHeight;
if (typeof ancestorHeight === 'number') {
rebuildFromHeight = ancestorHeight + 1;
}
else if (typeof depth === 'number') {
// No common ancestor (e.g. reorg deeper than retained history): fall back to
// the reported depth from the new tip.
rebuildFromHeight = Math.max(0, newTipHeight - depth + 1);
}
else {
return null;
}
return { orphanedBlockHashes, rebuildFromHeight, newTipHeight };
}
/**
* Splits an SSE byte buffer into complete event payloads. Frames are delimited by
* a blank line (`\n\n`); within a frame, `data:` lines are concatenated and
* comment lines (starting with `:`) are ignored. Any trailing partial frame is
* returned in `rest` for the next read.
*/
export function extractSseFrames(buffer) {
const events = [];
let working = buffer;
let boundary = working.indexOf('\n\n');
while (boundary !== -1) {
const block = working.slice(0, boundary);
working = working.slice(boundary + 2);
const dataLines = [];
for (const line of block.split('\n')) {
if (line.startsWith(':')) {
continue;
}
if (line.startsWith('data:')) {
dataLines.push(line.slice(5).replace(/^ /, ''));
}
}
if (dataLines.length > 0) {
events.push(dataLines.join(''));
}
boundary = working.indexOf('\n\n');
}
return { events, rest: working };
}
/**
* Long-lived SSE client that keeps the overlay's BASM anchors reconciled with
* chain reorgs. Auto-reconnects with a fixed delay and runs a catch-up on connect.
*/
export class ReorgSseAdapter {
url;
onReorg;
onConnect;
logger;
reconnectDelayMs;
fetchImpl;
controller;
stopped = false;
constructor(options) {
this.url = options.url;
this.onReorg = options.onReorg;
this.onConnect = options.onConnect;
this.logger = options.logger ?? console;
this.reconnectDelayMs = options.reconnectDelayMs ?? 5000;
this.fetchImpl = options.fetchImpl ?? fetch;
}
/** Begins consuming the stream in the background. */
start() {
if (this.stopped) {
return;
}
void this.runLoop();
}
/** Stops consuming and aborts any in-flight connection. */
stop() {
this.stopped = true;
this.controller?.abort();
}
async runLoop() {
while (!this.stopped) {
try {
await this.connectOnce();
}
catch (error) {
if (!this.stopped) {
this.logger.warn(`[BASM] reorg stream error: ${error instanceof Error ? error.message : String(error)}`);
}
}
if (this.stopped) {
break;
}
await this.delay(this.reconnectDelayMs);
}
}
async connectOnce() {
this.controller = new AbortController();
const response = await this.fetchImpl(this.url, {
headers: { Accept: 'text/event-stream' },
signal: this.controller.signal
});
if (!response.ok || response.body == null) {
throw new Error(`reorg stream responded ${response.status}`);
}
// No event-id replay on this stream: catch up on (re)connect.
await this.runCatchUp();
await this.pumpEvents(response.body.getReader());
}
async runCatchUp() {
if (this.onConnect === undefined) {
return;
}
try {
await this.onConnect();
}
catch (error) {
this.logger.warn(`[BASM] reorg catch-up failed: ${error instanceof Error ? error.message : String(error)}`);
}
}
async pumpEvents(reader) {
const decoder = new TextDecoder();
let buffer = '';
while (!this.stopped) {
const { value, done } = await reader.read();
if (done) {
break;
}
buffer += decoder.decode(value, { stream: true });
const { events, rest } = extractSseFrames(buffer);
buffer = rest;
for (const frame of events) {
await this.processReorgFrame(frame);
}
}
}
async processReorgFrame(frame) {
const input = parseReorgEvent(frame);
if (input === null) {
this.logger.warn('[BASM] skipping malformed reorg frame');
return;
}
try {
await this.onReorg(input);
}
catch (error) {
this.logger.error(`[BASM] handleReorg failed: ${error instanceof Error ? error.message : String(error)}`);
}
}
async delay(ms) {
await new Promise(resolve => {
const timer = setTimeout(resolve, ms);
timer.unref?.();
});
}
}
//# sourceMappingURL=ReorgStream.js.map