@apibara/protocol 0.1.2 → 0.3.0

package/dist/buffer.d.ts

@@ -2,7 +2,7 @@
 /**
  * Converts the hex-encoded bytes to a `Buffer`.
  * @param hex The hex string
- * @param size The buffer size, in bits
+ * @param size The buffer size, in bytes
  */
 export declare function hexToBuffer(hex: string, size: number): Buffer;
 /**

package/dist/buffer.js

@@ -4,7 +4,7 @@ exports.bufferToHex = exports.hexToBuffer = void 0;
 /**
  * Converts the hex-encoded bytes to a `Buffer`.
  * @param hex The hex string
- * @param size The buffer size, in bits
+ * @param size The buffer size, in bytes
  */
 function hexToBuffer(hex, size) {
     const padSize = size * 2;

package/dist/client.d.ts

@@ -1,7 +1,7 @@
-import { ClientOptions, ChannelCredentials, ClientReadableStream } from '@grpc/grpc-js';
+import { ClientOptions, ChannelCredentials } from '@grpc/grpc-js';
+import { Retry, StreamMessagesStream } from './stream';
 import { NodeClient as GrpcNodeClient } from './proto/apibara/node/v1alpha1/Node';
 import { StatusResponse__Output } from './proto/apibara/node/v1alpha1/StatusResponse';
-import { StreamMessagesResponse__Output } from './proto/apibara/node/v1alpha1/StreamMessagesResponse';
 import { StreamMessagesRequest } from './proto/apibara/node/v1alpha1/StreamMessagesRequest';
 export declare const Node: (new (address: string, credentials: ChannelCredentials, options?: ClientOptions | undefined) => GrpcNodeClient) & {
     service: import("./proto/apibara/node/v1alpha1/Node").NodeDefinition;
@@ -16,9 +16,13 @@ export declare const credentials: {
     createFromGoogleCredential: typeof import("@grpc/grpc-js").CallCredentials.createFromGoogleCredential;
     createEmpty: typeof import("@grpc/grpc-js").CallCredentials.createEmpty;
 };
+export interface StreamMessagesOptions {
+    reconnect?: boolean;
+    onRetry?: (retryCount: number) => Retry;
+}
 export declare class NodeClient {
     private readonly client;
     constructor(address: string, credentials: ChannelCredentials, options?: ClientOptions);
     status(): Promise<StatusResponse__Output | undefined>;
-    streamMessages(args: StreamMessagesRequest): ClientReadableStream<StreamMessagesResponse__Output>;
+    streamMessages(args: StreamMessagesRequest, options?: StreamMessagesOptions): StreamMessagesStream;
 }

package/dist/client.js

@@ -13,6 +13,7 @@ exports.NodeClient = exports.credentials = exports.Node = void 0;
 const util_1 = require("util");
 const grpc_js_1 = require("@grpc/grpc-js");
 const proto_loader_1 = require("@grpc/proto-loader");
+const stream_1 = require("./stream");
 const __NODE_PROTO_PATH = __dirname + '/proto/node.proto';
 const packageDefinition = (0, proto_loader_1.loadSync)(__NODE_PROTO_PATH, {});
 const protoDescriptor = (0, grpc_js_1.loadPackageDefinition)(packageDefinition);
@@ -27,8 +28,18 @@ class NodeClient {
             return (0, util_1.promisify)(this.client.Status.bind(this.client, {}))();
         });
     }
