@atproto/sync 0.1.0

package/dist/runner/memory-runner.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRunner = exports.ConsecutiveList = void 0;
+const p_queue_1 = __importDefault(require("p-queue"));
+const consecutive_list_1 = require("./consecutive-list");
+Object.defineProperty(exports, "ConsecutiveList", { enumerable: true, get: function () { return consecutive_list_1.ConsecutiveList; } });
+// A queue with arbitrarily many partitions, each processing work sequentially.
+// Partitions are created lazily and taken out of memory when they go idle.
+class MemoryRunner {
+    constructor(opts = {}) {
+        Object.defineProperty(this, "opts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: opts
+        });
+        Object.defineProperty(this, "consecutive", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new consecutive_list_1.ConsecutiveList()
+        });
+        Object.defineProperty(this, "mainQueue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "partitions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "cursor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.mainQueue = new p_queue_1.default({ concurrency: opts.concurrency ?? Infinity });
+        this.cursor = opts.startCursor;
+    }
+    getCursor() {
+        return this.cursor;
+    }
+    async addTask(partitionId, task) {
+        if (this.mainQueue.isPaused)
+            return;
+        return this.mainQueue.add(() => {
+            return this.getPartition(partitionId).add(task);
+        });
+    }
+    getPartition(partitionId) {
+        let partition = this.partitions.get(partitionId);
+        if (!partition) {
+            partition = new p_queue_1.default({ concurrency: 1 });
+            partition.once('idle', () => this.partitions.delete(partitionId));
+            this.partitions.set(partitionId, partition);
+        }
+        return partition;
+    }
+    async trackEvent(did, seq, handler) {
+        if (this.mainQueue.isPaused)
+            return;
+        const item = this.consecutive.push(seq);
+        await this.addTask(did, async () => {
+            await handler();
+            const latest = item.complete().at(-1);
+            if (latest !== undefined) {
+                this.cursor = latest;
+                if (this.opts.setCursor) {
+                    await this.opts.setCursor(this.cursor);
+                }
+            }
+        });
+    }
+    async processAll() {
+        await this.mainQueue.onIdle();
+    }
+    async destroy() {
+        this.mainQueue.pause();
+        this.mainQueue.clear();
+        this.partitions.forEach((p) => p.clear());
+        await this.mainQueue.onIdle();
+    }
+}
+exports.MemoryRunner = MemoryRunner;
+//# sourceMappingURL=memory-runner.js.map

package/dist/runner/memory-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-runner.js","sourceRoot":"","sources":["../../src/runner/memory-runner.ts"],"names":[],"mappings":";;;;;;AAAA,sDAA4B;AAC5B,yDAAoD;AAG3C,gGAHA,kCAAe,OAGA;AAQxB,+EAA+E;AAC/E,2EAA2E;AAC3E,MAAa,YAAY;IAMvB,YAAmB,OAA4B,EAAE;QAArC;;;;mBAAO,IAAI;WAA0B;QALjD;;;;mBAAc,IAAI,kCAAe,EAAU;WAAA;QAC3C;;;;;WAAiB;QACjB;;;;mBAAa,IAAI,GAAG,EAAkB;WAAA;QACtC;;;;;WAA0B;QAGxB,IAAI,CAAC,SAAS,GAAG,IAAI,iBAAM,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,QAAQ,EAAE,CAAC,CAAA;QAC1E,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,CAAA;IAChC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAA;IACpB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,IAAyB;QAC1D,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ;YAAE,OAAM;QACnC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE;YAC7B,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACjD,CAAC,CAAC,CAAA;IACJ,CAAC;IAEO,YAAY,CAAC,WAAmB;QACtC,IAAI,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QAChD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,SAAS,GAAG,IAAI,iBAAM,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAA;YAC1C,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAA;YACjE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;QAC7C,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAAW,EAAE,GAAW,EAAE,OAA4B;QACrE,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ;YAAE,OAAM;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACvC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE;YACjC,MAAM,OAAO,EAAE,CAAA;YACf,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;YACrC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;gBACpB,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;oBACxB,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;gBACxC,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAA;IAC/B,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;QACtB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;QACtB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;QACzC,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAA;IAC/B,CAAC;CACF;AAzDD,oCAyDC"}

