@apibara/protocol 0.4.0-next.0 → 0.4.0

package/dist/client.d.ts

@@ -1,29 +1,119 @@
-import { ChannelCredentials, ClientDuplexStream } from '@grpc/grpc-js';
+import { ChannelCredentials, ClientDuplexStream, ClientOptions, StatusObject } from '@grpc/grpc-js';
 import { v1alpha2 } from './proto';
-export { ChannelCredentials } from '@grpc/grpc-js';
-export declare type ErrorHandler = (client: StreamClient, err: Error) => void | Promise<void>;
-export declare type CloseHandler = (client: StreamClient) => void | Promise<void>;
-export declare type DataHandler = (client: StreamClient, data: v1alpha2.IData) => void | Promise<void>;
-export declare type InvalidateHandler = (client: StreamClient, invalidate: v1alpha2.IInvalidate) => void | Promise<void>;
-export declare type HeartbeatHandler = (client: StreamClient, invalidate: v1alpha2.IHeartbeat) => void | Promise<void>;
+export { ChannelCredentials, StatusObject } from '@grpc/grpc-js';
 export declare type DataStream = ClientDuplexStream<v1alpha2.IStreamDataRequest, v1alpha2.IStreamDataResponse>;
+export declare type ConfigureArgs = {
+    /**
+     * Stream filter, encoded.
+     */
+    filter: Uint8Array;
+    /**
+     * How much data in a single message.
+     */
+    batchSize?: number;
+    /**
+     * Starting cursor. This cursor is stream-specific.
+     */
+    cursor?: v1alpha2.ICursor | null;
+    /**
+     * Data finality, e.g. finalized or accepted.
+     */
+    finality?: v1alpha2.DataFinality | null;
+};
+/**
+ * Reconnect callback return value.
+ */
+export declare type OnReconnectResult = {
+    /**
+     * If `true`, reconnects to the stream.
+     */
+    reconnect: boolean;
+    /**
+     * Stream configuration used when reconnecting.
+     *
+     * By default, the client uses the last configuration passed to
+     * `configure` and updates the `cursor` with the most recent one.
+     */
+    args?: ConfigureArgs;
+};
+/**
+ * Reconnect callback.
+ */
+export declare type OnReconnect = (err: StatusObject, retryCount: number) => Promise<OnReconnectResult> | OnReconnectResult;
+export declare type StreamClientArgs = {
+    /**
+     * The stream url.
+     */
+    url: string;
+    /**
+     * Grpc credentials.
+     *
+     * Use `ChannelCredentials.createInsecure()` to disable SSL.
+     */
+    credentials?: ChannelCredentials;
+    /**
+     * Grpc client options.
+     */
+    clientOptions?: ClientOptions;
+    /**
+     * Callback to control reconnection after receiving an error from the stream.
+     *
+     * By default uses `defaultOnReconnect`, which only reconnects on internal grpc errors.
+     */
+    onReconnect?: OnReconnect;
+};
+/**
+ * A client to configure and stream data.
+ */
 export declare class StreamClient {
     private readonly inner;
     private stream?;
-    private configured;
     private stream_id;
-    constructor({ url, credentials }: {
-        url: string;
-        credentials?: ChannelCredentials;
-    });
-    connect(): this;
+    private onReconnect;
+    private configuration?;
+    /**
+     * Create a new `StreamClient`.
+     *
+     * Notice that the stream is not connected until you start iterating over it.
+     * The stream should be used as an _async iterator_.
+     *
+     * @example
+     * ```ts
+     * import { StreamClient } from '@apibara/protocol'
+     *
+     * const client = new StreamClient({ url })
+     *
+     * client.configure({ filter, cursor })
+     *
+     * for await (const message of client) {
+     *   // use message
+     * }
+     * ```
+     */
+    constructor({ url, credentials, clientOptions, onReconnect }: StreamClientArgs);
+    /**
+     * Async iterator over messages in the stream.
+     */
     [Symbol.asyncIterator](): AsyncIterator<v1alpha2.IStreamDataResponse>;
-    configure({ filter, batchSize, cursor, finality, }: {
-        filter: Uint8Array;
-        batchSize?: number;
-        cursor?: v1alpha2.ICursor | null;
-        finality?: v1alpha2.DataFinality | null;
-    }): void;
-    private ensureConnected;
-    private ensureConfigured;
+    /**
+     * Configure the stream to return the requested data.
+     *
+     * The stream can be reconfigured while streaming data, the client will
+     * take care of returning only data for the new configuration even if there
+     * are old messages in-flight.
+     */
+    configure(args: ConfigureArgs): void;
+    private _configure;
+    private connect;
 }