-    streamMessages(args) {
-        return this.client.streamMessages(args);
+    streamMessages(args, options) {
+        // only reconnect if user has opted-in
+        let onRetry = stream_1.neverRetry;
+        if (options === null || options === void 0 ? void 0 : options.reconnect) {
+            if (options.onRetry) {
+                onRetry = options.onRetry;
+            }
+            else {
+                onRetry = stream_1.defaultOnRetry;
+            }
+        }
+        return new stream_1.StreamMessagesStream({ args, onRetry, client: this.client });
     }
 }
 exports.NodeClient = NodeClient;

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,+BAAgC;AAChC,2CAMsB;AACtB,qDAA6C;AAO7C,MAAM,iBAAiB,GAAG,SAAS,GAAG,mBAAmB,CAAA;AAEzD,MAAM,iBAAiB,GAAG,IAAA,uBAAQ,EAAC,iBAAiB,EAAE,EAAE,CAAC,CAAA;AACzD,MAAM,eAAe,GAAG,IAAA,+BAAqB,EAAC,iBAAiB,CAA6B,CAAA;AAE/E,QAAA,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAA;AAEjD,QAAA,WAAW,GAAG,qBAAe,CAAA;AAE1C,MAAa,UAAU;IAGrB,YAAY,OAAe,EAAE,WAA+B,EAAE,OAAuB;QACnF,IAAI,CAAC,MAAM,GAAG,IAAI,YAAI,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC;IAEY,MAAM;;YACjB,OAAO,IAAA,gBAAS,EAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAA;QAC9D,CAAC;KAAA;IAEM,cAAc,CACnB,IAA2B;QAE3B,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;IACzC,CAAC;CACF;AAhBD,gCAgBC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,+BAAgC;AAChC,2CAKsB;AACtB,qDAA6C;AAC7C,qCAAkF;AAMlF,MAAM,iBAAiB,GAAG,SAAS,GAAG,mBAAmB,CAAA;AAEzD,MAAM,iBAAiB,GAAG,IAAA,uBAAQ,EAAC,iBAAiB,EAAE,EAAE,CAAC,CAAA;AACzD,MAAM,eAAe,GAAG,IAAA,+BAAqB,EAAC,iBAAiB,CAA6B,CAAA;AAE/E,QAAA,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAA;AAEjD,QAAA,WAAW,GAAG,qBAAe,CAAA;AAO1C,MAAa,UAAU;IAGrB,YAAY,OAAe,EAAE,WAA+B,EAAE,OAAuB;QACnF,IAAI,CAAC,MAAM,GAAG,IAAI,YAAI,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAA;IACvD,CAAC;IAEY,MAAM;;YACjB,OAAO,IAAA,gBAAS,EAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAA;QAC9D,CAAC;KAAA;IAEM,cAAc,CACnB,IAA2B,EAC3B,OAA+B;QAE/B,sCAAsC;QACtC,IAAI,OAAO,GAAG,mBAAU,CAAA;QACxB,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,SAAS,EAAE;YACtB,IAAI,OAAO,CAAC,OAAO,EAAE;gBACnB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;aAC1B;iBAAM;gBACL,OAAO,GAAG,uBAAc,CAAA;aACzB;SACF;QAED,OAAO,IAAI,6BAAoB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;IACzE,CAAC;CACF;AA3BD,gCA2BC"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './client';
 export * from './buffer';
+export * from './stream';
 export * as proto from './proto';

package/dist/index.js

@@ -29,5 +29,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.proto = void 0;
 __exportStar(require("./client"), exports);
 __exportStar(require("./buffer"), exports);
+__exportStar(require("./stream"), exports);
 exports.proto = __importStar(require("./proto"));
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,2CAAwB;AACxB,2CAAwB;AACxB,iDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,2CAAwB;AACxB,2CAAwB;AACxB,2CAAwB;AACxB,iDAAgC"}

package/dist/proto/apibara/node/v1alpha1/StreamMessagesRequest.d.ts

@@ -1,7 +1,9 @@
 import type { Long } from '@grpc/proto-loader';
 export interface StreamMessagesRequest {
     'startingSequence'?: (number | string | Long);
+    'pendingBlockIntervalSeconds'?: (number);
 }
 export interface StreamMessagesRequest__Output {
     'startingSequence': (string);
+    'pendingBlockIntervalSeconds': (number);
 }

package/dist/proto/apibara/node/v1alpha1/StreamMessagesResponse.d.ts