package/dist/runner/types.d.ts

@@ -0,0 +1,5 @@
+export interface EventRunner {
+    getCursor(): Awaited<number | undefined>;
+    trackEvent(did: string, seq: number, hanlder: () => Promise<void>): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runner/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runner/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACxC,UAAU,CACR,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAA;CACjB"}

package/dist/runner/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/runner/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/runner/types.ts"],"names":[],"mappings":""}

package/dist/util.d.ts

@@ -0,0 +1,6 @@
+import { RepoEvent } from './firehose/lexicons';
+export declare const didAndSeqForEvt: (evt: RepoEvent) => {
+    did: string;
+    seq: number;
+} | undefined;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEhF,eAAO,MAAM,eAAe,QACrB,SAAS,KACb;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAKjC,CAAA"}

package/dist/util.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.didAndSeqForEvt = void 0;
+const lexicons_1 = require("./firehose/lexicons");
+const didAndSeqForEvt = (evt) => {
+    if ((0, lexicons_1.isCommit)(evt))
+        return { seq: evt.seq, did: evt.repo };
+    else if ((0, lexicons_1.isAccount)(evt) || (0, lexicons_1.isIdentity)(evt))
+        return { seq: evt.seq, did: evt.did };
+    return undefined;
+};
+exports.didAndSeqForEvt = didAndSeqForEvt;
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":";;;AAAA,kDAAgF;AAEzE,MAAM,eAAe,GAAG,CAC7B,GAAc,EAC4B,EAAE;IAC5C,IAAI,IAAA,mBAAQ,EAAC,GAAG,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,CAAA;SACpD,IAAI,IAAA,oBAAS,EAAC,GAAG,CAAC,IAAI,IAAA,qBAAU,EAAC,GAAG,CAAC;QACxC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAA;IACvC,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA;AAPY,QAAA,eAAe,mBAO3B"}

package/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  displayName: 'Sync',
+  transform: { '^.+\\.(t|j)s$': '@swc/jest' },
+  transformIgnorePatterns: [`<rootDir>/node_modules/(?!get-port)`],
+  testTimeout: 60000,
+  setupFiles: ['<rootDir>/../../jest.setup.ts'],
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@atproto/sync",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "atproto sync library",
+  "keywords": [
+    "atproto",
+    "sync",
+    "firehose",
+    "relay"
+  ],
+  "homepage": "https://atproto.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluesky-social/atproto",
+    "directory": "packages/sync"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "multiformats": "^9.9.0",
+    "p-queue": "^6.6.2",
+    "@atproto/common": "^0.4.1",
+    "@atproto/identity": "^0.4.1",
+    "@atproto/lexicon": "^0.4.1",
+    "@atproto/repo": "^0.5.0",
+    "@atproto/syntax": "^0.3.0",
+    "@atproto/xrpc-server": "^0.6.3"
+  },
+  "devDependencies": {
+    "jest": "^28.1.2"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "test": "../dev-infra/with-test-redis-and-db.sh jest"
+  }
+}

package/src/events.ts