+/**
+ * A `onReconnect` callback that never reconnects.
+ */
+export declare function neverReconnect(_err: StatusObject, _retryCount: number): OnReconnectResult;
+/**
+ * A `onReconnect` callback that retries to reconnect up to 5 times.
+ *
+ * If the error is not an internal error, then it will not reconnect.
+ * This callback awaits for `1s * retryCount` before returning.
+ */
+export declare function defaultOnReconnect(err: StatusObject, retryCount: number): Promise<OnReconnectResult>;

package/dist/client.js

@@ -1,64 +1,170 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StreamClient = exports.ChannelCredentials = void 0;
+exports.defaultOnReconnect = exports.neverReconnect = exports.StreamClient = exports.ChannelCredentials = void 0;
 const grpc_js_1 = require("@grpc/grpc-js");
 const proto_1 = require("./proto");
 const request_1 = require("./request");
 var grpc_js_2 = require("@grpc/grpc-js");
 Object.defineProperty(exports, "ChannelCredentials", { enumerable: true, get: function () { return grpc_js_2.ChannelCredentials; } });
 const StreamService = proto_1.v1alpha2.protoDescriptor.apibara.node.v1alpha2.Stream;
+/**
+ * A client to configure and stream data.
+ */
 class StreamClient {
-    constructor({ url, credentials }) {
+    /**
+     * Create a new `StreamClient`.
+     *
+     * Notice that the stream is not connected until you start iterating over it.
+     * The stream should be used as an _async iterator_.
+     *
+     * @example
+     * ```ts
+     * import { StreamClient } from '@apibara/protocol'
+     *
+     * const client = new StreamClient({ url })
+     *
+     * client.configure({ filter, cursor })
+     *
+     * for await (const message of client) {
+     *   // use message
+     * }
+     * ```
+     */
+    constructor({ url, credentials, clientOptions, onReconnect }) {
         this.inner = new StreamService(url, credentials ?? grpc_js_1.ChannelCredentials.createSsl(), {
             'grpc.keepalive_timeout_ms': 3600000,
+            ...clientOptions,
         });
-        this.configured = false;
         this.stream_id = 0;
+        this.onReconnect = onReconnect ?? defaultOnReconnect;
     }
-    connect() {
-        this.stream = this.inner.streamData();
-        return this;
-    }
+    /**
+     * Async iterator over messages in the stream.
+     */
     async *[Symbol.asyncIterator]() {
-        this.ensureConnected();
-        this.ensureConfigured();
-        if (this.stream) {
-            for await (const message of this.stream) {
-                const messageTyped = message;
-                // only return messages if they are with the most recently configured stream
-                if (messageTyped.streamId?.toString() == this.stream_id.toString()) {
-                    yield messageTyped;
+        if (!this.configuration) {
+            throw new Error('StreamClient must be configured');
+        }
+        // connect if not connected.
+        if (!this.stream) {
+            this.connect();
+            this._configure(this.configuration);
+        }
+        while (true) {
+            let retryCount = 1;
+            let cursor = null;
+            try {
+                // this check is to make ts happy
+                if (!this.stream) {
+                    throw new Error('Stream disconnected unexpectedly');
+                }
+                for await (const message of this.stream) {
+                    const messageTyped = message;
+                    // only return messages if they are with the most recently configured stream
+                    if (messageTyped.streamId?.toString() == this.stream_id.toString()) {
+                        // reset retry count on new message
+                        retryCount = 1;
+                        // keep cursor updated for use when reconnecting
+                        if (messageTyped.data) {
+                            cursor = messageTyped.data.cursor;
+                        }
+                        else if (messageTyped.invalidate) {
+                            cursor = messageTyped.invalidate.cursor;
+                        }
+                        yield messageTyped;
+                    }
+                }
+            }
+            catch (err) {
+                const isGrpcError = err.hasOwnProperty('code') &&
+                    err.hasOwnProperty('details') &&
+                    err.hasOwnProperty('metadata');
+                // non-grpc error, so just bubble it up
+                if (!isGrpcError) {
+                    throw err;
+                }
+                const { reconnect, args } = await Promise.resolve(this.onReconnect(err, retryCount));
+                retryCount += 1;
+                if (!reconnect) {
+                    break;
+                }
+                this.connect();
+                if (args) {
+                    this._configure(args);
+                }
+                else {
+                    // use same configuration specified by user, restarting from the
+                    // latest ingested batch.
+                    const configuration = {
+                        ...this.configuration,
+                        cursor: cursor ?? this.configuration.cursor,
+                    };
+                    this._configure(configuration);
                 }
             }
         }
     }
-    configure({ filter, batchSize, cursor, finality, }) {
-        this.ensureConnected();
-        this.configured = true;
-        this.stream_id++;
-        const builder = request_1.StreamDataRequest.create().withStreamId(this.stream_id).withFilter(filter);
-        if (batchSize) {
-            builder.withBatchSize(batchSize);
-        }
-        if (cursor) {
-            builder.withStartingCursor(cursor);
-        }
-        if (finality) {
-            builder.withFinality(finality);
-        }
-        const request = builder.encode();
-        this.stream?.write(request);
+    /**
+     * Configure the stream to return the requested data.
+     *
+     * The stream can be reconfigured while streaming data, the client will
+     * take care of returning only data for the new configuration even if there
+     * are old messages in-flight.
+     */
+    configure(args) {
+        this.configuration = args;
+        this._configure(args);
     }
-    ensureConnected() {
-        if (!this.stream) {
-            throw new Error('StreamClient is not connected');
+    _configure(args) {
+        const { filter, batchSize, cursor, finality } = args;
+        this.stream_id++;
+        // only send configuration if connected
+        if (this.stream) {
+            const builder = request_1.StreamDataRequest.create().withStreamId(this.stream_id).withFilter(filter);
+            if (batchSize) {
+                builder.withBatchSize(batchSize);
+            }
+            if (cursor) {
+                builder.withStartingCursor(cursor);
+            }
+            if (finality) {
+                builder.withFinality(finality);
+            }
+            const request = builder.encode();
+            this.stream?.write(request);
         }
     }
-    ensureConfigured() {
-        if (!this.configured) {
-            throw new Error('StreamClient must be configured');
-        }
+    connect() {
+        this.stream = this.inner.streamData();
+        return this;
     }
 }
 exports.StreamClient = StreamClient;
+/**
+ * A `onReconnect` callback that never reconnects.
+ */
+function neverReconnect(_err, _retryCount) {
+    return {
+        reconnect: false,
+    };
+}
+exports.neverReconnect = neverReconnect;
+/**
+ * A `onReconnect` callback that retries to reconnect up to 5 times.
+ *
+ * If the error is not an internal error, then it will not reconnect.
+ * This callback awaits for `1s * retryCount` before returning.
+ */
+async function defaultOnReconnect(err, retryCount) {
+    if (err.code != 13) {
+        return {
+            reconnect: false,
+        };
+    }
+    await new Promise((resolve) => setTimeout(resolve, retryCount * 1000));
+    return {
+        reconnect: retryCount < 5,
+    };
+}
+exports.defaultOnReconnect = defaultOnReconnect;
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAAA,2CAAsE;AACtE,mCAAkC;AAClC,uCAA6C;AAE7C,yCAAkD;AAAzC,6GAAA,kBAAkB,OAAA;AAc3B,MAAM,aAAa,GAAG,gBAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAA;AAO3E,MAAa,YAAY;IAOvB,YAAY,EAAE,GAAG,EAAE,WAAW,EAAqD;QACjF,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,GAAG,EAAE,WAAW,IAAI,4BAAkB,CAAC,SAAS,EAAE,EAAE;YACjF,2BAA2B,EAAE,OAAS;SACvC,CAAC,CAAA;QACF,IAAI,CAAC,UAAU,GAAG,KAAK,CAAA;QACvB,IAAI,CAAC,SAAS,GAAG,CAAC,CAAA;IACpB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAA;QACrC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,IAAI,CAAC,eAAe,EAAE,CAAA;QACtB,IAAI,CAAC,gBAAgB,EAAE,CAAA;QAEvB,IAAI,IAAI,CAAC,MAAM,EAAE;YACf,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE;gBACvC,MAAM,YAAY,GAAG,OAAuC,CAAA;gBAC5D,4EAA4E;gBAC5E,IAAI,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE;oBAClE,MAAM,YAAY,CAAA;iBACnB;aACF;SACF;IACH,CAAC;IAED,SAAS,CAAC,EACR,MAAM,EACN,SAAS,EACT,MAAM,EACN,QAAQ,GAMT;QACC,IAAI,CAAC,eAAe,EAAE,CAAA;QACtB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAA;QAEtB,IAAI,CAAC,SAAS,EAAE,CAAA;QAEhB,MAAM,OAAO,GAAG,2BAAiB,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;QAE1F,IAAI,SAAS,EAAE;YACb,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAA;SACjC;QACD,IAAI,MAAM,EAAE;YACV,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;SACnC;QACD,IAAI,QAAQ,EAAE;YACZ,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAA;SAC/B;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAA;QAChC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC7B,CAAC;IAEO,eAAe;QACrB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAChB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAA;SACjD;IACH,CAAC;IAEO,gBAAgB;QACtB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;YACpB,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;SACnD;IACH,CAAC;CACF;AA9ED,oCA8EC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cursor.d.ts

@@ -0,0 +1,22 @@
+import Long from 'long';
+import { ICursor } from './proto/v1alpha2';
+export declare const Cursor: {
+    /**
+     * Creates a new cursor with only the `orderKey` set.
+     *
+     * Notice that this cursor does not uniquely identify a message in the stream
+     * and may result in missing information.
+     */
+    createWithOrderKey: (order: string | number | Long) => ICursor;
+    /**
+     * Creates a new cursor with both order and unique keys.
+     *
+     * This cursor uniquely identifies a message in the stream, even if it has
+     * been invalidated.
+     */
+    create: (order: string | number | Long, unique: Uint8Array) => ICursor;
+    /**
+     * Returns the cursor string representation.
+     */
+    toString: (cursor?: ICursor | null) => string | undefined;
+};

package/dist/cursor.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cursor = void 0;
+const long_1 = __importDefault(require("long"));
+exports.Cursor = {
+    /**
+     * Creates a new cursor with only the `orderKey` set.
+     *
+     * Notice that this cursor does not uniquely identify a message in the stream
+     * and may result in missing information.
+     */
+    createWithOrderKey: (order) => {
+        return {
+            orderKey: long_1.default.fromValue(order),
+            uniqueKey: new Uint8Array(),
+        };
+    },
+    /**
+     * Creates a new cursor with both order and unique keys.
+     *
+     * This cursor uniquely identifies a message in the stream, even if it has
+     * been invalidated.
+     */
+    create: (order, unique) => {
+        return {
+            orderKey: long_1.default.fromValue(order),
+            uniqueKey: unique,
+        };
+    },
+    /**
+     * Returns the cursor string representation.
+     */
+    toString: (cursor) => {
+        if (!cursor)
+            return;
+        let hash = Buffer.from(cursor.uniqueKey).toString('hex');
+        return `${cursor.orderKey.toString()}/0x${hash}`;
+    },
+};
+//# sourceMappingURL=cursor.js.map

package/dist/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":";;;;;;AAAA,gDAAuB;AAGV,QAAA,MAAM,GAAG;IACpB;;;;;OAKG;IACH,kBAAkB,EAAE,CAAC,KAA6B,EAAW,EAAE;QAC7D,OAAO;YACL,QAAQ,EAAE,cAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAC/B,SAAS,EAAE,IAAI,UAAU,EAAE;SAC5B,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACH,MAAM,EAAE,CAAC,KAA6B,EAAE,MAAkB,EAAW,EAAE;QACrE,OAAO;YACL,QAAQ,EAAE,cAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAC/B,SAAS,EAAE,MAAM;SAClB,CAAA;IACH,CAAC;IAED;;OAEG;IACH,QAAQ,EAAE,CAAC,MAAuB,EAAsB,EAAE;QACxD,IAAI,CAAC,MAAM;YAAE,OAAM;QACnB,IAAI,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QACxD,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAA;IAClD,CAAC;CACF,CAAA"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './proto';
 export * from './client';
 export * from './request';
+export * from './cursor';

package/dist/index.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./proto"), exports);
 __exportStar(require("./client"), exports);
 __exportStar(require("./request"), exports);
+__exportStar(require("./cursor"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/proto/apibara/node/v1alpha2/Data.d.ts

@@ -5,9 +5,11 @@ export interface Data {
     'endCursor'?: (_apibara_node_v1alpha2_Cursor | null);
     'finality'?: (_apibara_node_v1alpha2_DataFinality | keyof typeof _apibara_node_v1alpha2_DataFinality);
     'data'?: (Buffer | Uint8Array | string)[];
+    'cursor'?: (_apibara_node_v1alpha2_Cursor | null);
 }
 export interface Data__Output {
     'endCursor': (_apibara_node_v1alpha2_Cursor__Output | null);
     'finality': (keyof typeof _apibara_node_v1alpha2_DataFinality);
     'data': (Uint8Array)[];
+    'cursor': (_apibara_node_v1alpha2_Cursor__Output | null);
 }

package/dist/proto/apibara/node/v1alpha2/StreamDataResponse.d.ts

@@ -4,15 +4,15 @@ import type { Heartbeat as _apibara_node_v1alpha2_Heartbeat, Heartbeat__Output a
 import type { Long } from '@grpc/proto-loader';
 export interface StreamDataResponse {
     'streamId'?: (number | string | Long);
-    'Invalidate'?: (_apibara_node_v1alpha2_Invalidate | null);
+    'invalidate'?: (_apibara_node_v1alpha2_Invalidate | null);
     'data'?: (_apibara_node_v1alpha2_Data | null);
     'heartbeat'?: (_apibara_node_v1alpha2_Heartbeat | null);
-    'message'?: "Invalidate" | "data" | "heartbeat";
+    'message'?: "invalidate" | "data" | "heartbeat";
 }
 export interface StreamDataResponse__Output {
     'streamId': (Long);
-    'Invalidate'?: (_apibara_node_v1alpha2_Invalidate__Output | null);
+    'invalidate'?: (_apibara_node_v1alpha2_Invalidate__Output | null);
     'data'?: (_apibara_node_v1alpha2_Data__Output | null);
     'heartbeat'?: (_apibara_node_v1alpha2_Heartbeat__Output | null);
-    'message': "Invalidate" | "data" | "heartbeat";
+    'message': "invalidate" | "data" | "heartbeat";
 }

package/dist/proto/stream.proto

@@ -29,7 +29,7 @@ message StreamDataResponse {
   // The stream id.
   uint64 stream_id = 1;
   oneof message {
-    Invalidate Invalidate = 2;
+    Invalidate invalidate = 2;
     Data data = 3;
     Heartbeat heartbeat = 4;
   }
@@ -68,6 +68,8 @@ message Data {
   DataFinality finality = 2;
   // The stream data.
   repeated bytes data = 3;
+  // Cursor used to produced the batch.
+  Cursor cursor = 4;
 }
 
 // Sent to clients to check if stream is still connected.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apibara/protocol",
-  "version": "0.4.0-next.0",
+  "version": "0.4.0",
   "source": "src/index.ts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.ts

@@ -1,20 +1,8 @@
-import { ChannelCredentials, ClientDuplexStream } from '@grpc/grpc-js'
+import { ChannelCredentials, ClientDuplexStream, ClientOptions, StatusObject } from '@grpc/grpc-js'
 import { v1alpha2 } from './proto'
 import { StreamDataRequest } from './request'
 
-export { ChannelCredentials } from '@grpc/grpc-js'
-
-export type ErrorHandler = (client: StreamClient, err: Error) => void | Promise<void>
-export type CloseHandler = (client: StreamClient) => void | Promise<void>
-export type DataHandler = (client: StreamClient, data: v1alpha2.IData) => void | Promise<void>
-export type InvalidateHandler = (
-  client: StreamClient,
-  invalidate: v1alpha2.IInvalidate
-) => void | Promise<void>
-export type HeartbeatHandler = (
-  client: StreamClient,
-  invalidate: v1alpha2.IHeartbeat
-) => void | Promise<void>
+export { ChannelCredentials, StatusObject } from '@grpc/grpc-js'
 
 const StreamService = v1alpha2.protoDescriptor.apibara.node.v1alpha2.Stream
 
@@ -23,82 +11,261 @@ export type DataStream = ClientDuplexStream<
   v1alpha2.IStreamDataResponse
 >
 
+export type ConfigureArgs = {
+  /**
+   * Stream filter, encoded.
+   */
+  filter: Uint8Array
+
+  /**
+   * How much data in a single message.
+   */
+  batchSize?: number
+
+  /**
+   * Starting cursor. This cursor is stream-specific.
+   */
+  cursor?: v1alpha2.ICursor | null
+
+  /**
+   * Data finality, e.g. finalized or accepted.
+   */
+  finality?: v1alpha2.DataFinality | null
+}
+
+/**
+ * Reconnect callback return value.
+ */
+export type OnReconnectResult = {
+  /**
+   * If `true`, reconnects to the stream.
+   */
+  reconnect: boolean
+
+  /**
+   * Stream configuration used when reconnecting.
+   *
+   * By default, the client uses the last configuration passed to
+   * `configure` and updates the `cursor` with the most recent one.
+   */
+  args?: ConfigureArgs
+}
+
+/**
+ * Reconnect callback.
+ */
+export type OnReconnect = (
+  err: StatusObject,
+  retryCount: number
+) => Promise<OnReconnectResult> | OnReconnectResult
+
+export type StreamClientArgs = {
+  /**
+   * The stream url.
+   */
+  url: string
+
+  /**
+   * Grpc credentials.
+   *
+   * Use `ChannelCredentials.createInsecure()` to disable SSL.
+   */
+  credentials?: ChannelCredentials
+
+  /**
+   * Grpc client options.
+   */
+  clientOptions?: ClientOptions
+  /**
+   * Callback to control reconnection after receiving an error from the stream.
+   *
+   * By default uses `defaultOnReconnect`, which only reconnects on internal grpc errors.
+   */
+  onReconnect?: OnReconnect
+}
+
+/**
+ * A client to configure and stream data.
+ */
 export class StreamClient {
   private readonly inner: v1alpha2.StreamClient
 
   private stream?: DataStream
-  private configured: boolean
   private stream_id: number
+  private onReconnect: OnReconnect
+  private configuration?: ConfigureArgs
 
-  constructor({ url, credentials }: { url: string; credentials?: ChannelCredentials }) {
+  /**
+   * Create a new `StreamClient`.
+   *
+   * Notice that the stream is not connected until you start iterating over it.
+   * The stream should be used as an _async iterator_.
+   *
+   * @example
+   * ```ts
+   * import { StreamClient } from '@apibara/protocol'
+   *
+   * const client = new StreamClient({ url })
+   *
+   * client.configure({ filter, cursor })
+   *
+   * for await (const message of client) {
+   *   // use message
+   * }
+   * ```
+   */
+  constructor({ url, credentials, clientOptions, onReconnect }: StreamClientArgs) {
     this.inner = new StreamService(url, credentials ?? ChannelCredentials.createSsl(), {
       'grpc.keepalive_timeout_ms': 3_600_000,
+      ...clientOptions,
     })
-    this.configured = false
     this.stream_id = 0
+    this.onReconnect = onReconnect ?? defaultOnReconnect
   }
 
-  connect() {
-    this.stream = this.inner.streamData()
-    return this
-  }
-
+  /**
+   * Async iterator over messages in the stream.
+   */
   async *[Symbol.asyncIterator](): AsyncIterator<v1alpha2.IStreamDataResponse> {
-    this.ensureConnected()
-    this.ensureConfigured()
+    if (!this.configuration) {
+      throw new Error('StreamClient must be configured')
+    }
 
-    if (this.stream) {
-      for await (const message of this.stream) {
-        const messageTyped = message as v1alpha2.IStreamDataResponse
-        // only return messages if they are with the most recently configured stream
-        if (messageTyped.streamId?.toString() == this.stream_id.toString()) {
-          yield messageTyped
+    // connect if not connected.
+    if (!this.stream) {
+      this.connect()
+      this._configure(this.configuration)
+    }
+
+    while (true) {
+      let retryCount = 1
+      let cursor = null
+      try {
+        // this check is to make ts happy
+        if (!this.stream) {
+          throw new Error('Stream disconnected unexpectedly')
+        }
+
+        for await (const message of this.stream) {
+          const messageTyped = message as v1alpha2.IStreamDataResponse
+
+          // only return messages if they are with the most recently configured stream
+          if (messageTyped.streamId?.toString() == this.stream_id.toString()) {
+            // reset retry count on new message
+            retryCount = 1
+
+            // keep cursor updated for use when reconnecting
+            if (messageTyped.data) {
+              cursor = messageTyped.data.cursor
+            } else if (messageTyped.invalidate) {
+              cursor = messageTyped.invalidate.cursor
+            }
+
+            yield messageTyped
+          }
+        }
+      } catch (err: any) {
+        const isGrpcError =
+          err.hasOwnProperty('code') &&
+          err.hasOwnProperty('details') &&
+          err.hasOwnProperty('metadata')
+
+        // non-grpc error, so just bubble it up
+        if (!isGrpcError) {
+          throw err
+        }
+
+        const { reconnect, args } = await Promise.resolve(this.onReconnect(err, retryCount))
+        retryCount += 1
+        if (!reconnect) {
+          break
+        }
+
+        this.connect()
+
+        if (args) {
+          this._configure(args)
+        } else {
+          // use same configuration specified by user, restarting from the
+          // latest ingested batch.
+          const configuration = {
+            ...this.configuration,
+            cursor: cursor ?? this.configuration.cursor,
+          }
+          this._configure(configuration)
         }
       }
     }
   }
 
-  configure({
-    filter,
-    batchSize,
-    cursor,
-    finality,
-  }: {
-    filter: Uint8Array
-    batchSize?: number
-    cursor?: v1alpha2.ICursor | null
-    finality?: v1alpha2.DataFinality | null
-  }) {
-    this.ensureConnected()
-    this.configured = true
+  /**
+   * Configure the stream to return the requested data.
+   *
+   * The stream can be reconfigured while streaming data, the client will
+   * take care of returning only data for the new configuration even if there
+   * are old messages in-flight.
+   */
+  configure(args: ConfigureArgs) {
+    this.configuration = args
+    this._configure(args)
+  }
 
+  private _configure(args: ConfigureArgs) {
+    const { filter, batchSize, cursor, finality } = args
     this.stream_id++
 
-    const builder = StreamDataRequest.create().withStreamId(this.stream_id).withFilter(filter)
+    // only send configuration if connected
+    if (this.stream) {
+      const builder = StreamDataRequest.create().withStreamId(this.stream_id).withFilter(filter)
 
-    if (batchSize) {
-      builder.withBatchSize(batchSize)
-    }
-    if (cursor) {
-      builder.withStartingCursor(cursor)
-    }
-    if (finality) {
-      builder.withFinality(finality)
+      if (batchSize) {
+        builder.withBatchSize(batchSize)
+      }
+      if (cursor) {
+        builder.withStartingCursor(cursor)
+      }
+      if (finality) {
+        builder.withFinality(finality)
+      }
+
+      const request = builder.encode()
+      this.stream?.write(request)
     }
+  }
 
-    const request = builder.encode()
-    this.stream?.write(request)
+  private connect() {
+    this.stream = this.inner.streamData()
+    return this
   }
+}
 
-  private ensureConnected() {
-    if (!this.stream) {
-      throw new Error('StreamClient is not connected')
-    }
+/**
+ * A `onReconnect` callback that never reconnects.
+ */
+export function neverReconnect(_err: StatusObject, _retryCount: number): OnReconnectResult {
+  return {
+    reconnect: false,
   }
+}
 
-  private ensureConfigured() {
-    if (!this.configured) {
-      throw new Error('StreamClient must be configured')
+/**
+ * A `onReconnect` callback that retries to reconnect up to 5 times.
+ *
+ * If the error is not an internal error, then it will not reconnect.
+ * This callback awaits for `1s * retryCount` before returning.
+ */
+export async function defaultOnReconnect(
+  err: StatusObject,
+  retryCount: number
+): Promise<OnReconnectResult> {
+  if (err.code != 13) {
+    return {
+      reconnect: false,
     }
   }
+
+  await new Promise((resolve) => setTimeout(resolve, retryCount * 1000))
+  return {
+    reconnect: retryCount < 5,
+  }
 }

package/src/cursor.ts

@@ -0,0 +1,39 @@
+import Long from 'long'
+import { ICursor } from './proto/v1alpha2'
+
+export const Cursor = {
+  /**
+   * Creates a new cursor with only the `orderKey` set.
+   *
+   * Notice that this cursor does not uniquely identify a message in the stream
+   * and may result in missing information.
+   */
+  createWithOrderKey: (order: string | number | Long): ICursor => {
+    return {
+      orderKey: Long.fromValue(order),
+      uniqueKey: new Uint8Array(),
+    }
+  },
+
+  /**
+   * Creates a new cursor with both order and unique keys.
+   *
+   * This cursor uniquely identifies a message in the stream, even if it has
+   * been invalidated.
+   */
+  create: (order: string | number | Long, unique: Uint8Array): ICursor => {
+    return {
+      orderKey: Long.fromValue(order),
+      uniqueKey: unique,
+    }
+  },
+
+  /**
+   * Returns the cursor string representation.
+   */
+  toString: (cursor?: ICursor | null): string | undefined => {
+    if (!cursor) return
+    let hash = Buffer.from(cursor.uniqueKey).toString('hex')
+    return `${cursor.orderKey.toString()}/0x${hash}`
+  },
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './proto'
 export * from './client'
 export * from './request'
+export * from './cursor'

package/src/proto/apibara/node/v1alpha2/Data.ts

@@ -7,10 +7,12 @@ export interface Data {
   'endCursor'?: (_apibara_node_v1alpha2_Cursor | null);
   'finality'?: (_apibara_node_v1alpha2_DataFinality | keyof typeof _apibara_node_v1alpha2_DataFinality);
   'data'?: (Buffer | Uint8Array | string)[];
+  'cursor'?: (_apibara_node_v1alpha2_Cursor | null);
 }
 
 export interface Data__Output {
   'endCursor': (_apibara_node_v1alpha2_Cursor__Output | null);
   'finality': (keyof typeof _apibara_node_v1alpha2_DataFinality);
   'data': (Uint8Array)[];
+  'cursor': (_apibara_node_v1alpha2_Cursor__Output | null);
 }

package/src/proto/apibara/node/v1alpha2/StreamDataResponse.ts

@@ -7,16 +7,16 @@ import type { Long } from '@grpc/proto-loader';
 
 export interface StreamDataResponse {
   'streamId'?: (number | string | Long);
-  'Invalidate'?: (_apibara_node_v1alpha2_Invalidate | null);
+  'invalidate'?: (_apibara_node_v1alpha2_Invalidate | null);
   'data'?: (_apibara_node_v1alpha2_Data | null);
   'heartbeat'?: (_apibara_node_v1alpha2_Heartbeat | null);
-  'message'?: "Invalidate"|"data"|"heartbeat";
+  'message'?: "invalidate"|"data"|"heartbeat";
 }
 
 export interface StreamDataResponse__Output {
   'streamId': (Long);
-  'Invalidate'?: (_apibara_node_v1alpha2_Invalidate__Output | null);
+  'invalidate'?: (_apibara_node_v1alpha2_Invalidate__Output | null);
   'data'?: (_apibara_node_v1alpha2_Data__Output | null);
   'heartbeat'?: (_apibara_node_v1alpha2_Heartbeat__Output | null);
-  'message': "Invalidate"|"data"|"heartbeat";
+  'message': "invalidate"|"data"|"heartbeat";
 }

package/src/proto/stream.proto

@@ -29,7 +29,7 @@ message StreamDataResponse {
   // The stream id.
   uint64 stream_id = 1;
   oneof message {
-    Invalidate Invalidate = 2;
+    Invalidate invalidate = 2;
     Data data = 3;
     Heartbeat heartbeat = 4;
   }
@@ -68,6 +68,8 @@ message Data {
   DataFinality finality = 2;
   // The stream data.
   repeated bytes data = 3;
+  // Cursor used to produced the batch.
+  Cursor cursor = 4;
 }
 
 // Sent to clients to check if stream is still connected.