@@ -5,11 +5,13 @@ export interface StreamMessagesResponse {
     'invalidate'?: (_apibara_node_v1alpha1_Invalidate | null);
     'data'?: (_apibara_node_v1alpha1_Data | null);
     'heartbeat'?: (_apibara_node_v1alpha1_Heartbeat | null);
-    'message'?: "invalidate" | "data" | "heartbeat";
+    'pending'?: (_apibara_node_v1alpha1_Data | null);
+    'message'?: "invalidate" | "data" | "heartbeat" | "pending";
 }
 export interface StreamMessagesResponse__Output {
     'invalidate'?: (_apibara_node_v1alpha1_Invalidate__Output | null);
     'data'?: (_apibara_node_v1alpha1_Data__Output | null);
     'heartbeat'?: (_apibara_node_v1alpha1_Heartbeat__Output | null);
-    'message': "invalidate" | "data" | "heartbeat";
+    'pending'?: (_apibara_node_v1alpha1_Data__Output | null);
+    'message': "invalidate" | "data" | "heartbeat" | "pending";
 }

package/dist/proto/node.proto

@@ -70,6 +70,8 @@ message ConnectResponse {
 message StreamMessagesRequest {
   // Start streaming from the provided sequence number.
   uint64 starting_sequence = 1;
+  // If greater than 0, send pending blocks at the specified interval.
+  uint32 pending_block_interval_seconds = 2;
 }
 
 // Message sent from the node to the client.
@@ -78,6 +80,7 @@ message StreamMessagesResponse {
     Invalidate invalidate = 1;
     Data data = 2;
     Heartbeat heartbeat = 3;
+    Data pending = 4;
   }
 }
 

package/dist/stream.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" />
+import { Readable } from 'stream';
+import { NodeClient as GrpcNodeClient } from './proto/apibara/node/v1alpha1/Node';
+import { StreamMessagesResponse__Output } from './proto/apibara/node/v1alpha1/StreamMessagesResponse';
+import { StreamMessagesRequest } from './proto/apibara/node/v1alpha1/StreamMessagesRequest';
+export declare function neverRetry(_retryCount: number): Retry;
+export declare function defaultOnRetry(retryCount: number): Retry;
+export interface Retry {
+    retry: boolean;
+    startingSequence?: number;
+    delay?: number;
+}
+export declare class StreamMessagesStream extends Readable {
+    private readonly client;
+    private readonly initialRequest;
+    private readonly onRetry;
+    private source?;
+    private currentSequence?;
+    private retryCount;
+    constructor({ args, onRetry, client, }: {
+        args: StreamMessagesRequest;
+        onRetry: (retryCount: number) => Retry;
+        client: GrpcNodeClient;
+    });
+    _construct(callback: (error?: Error | null | undefined) => void): void;
+    _read(_size: number): void;
+    setupSource(startingSequence?: number): void;
+    cleanupSource(): void;
+    onData(chunk: StreamMessagesResponse__Output): void;
+    onError(_err: any): void;
+    onEnd(): void;
+}