@@ -0,0 +1,61 @@
+import { DidDocument } from '@atproto/identity'
+import type { RepoRecord } from '@atproto/lexicon'
+import { BlockMap } from '@atproto/repo'
+import { AtUri } from '@atproto/syntax'
+import type { CID } from 'multiformats/cid'
+
+export type Event = CommitEvt | IdentityEvt | AccountEvt
+
+export type CommitMeta = {
+  seq: number
+  time: string
+  commit: CID
+  blocks: BlockMap
+  rev: string
+  uri: AtUri
+  did: string
+  collection: string
+  rkey: string
+}
+
+export type CommitEvt = Create | Update | Delete
+
+export type Create = CommitMeta & {
+  event: 'create'
+  record: RepoRecord
+  cid: CID
+}
+
+export type Update = CommitMeta & {
+  event: 'update'
+  record: RepoRecord
+  cid: CID
+}
+
+export type Delete = CommitMeta & {
+  event: 'delete'
+}
+
+export type IdentityEvt = {
+  seq: number
+  time: string
+  event: 'identity'
+  did: string
+  handle?: string
+  didDocument?: DidDocument
+}
+
+export type AccountEvt = {
+  seq: number
+  time: string
+  event: 'account'
+  did: string
+  active: boolean
+  status?: AccountStatus
+}
+
+export type AccountStatus =
+  | 'takendown'
+  | 'suspended'
+  | 'deleted'
+  | 'deactivated'

package/src/firehose/index.ts