package/dist/stream.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamMessagesStream = exports.defaultOnRetry = exports.neverRetry = void 0;
+const stream_1 = require("stream");
+const defaultMaxRetry = 3;
+const defaultDelaySeconds = 5;
+function neverRetry(_retryCount) {
+    return {
+        retry: false,
+    };
+}
+exports.neverRetry = neverRetry;
+function defaultOnRetry(retryCount) {
+    return {
+        retry: retryCount < defaultMaxRetry,
+        delay: defaultDelaySeconds,
+    };
+}
+exports.defaultOnRetry = defaultOnRetry;
+class StreamMessagesStream extends stream_1.Readable {
+    constructor({ args, onRetry, client, }) {
+        super({ objectMode: true });
+        this.initialRequest = args;
+        this.client = client;
+        this.onRetry = onRetry;
+        this.retryCount = 0;
+    }
+    _construct(callback) {
+        this.setupSource();
+        callback();
+    }
+    _read(_size) {
+        if (this.source) {
+            // resume source data if not flowing
+            if (!this.source.readableFlowing) {
+                this.source.resume();
+            }
+        }
+        else {
+            // create source stream
+            this.setupSource(this.currentSequence);
+        }
+    }
+    setupSource(startingSequence) {
+        const request = startingSequence !== undefined
+            ? Object.assign(Object.assign({}, this.initialRequest), { startingSequence }) : this.initialRequest;
+        this.source = this.client.streamMessages(request);
+        this.source.on('data', this.onData.bind(this));
+        this.source.once('error', this.onError.bind(this));
+        this.source.once('end', this.onEnd.bind(this));
+    }
+    cleanupSource() {
+        if (!this.source) {
+            return;
+        }
+        this.source.off('data', this.onData.bind(this));
+        this.source.off('error', this.onData.bind(this));
+        this.source.off('end', this.onEnd.bind(this));
+    }
+    onData(chunk) {
+        var _a;
+        // reset retry count
+        this.retryCount = 0;
+        if (chunk.data) {
+            this.currentSequence = +chunk.data.sequence;
+        }
+        else if (chunk.invalidate) {
+            this.currentSequence = +chunk.invalidate;
+        }
+        // apply backpressure on stream
+        if (!this.push(chunk)) {
+            (_a = this.source) === null || _a === void 0 ? void 0 : _a.pause();
+        }
+    }
+    onError(_err) {
+        this.cleanupSource();
+        this.retryCount += 1;
+        const { retry, delay, startingSequence } = this.onRetry(this.retryCount);
+        if (retry) {
+            const intervalDelayMs = (delay !== null && delay !== void 0 ? delay : defaultDelaySeconds) * 1000;
+            setTimeout(() => {
+                this.setupSource(startingSequence);
+            }, intervalDelayMs);
+        }
+    }
+    onEnd() {
+        // block streams never end
+        if (this.retryCount > 0) {
+            return;
+        }
+        this.cleanupSource();
+    }
+}
+exports.StreamMessagesStream = StreamMessagesStream;
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"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"}

package/dist/stream.test.js

@@ -0,0 +1,19 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+describe('StreamMessagesStream', () => {
+    it('produces data', () => __awaiter(void 0, void 0, void 0, function* () { }));
+    describe('on error', () => {
+        it('produces an error by default', () => { });
+        it('reconnects', () => { });
+        it('produces an error after trying to reconnect', () => { });
+    });
+});
+//# sourceMappingURL=stream.test.js.map

package/dist/stream.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.test.js","sourceRoot":"","sources":["../src/stream.test.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,eAAe,EAAE,GAAS,EAAE,kDAAE,CAAC,CAAA,CAAC,CAAA;IAEnC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;QACxB,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QAC5C,EAAE,CAAC,YAAY,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QAC1B,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAC7D,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apibara/protocol",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "source": "src/index.ts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,6 +20,7 @@
   "scripts": {
     "prebuild": "pnpm run protobuf && pnpm run gen-types",
     "build": "tsc",
+    "test": "jest",
     "lint": "eslint src --ext .ts",
     "lint:fix": "eslint --fix src --ext .ts",
     "protobuf": "mkdir -p dist/proto && cp src/proto/*.proto dist/proto",

package/src/buffer.ts

@@ -1,7 +1,7 @@
 /**
  * Converts the hex-encoded bytes to a `Buffer`.
  * @param hex The hex string
- * @param size The buffer size, in bits
+ * @param size The buffer size, in bytes
  */
 export function hexToBuffer(hex: string, size: number): Buffer {
   const padSize = size * 2

package/src/client.ts

@@ -4,13 +4,12 @@ import {
   credentials as grpcCredentials,
   ClientOptions,
   ChannelCredentials,
-  ClientReadableStream,
 } from '@grpc/grpc-js'
 import { loadSync } from '@grpc/proto-loader'
+import { Retry, neverRetry, defaultOnRetry, StreamMessagesStream } from './stream'
 import { NodeClient as GrpcNodeClient } from './proto/apibara/node/v1alpha1/Node'
 import { ProtoGrpcType } from './proto/node'
 import { StatusResponse__Output } from './proto/apibara/node/v1alpha1/StatusResponse'
-import { StreamMessagesResponse__Output } from './proto/apibara/node/v1alpha1/StreamMessagesResponse'
 import { StreamMessagesRequest } from './proto/apibara/node/v1alpha1/StreamMessagesRequest'
 
 const __NODE_PROTO_PATH = __dirname + '/proto/node.proto'
@@ -22,6 +21,11 @@ export const Node = protoDescriptor.apibara.node.v1alpha1.Node
 
 export const credentials = grpcCredentials
 
+export interface StreamMessagesOptions {
+  reconnect?: boolean
+  onRetry?: (retryCount: number) => Retry
+}
+
 export class NodeClient {
   private readonly client: GrpcNodeClient
 
@@ -34,8 +38,19 @@ export class NodeClient {
   }
 
   public streamMessages(
-    args: StreamMessagesRequest
-  ): ClientReadableStream<StreamMessagesResponse__Output> {
-    return this.client.streamMessages(args)
+    args: StreamMessagesRequest,
+    options?: StreamMessagesOptions
+  ): StreamMessagesStream {
+    // only reconnect if user has opted-in
+    let onRetry = neverRetry
+    if (options?.reconnect) {
+      if (options.onRetry) {
+        onRetry = options.onRetry
+      } else {
+        onRetry = defaultOnRetry
+      }
+    }
+
+    return new StreamMessagesStream({ args, onRetry, client: this.client })
   }
 }

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './client'
 export * from './buffer'
+export * from './stream'
 export * as proto from './proto'

package/src/proto/apibara/node/v1alpha1/StreamMessagesRequest.ts

@@ -4,8 +4,10 @@ import type { Long } from '@grpc/proto-loader';
 
 export interface StreamMessagesRequest {
   'startingSequence'?: (number | string | Long);
+  'pendingBlockIntervalSeconds'?: (number);
 }
 
 export interface StreamMessagesRequest__Output {
   'startingSequence': (string);
+  'pendingBlockIntervalSeconds': (number);
 }

package/src/proto/apibara/node/v1alpha1/StreamMessagesResponse.ts

@@ -8,12 +8,14 @@ export interface StreamMessagesResponse {
   'invalidate'?: (_apibara_node_v1alpha1_Invalidate | null);
   'data'?: (_apibara_node_v1alpha1_Data | null);
   'heartbeat'?: (_apibara_node_v1alpha1_Heartbeat | null);
-  'message'?: "invalidate"|"data"|"heartbeat";
+  'pending'?: (_apibara_node_v1alpha1_Data | null);
+  'message'?: "invalidate"|"data"|"heartbeat"|"pending";
 }
 
 export interface StreamMessagesResponse__Output {
   'invalidate'?: (_apibara_node_v1alpha1_Invalidate__Output | null);
   'data'?: (_apibara_node_v1alpha1_Data__Output | null);
   'heartbeat'?: (_apibara_node_v1alpha1_Heartbeat__Output | null);
-  'message': "invalidate"|"data"|"heartbeat";
+  'pending'?: (_apibara_node_v1alpha1_Data__Output | null);
+  'message': "invalidate"|"data"|"heartbeat"|"pending";
 }

package/src/proto/node.proto

@@ -70,6 +70,8 @@ message ConnectResponse {
 message StreamMessagesRequest {
   // Start streaming from the provided sequence number.
   uint64 starting_sequence = 1;
+  // If greater than 0, send pending blocks at the specified interval.
+  uint32 pending_block_interval_seconds = 2;
 }
 
 // Message sent from the node to the client.
@@ -78,6 +80,7 @@ message StreamMessagesResponse {
     Invalidate invalidate = 1;
     Data data = 2;
     Heartbeat heartbeat = 3;
+    Data pending = 4;
   }
 }
 

package/src/stream.test.ts

@@ -0,0 +1,9 @@
+describe('StreamMessagesStream', () => {
+  it('produces data', async () => {})
+
+  describe('on error', () => {
+    it('produces an error by default', () => {})
+    it('reconnects', () => {})
+    it('produces an error after trying to reconnect', () => {})
+  })
+})

package/src/stream.ts

@@ -0,0 +1,127 @@
+import { Readable } from 'stream'
+import { ClientReadableStream } from '@grpc/grpc-js'
+import { NodeClient as GrpcNodeClient } from './proto/apibara/node/v1alpha1/Node'
+import { StreamMessagesResponse__Output } from './proto/apibara/node/v1alpha1/StreamMessagesResponse'
+import { StreamMessagesRequest } from './proto/apibara/node/v1alpha1/StreamMessagesRequest'
+
+const defaultMaxRetry = 3
+const defaultDelaySeconds = 5
+
+export function neverRetry(_retryCount: number): Retry {
+  return {
+    retry: false,
+  }
+}
+
+export function defaultOnRetry(retryCount: number): Retry {
+  return {
+    retry: retryCount < defaultMaxRetry,
+    delay: defaultDelaySeconds,
+  }
+}
+
+export interface Retry {
+  retry: boolean
+  startingSequence?: number
+  delay?: number
+}
+
+export class StreamMessagesStream extends Readable {
+  private readonly client: GrpcNodeClient
+  private readonly initialRequest: StreamMessagesRequest
+  private readonly onRetry: (retryCount: number) => Retry
+  private source?: ClientReadableStream<StreamMessagesResponse__Output>
+  private currentSequence?: number
+  private retryCount: number
+
+  constructor({
+    args,
+    onRetry,
+    client,
+  }: {
+    args: StreamMessagesRequest
+    onRetry: (retryCount: number) => Retry
+    client: GrpcNodeClient
+  }) {
+    super({ objectMode: true })
+    this.initialRequest = args
+    this.client = client
+    this.onRetry = onRetry
+    this.retryCount = 0
+  }
+
+  _construct(callback: (error?: Error | null | undefined) => void): void {
+    this.setupSource()
+    callback()
+  }
+
+  _read(_size: number): void {
+    if (this.source) {
+      // resume source data if not flowing
+      if (!this.source.readableFlowing) {
+        this.source.resume()
+      }
+    } else {
+      // create source stream
+      this.setupSource(this.currentSequence)
+    }
+  }
+
+  setupSource(startingSequence?: number) {
+    const request =
+      startingSequence !== undefined
+        ? { ...this.initialRequest, startingSequence }
+        : this.initialRequest
+    this.source = this.client.streamMessages(request)
+
+    this.source.on('data', this.onData.bind(this))
+    this.source.once('error', this.onError.bind(this))
+    this.source.once('end', this.onEnd.bind(this))
+  }
+
+  cleanupSource() {
+    if (!this.source) {
+      return
+    }
+
+    this.source.off('data', this.onData.bind(this))
+    this.source.off('error', this.onData.bind(this))
+    this.source.off('end', this.onEnd.bind(this))
+  }
+
+  onData(chunk: StreamMessagesResponse__Output) {
+    // reset retry count
+    this.retryCount = 0
+    if (chunk.data) {
+      this.currentSequence = +chunk.data.sequence
+    } else if (chunk.invalidate) {
+      this.currentSequence = +chunk.invalidate
+    }
+
+    // apply backpressure on stream
+    if (!this.push(chunk)) {
+      this.source?.pause()
+    }
+  }
+
+  onError(_err: any) {
+    this.cleanupSource()
+    this.retryCount += 1
+
+    const { retry, delay, startingSequence } = this.onRetry(this.retryCount)
+    if (retry) {
+      const intervalDelayMs = (delay ?? defaultDelaySeconds) * 1000
+      setTimeout(() => {
+        this.setupSource(startingSequence)
+      }, intervalDelayMs)
+    }
+  }
+
+  onEnd() {
+    // block streams never end
+    if (this.retryCount > 0) {
+      return
+    }
+    this.cleanupSource()
+  }
+}