@@ -0,0 +1,357 @@
+import { createDeferrable, Deferrable, wait } from '@atproto/common'
+import {
+  IdResolver,
+  parseToAtprotoDocument,
+  DidDocument,
+} from '@atproto/identity'
+import {
+  cborToLexRecord,
+  formatDataKey,
+  parseDataKey,
+  readCar,
+  RepoVerificationError,
+  verifyProofs,
+} from '@atproto/repo'
+import { AtUri } from '@atproto/syntax'
+import { Subscription } from '@atproto/xrpc-server'
+import {
+  type Account,
+  type Commit,
+  type Identity,
+  type RepoEvent,
+  RepoOp,
+  isAccount,
+  isCommit,
+  isIdentity,
+  isValidRepoEvent,
+} from './lexicons'
+import {
+  Event,
+  CommitMeta,
+  CommitEvt,
+  AccountEvt,
+  AccountStatus,
+  IdentityEvt,
+} from '../events'
+import { CID } from 'multiformats/cid'
+import { EventRunner } from '../runner'
+import { didAndSeqForEvt } from '../util'
+
+export type FirehoseOptions = {
+  idResolver: IdResolver
+
+  handleEvent: (evt: Event) => Awaited<void>
+  onError: (err: Error) => void
+  getCursor?: () => Awaited<number | undefined>
+
+  runner?: EventRunner // should only set getCursor *or* runner
+
+  service?: string
+  subscriptionReconnectDelay?: number
+
+  unauthenticatedCommits?: boolean
+  unauthenticatedHandles?: boolean
+
+  filterCollections?: string[]
+  excludeIdentity?: boolean
+  excludeAccount?: boolean
+  excludeCommit?: boolean
+}
+
+export class Firehose {
+  private sub: Subscription<RepoEvent>
+  private abortController: AbortController
+  private destoryDefer: Deferrable
+
+  constructor(public opts: FirehoseOptions) {
+    this.destoryDefer = createDeferrable()
+    this.abortController = new AbortController()
+    if (this.opts.getCursor && this.opts.runner) {
+      throw new Error('Must set only `getCursor` or `runner`')
+    }
+    this.sub = new Subscription({
+      service: opts.service ?? 'wss://bsky.network',
+      method: 'com.atproto.sync.subscribeRepos',
+      signal: this.abortController.signal,
+      getParams: async () => {
+        const getCursorFn = () =>
+          this.opts.runner?.getCursor() ?? this.opts.getCursor
+        if (!getCursorFn) {
+          return undefined
+        }
+        const cursor = await getCursorFn()
+        return { cursor }
+      },
+      validate: (value: unknown) => {
+        try {
+          return isValidRepoEvent(value)
+        } catch (err) {
+          this.opts.onError(new FirehoseValidationError(err, value))
+        }
+      },
+    })
+  }
+
+  async start() {
+    try {
+      for await (const evt of this.sub) {
+        if (this.opts.runner) {
+          const parsed = didAndSeqForEvt(evt)
+          if (!parsed) {
+            continue
+          }
+          this.opts.runner.trackEvent(parsed.did, parsed.seq, async () => {
+            const parsed = await this.parseEvt(evt)
+            for (const write of parsed) {
+              try {
+                await this.opts.handleEvent(write)
+              } catch (err) {
+                this.opts.onError(new FirehoseHandlerError(err, write))
+              }
+            }
+          })
+        } else {
+          await this.processEvt(evt)
+        }
+      }
+    } catch (err) {
+      if (err && err['name'] === 'AbortError') {
+        this.destoryDefer.resolve()
+        return
+      }
+      this.opts.onError(new FirehoseSubscriptionError(err))
+      await wait(this.opts.subscriptionReconnectDelay ?? 3000)
+      return this.start()
+    }
+  }
+
+  private async parseEvt(evt: RepoEvent): Promise<Event[]> {
+    try {
+      if (isCommit(evt) && !this.opts.excludeCommit) {
+        return this.opts.unauthenticatedCommits
+          ? await parseCommitUnauthenticated(evt, this.opts.filterCollections)
+          : await parseCommitAuthenticated(
+              this.opts.idResolver,
+              evt,
+              this.opts.filterCollections,
+            )
+      } else if (isAccount(evt) && !this.opts.excludeAccount) {
+        const parsed = parseAccount(evt)
+        return parsed ? [parsed] : []
+      } else if (isIdentity(evt) && !this.opts.excludeIdentity) {
+        const parsed = await parseIdentity(
+          this.opts.idResolver,
+          evt,
+          this.opts.unauthenticatedHandles,
+        )
+        return parsed ? [parsed] : []
+      } else {
+        return []
+      }
+    } catch (err) {
+      this.opts.onError(new FirehoseParseError(err, evt))
+      return []
+    }
+  }
+
+  private async processEvt(evt: RepoEvent) {
+    const parsed = await this.parseEvt(evt)
+    for (const write of parsed) {
+      try {
+        await this.opts.handleEvent(write)
+      } catch (err) {
+        this.opts.onError(new FirehoseHandlerError(err, write))
+      }
+    }
+  }
+
+  async destroy(): Promise<void> {
+    this.abortController.abort()
+    await this.destoryDefer.complete
+  }
+}
+
+export const parseCommitAuthenticated = async (
+  idResolver: IdResolver,
+  evt: Commit,
+  filterCollections?: string[],
+  forceKeyRefresh = false,
+): Promise<CommitEvt[]> => {
+  const did = evt.repo
+  const key = await idResolver.did.resolveAtprotoKey(did, forceKeyRefresh)
+  const claims = maybeFilterOps(evt.ops, filterCollections).map((op) => {
+    const { collection, rkey } = parseDataKey(op.path)
+    return {
+      collection,
+      rkey,
+      cid: op.action === 'delete' ? null : op.cid,
+    }
+  })
+  const verifiedCids: Record<string, CID | null> = {}
+  try {
+    const results = await verifyProofs(evt.blocks, claims, did, key)
+    results.verified.forEach((op) => {
+      const path = formatDataKey(op.collection, op.rkey)
+      verifiedCids[path] = op.cid
+    })
+  } catch (err) {
+    if (err instanceof RepoVerificationError && !forceKeyRefresh) {
+      return parseCommitAuthenticated(idResolver, evt, filterCollections, true)
+    }
+    throw err
+  }
+  const verifiedOps: RepoOp[] = evt.ops.filter((op) => {
+    if (op.action === 'delete') {
+      return verifiedCids[op.path] === null
+    } else {
+      return op.cid !== null && op.cid.equals(verifiedCids[op.path])
+    }
+  })
+  return formatCommitOps(evt, verifiedOps)
+}
+
+export const parseCommitUnauthenticated = async (
+  evt: Commit,
+  filterCollections?: string[],
+): Promise<CommitEvt[]> => {
+  const ops = maybeFilterOps(evt.ops, filterCollections)
+  return formatCommitOps(evt, ops)
+}
+
+const maybeFilterOps = (
+  ops: RepoOp[],
+  filterCollections?: string[],
+): RepoOp[] => {
+  if (!filterCollections) return ops
+  return ops.filter((op) => {
+    const { collection } = parseDataKey(op.path)
+    return filterCollections.includes(collection)
+  })
+}
+
+const formatCommitOps = async (evt: Commit, ops: RepoOp[]) => {
+  const car = await readCar(evt.blocks)
+
+  const evts: CommitEvt[] = []
+
+  for (const op of ops) {
+    const uri = AtUri.make(evt.repo, op.path)
+
+    const meta: CommitMeta = {
+      seq: evt.seq,
+      time: evt.time,
+      commit: evt.commit,
+      blocks: car.blocks,
+      rev: evt.rev,
+      uri,
+      did: uri.host,
+      collection: uri.collection,
+      rkey: uri.rkey,
+    }
+
+    if (op.action === 'create' || op.action === 'update') {
+      if (!op.cid) continue
+      const recordBytes = car.blocks.get(op.cid)
+      if (!recordBytes) continue
+      const record = cborToLexRecord(recordBytes)
+      evts.push({
+        ...meta,
+        event: op.action as 'create' | 'update',
+        cid: op.cid,
+        record,
+      })
+    }
+
+    if (op.action === 'delete') {
+      evts.push({
+        ...meta,
+        event: 'delete',
+      })
+    }
+  }
+
+  return evts
+}
+
+export const parseIdentity = async (
+  idResolver: IdResolver,
+  evt: Identity,
+  unauthenticated = false,
+): Promise<IdentityEvt | null> => {
+  const res = await idResolver.did.resolve(evt.did)
+  const handle =
+    res && !unauthenticated
+      ? await verifyHandle(idResolver, evt.did, res)
+      : undefined
+
+  return {
+    event: 'identity',
+    seq: evt.seq,
+    time: evt.time,
+    did: evt.did,
+    handle,
+    didDocument: res ?? undefined,
+  }
+}
+
+const verifyHandle = async (
+  idResolver: IdResolver,
+  did: string,
+  didDoc: DidDocument,
+): Promise<string | undefined> => {
+  const { handle } = parseToAtprotoDocument(didDoc)
+  if (!handle) {
+    return undefined
+  }
+  const res = await idResolver.handle.resolve(handle)
+  return res === did ? handle : undefined
+}
+
+export const parseAccount = (evt: Account): AccountEvt | undefined => {
+  if (evt.status && !isValidStatus(evt.status)) return
+  return {
+    event: 'account',
+    seq: evt.seq,
+    time: evt.time,
+    did: evt.did,
+    active: evt.active,
+    status: evt.status as AccountStatus | undefined,
+  }
+}
+
+const isValidStatus = (str: string): str is AccountStatus => {
+  return ['takendown', 'suspended', 'deleted', 'deactivated'].includes(str)
+}
+
+export class FirehoseValidationError extends Error {
+  constructor(
+    err: unknown,
+    public value: unknown,
+  ) {
+    super('error in firehose event lexicon validation', { cause: err })
+  }
+}
+
+export class FirehoseParseError extends Error {
+  constructor(
+    err: unknown,
+    public event: RepoEvent,
+  ) {
+    super('error in parsing and authenticating firehose event', { cause: err })
+  }
+}
+
+export class FirehoseSubscriptionError extends Error {
+  constructor(err: unknown) {
+    super('error on firehose subscription', { cause: err })
+  }
+}
+
+export class FirehoseHandlerError extends Error {
+  constructor(
+    err: unknown,
+    public event: Event,
+  ) {
+    super('error in firehose event handler', { cause: err })
+  }
+}