@lokalise/fastify-bullboard-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2023 Lokalise
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,41 @@
+# bull-board
+
+Bull-board is a dashboard which provided a UI built on top of BullMQ or BullMQ Pro to help you visualize
+your queues and their jobs.
+It gives you the possibility of visualizing what's happening with each job in your queues, their status and some actions
+that will enable you to get the job done.
+
+Internally, we are using an open source library, [bull-board](https://github.com/felixmosh/bull-board), which provides
+all the functionalities we mentioned above.
+
+## Adding bullboard to your app
+
+Register a bullboard plugin in your fastify app:
+
+```ts
+import fastify from 'fastify'
+import { bullBoard, basicAuth } from '@lokalise/fastify-bullboard-plugin'
+import { Queue } from 'bullmq'
+
+const app = fastify()
+
+await app.register(basicAuth, {
+    config: {
+        isEnabled: true,
+        username: 'username',
+        password: 'pass',
+    },
+    enableList: new Set(['/bull']),
+})
+
+await app.register(bullBoard, {
+  queueConstructor: Queue, // can be QueuePro if bullmq-pro is used
+  redisInstances: [
+      new Redis({
+          // some redis config
+      }),
+  ],
+  basePath: '/bull',
+  refreshIntervalInSeconds: config.bullBoard.refreshIntervalInSeconds,
+})
+```

package/package.json

@@ -0,0 +1,76 @@
+{
+    "name": "@lokalise/fastify-bullboard-plugin",
+    "version": "1.0.0",
+    "type": "module",
+    "engines": {
+        "node": ">=20.13.0"
+    },
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": "./dist/index.js",
+        "./package.json": "./package.json"
+    },
+    "scripts": {
+        "build": "rimraf dist && tsc --project tsconfig.build.json",
+        "lint": "biome check . && tsc",
+        "lint:fix": "biome check --write",
+        "test": "vitest run",
+        "test:ci": "vitest run --coverage",
+        "prepublishOnly": "npm run build",
+        "package-version": "echo $npm_package_version",
+        "postversion": "biome check --write package.json"
+    },
+    "dependencies": {
+        "@bull-board/api": "^6.11.0",
+        "@bull-board/fastify": "^6.11.0",
+        "@fastify/auth": "^5.0.2",
+        "@fastify/basic-auth": "^6.2.0"
+    },
+    "peerDependencies": {
+        "@lokalise/background-jobs-common": ">=12.6.0"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.0.6",
+        "@lokalise/background-jobs-common": "^12.6.0",
+        "@lokalise/biome-config": "^3.0.0",
+        "@types/node": "^24.0.12",
+        "@vitest/coverage-v8": "^3.2.4",
+        "@fastify/awilix": "^8.0.0",
+        "@fastify/schedule": "^6.0.0",
+        "@lokalise/fastify-extras": "^27.4.0",
+        "@lokalise/node-core": "^14.1.0",
+        "awilix": "^12.0.5",
+        "awilix-manager": "^6.1.0",
+        "bullmq": "5.56.9",
+        "cross-env": "^10.0.0",
+        "fastify": "^5.4.0",
+        "fastify-graceful-shutdown": "^4.0.1",
+        "fastify-metrics": "^12.1.0",
+        "fastify-plugin": "^5.0.1",
+        "ioredis": "^5.6.1",
+        "pino": "^9.7.0",
+        "toad-scheduler": "^3.0.1",
+        "ts-deepmerge": "^7.0.3",
+        "pino-pretty": "^13.0.0",
+        "typescript": "5.8.3",
+        "vitest": "^3.2.4"
+    },
+    "keywords": [
+        "fastify",
+        "bullboard",
+        "bull",
+        "dashboard",
+        "plugin"
+    ],
+    "homepage": "https://github.com/lokalise/shared-ts-libs",
+    "repository": {
+        "type": "git",
+        "url": "git://github.com/lokalise/shared-ts-libs.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/basicAuth.spec.ts

@@ -0,0 +1,79 @@
+import fastify, { type FastifyInstance } from 'fastify'
+import { beforeAll, describe, expect } from 'vitest'
+
+import { basicAuth } from './basicAuth.js'
+
+const skippedEndpoint = '/skipAuth'
+const enabledEndpoint = '/'
+
+async function initApp(authEnabled: boolean) {
+  const app = fastify()
+  await app.register(basicAuth, {
+    config: { isEnabled: authEnabled, username: 'test', password: 'test' },
+    enableList: new Set([enabledEndpoint]),
+  })
+
+  app.route({
+    method: 'GET',
+    url: '/',
+    handler: (_req, reply) => {
+      return reply.status(200).send({ hello: 'world' })
+    },
+  })
+
+  app.route({
+    method: 'GET',
+    url: skippedEndpoint,
+    handler: (_req, reply) => {
+      return reply.status(200).send({ hello: 'my friend' })
+    },
+  })
+
+  await app.ready()
+  return app
+}
+
+describe('basicAuth', () => {
+  let app: FastifyInstance
+
+  afterAll(async () => {
+    await app.close()
+  })
+
+  const performRequest = async (path: string) => app.inject().get(path).end()
+
+  describe('auth enabled', () => {
+    beforeAll(async () => {
+      app = await initApp(true)
+    })
+
+    it('returns 401 on not skipped endpoints', async () => {
+      const response = await performRequest('/')
+      expect(response.statusCode).toBe(401)
+    })
+
+    it('works on skipped endpoints', async () => {
+      const response = await performRequest(skippedEndpoint)
+      expect(response.statusCode).toBe(200)
+      expect(response.json()).toEqual({ hello: 'my friend' })
+    })
+  })
+
+  describe('auth disabled', () => {
+    beforeAll(async () => {
+      app = await initApp(false)
+    })
+
+    it('works on not skipped endpoints', async () => {
+      const response = await performRequest('/')
+      expect(response.statusCode).toBe(200)
+      expect(response.json()).toEqual({ hello: 'world' })
+    })
+
+    it('works on skipped endpoints', async () => {
+      const response = await performRequest(skippedEndpoint)
+      expect(response.statusCode).toBe(200)
+      expect(response.json()).toEqual({ hello: 'my friend' })
+    })
+  })
+})

package/src/basicAuth.ts

@@ -0,0 +1,67 @@
+import type { FastifyAuthFunction } from '@fastify/auth'
+import fastifyAuth from '@fastify/auth'
+import fastifyBasicAuth from '@fastify/basic-auth'
+import { AuthFailedError } from '@lokalise/node-core'
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import fp from 'fastify-plugin'
+
+export type AuthConfig = {
+  isEnabled: boolean
+  username: string
+  password: string
+}
+
+type BasicAuthOptions = {
+  config: AuthConfig
+  enableList: Set<string>
+}
+
+function validate(config: AuthConfig) {
+  return (
+    username: string,
+    password: string,
+    _req: FastifyRequest,
+    _reply: FastifyReply,
+    done: (err?: Error) => void,
+  ) => {
+    if (username === config.username && password === config.password) {
+      done()
+    } else {
+      done(new AuthFailedError())
+    }
+  }
+}
+
+function enableListAuthHandler(enableList: Set<string>): FastifyAuthFunction {
+  return (req, _res, done) => {
+    if (req.routeOptions.url && !enableList.has(req.routeOptions.url)) {
+      return done()
+    }
+
+    return done(new AuthFailedError())
+  }
+}
+
+async function plugin(fastify: FastifyInstance, pluginOptions: BasicAuthOptions): Promise<void> {
+  if (!pluginOptions.config.isEnabled) {
+    return
+  }
+
+  await fastify.register(fastifyAuth)
+  await fastify.register(fastifyBasicAuth, {
+    validate: validate(pluginOptions.config),
+    authenticate: true,
+  })
+
+  fastify.after(() => {
+    fastify.addHook(
+      'onRequest',
+      fastify.auth([enableListAuthHandler(pluginOptions.enableList), fastify.basicAuth]),
+    )
+  })
+}
+
+export const basicAuth = fp<BasicAuthOptions>(plugin, {
+  fastify: '>=4.0.0',
+  name: 'basic-auth',
+})

package/src/bullBoard.spec.ts

@@ -0,0 +1,67 @@
+import { Queue } from 'bullmq'
+import fastify, { type FastifyInstance } from 'fastify'
+import { beforeAll, expect } from 'vitest'
+import { type BullBoardOptions, bullBoard, type QueueProConstructor } from './bullBoard.js'
+
+const QueuePro: QueueProConstructor = Queue as QueueProConstructor
+
+async function initApp(options: BullBoardOptions) {
+  const app = fastify()
+
+  await app.register(bullBoard, options)
+
+  await app.ready()
+  return app
+}
+
+describe('bull board', () => {
+  let app: FastifyInstance
+
+  afterAll(async () => {
+    await app.close()
+  })
+
+  describe('refresh disabled', () => {
+    beforeAll(async () => {
+      app = await initApp({
+        queueConstructor: QueuePro,
+        redisInstances: [],
+        basePath: '/test-disabled',
+      })
+    })
+
+    it('works', async () => {
+      const response = await app.inject().get('/test-disabled').end()
+
+      expect(response.statusCode).toBe(200)
+      expect(response.body.toLowerCase()).includes('<!doctype html>')
+      expect(response.body.toLowerCase()).includes('<title>bull dashboard</title>')
+
+      expect(app.scheduler).toBeUndefined()
+    })
+  })
+
+  describe('refresh enabled', () => {
+    beforeAll(async () => {
+      app = await initApp({
+        queueConstructor: Queue,
+        redisInstances: [],
+        basePath: '/test-enabled',
+        refreshIntervalInSeconds: 1,
+      })
+    })
+
+    it('works', async () => {
+      const response = await app.inject().get('/test-enabled').end()
+
+      expect(response.statusCode).toBe(200)
+      expect(response.body.toLowerCase()).includes('<!doctype html>')
+      expect(response.body.toLowerCase()).includes('<title>bull dashboard</title>')
+
+      expect(app.scheduler).toBeDefined()
+      const jobs = app.scheduler.getAllJobs()
+      expect(jobs).toHaveLength(1)
+      expect(jobs[0]!.id).toBe('bull-board-queues-update')
+    })
+  })
+})

package/src/bullBoard.ts

@@ -0,0 +1,112 @@
+import { constants as httpConstants } from 'node:http2'
+import { createBullBoard } from '@bull-board/api'
+// @ts-ignore
+import { BullMQAdapter } from '@bull-board/api/bullMQAdapter.js'
+import { FastifyAdapter } from '@bull-board/fastify'
+import fastifySchedule from '@fastify/schedule'
+import {
+  backgroundJobProcessorGetActiveQueueIds,
+  QUEUE_GROUP_DELIMITER,
+} from '@lokalise/background-jobs-common'
+import { resolveGlobalErrorLogObject } from '@lokalise/node-core'
+import type { Queue, QueueOptions, RedisConnection } from 'bullmq'
+import type { FastifyInstance } from 'fastify'
+import fp from 'fastify-plugin'
+import type { Redis } from 'ioredis'
+import { AsyncTask, SimpleIntervalJob } from 'toad-scheduler'
+
+export type BullBoardOptions = {
+  queueConstructor: QueueProConstructor | QueueConstructor
+  redisInstances: Redis[]
+  basePath: string
+  refreshIntervalInSeconds?: number
+}
+
+function containStatusCode(error: Error): error is Error & { statusCode: number } {
+  return Object.hasOwn(error, 'statusCode')
+}
+
+const bullBoardErrorHandler = (error: Error) => {
+  const status = containStatusCode(error)
+    ? error.statusCode
+    : httpConstants.HTTP_STATUS_INTERNAL_SERVER_ERROR
+  return {
+    status: status,
+    body: { message: error.message, details: error.stack },
+  }
+}
+
+export interface QueueProConstructor {
+  new (name: string, opts?: Record<string, unknown>): Queue
+}
+
+export interface QueueConstructor {
+  new (name: string, opts?: QueueOptions, Connection?: typeof RedisConnection): Queue
+}
+
+async function getCurrentQueues(
+  redisInstances: Redis[],
+  queueConstructor: QueueProConstructor | QueueConstructor,
+): Promise<BullMQAdapter[]> {
+  const queueIds = await Promise.all(
+    redisInstances.map((redis) => backgroundJobProcessorGetActiveQueueIds(redis)),
+  )
+
+  return queueIds
+    .flatMap((ids, index) =>
+      // biome-ignore lint/style/noNonNullAssertion: Should exist
+      ids.map((id) => new queueConstructor(id, { connection: redisInstances[index]! })),
+    )
+    .map((queue) => new BullMQAdapter(queue, { delimiter: QUEUE_GROUP_DELIMITER }))
+}
+
+async function scheduleUpdates(
+  fastify: FastifyInstance,
+  bullBoard: ReturnType<typeof createBullBoard>,
+  pluginOptions: BullBoardOptions,
+) {
+  const { refreshIntervalInSeconds, redisInstances, queueConstructor } = pluginOptions
+
+  if (!refreshIntervalInSeconds || refreshIntervalInSeconds <= 0) return
+
+  const refreshTask = new AsyncTask(
+    'Bull-board - update queues',
+    async () => {
+      fastify.log.debug({ refreshIntervalInSeconds }, 'Bull-dashboard -> updating queues')
+      bullBoard.replaceQueues(await getCurrentQueues(redisInstances, queueConstructor))
+    },
+    (e) => fastify.log.error(resolveGlobalErrorLogObject(e)),
+  )
+
+  await fastify.register(fastifySchedule)
+  fastify.scheduler.addSimpleIntervalJob(
+    new SimpleIntervalJob({ seconds: refreshIntervalInSeconds }, refreshTask, {
+      id: 'bull-board-queues-update',
+      preventOverrun: true,
+    }),
+  )
+}
+
+const plugin = async (fastify: FastifyInstance, pluginOptions: BullBoardOptions) => {
+  const { basePath, redisInstances, queueConstructor } = pluginOptions
+
+  const serverAdapter = new FastifyAdapter()
+  const bullBoard = createBullBoard({
+    queues: await getCurrentQueues(redisInstances, queueConstructor),
+    serverAdapter,
+  })
+  // biome-ignore lint/suspicious/noExplicitAny: bull-board is not exporting this type
+  serverAdapter.setErrorHandler(bullBoardErrorHandler as any)
+  serverAdapter.setBasePath(basePath)
+
+  await fastify.register(serverAdapter.registerPlugin(), {
+    prefix: basePath,
+  })
+
+  await scheduleUpdates(fastify, bullBoard, pluginOptions)
+}
+
+export const bullBoard = fp<BullBoardOptions>(plugin, {
+  fastify: '>=4.0.0',
+  name: 'bull-board',
+})

package/src/errorReporterPlugin.spec.ts

@@ -0,0 +1,127 @@
+import { type ErrorReporter, InternalError, PublicNonRecoverableError } from '@lokalise/node-core'
+import fastify, { type FastifyInstance, type RouteHandlerMethod } from 'fastify'
+import { pino } from 'pino'
+import { afterAll, describe, expect, it, type MockInstance, vi } from 'vitest'
+
+import { FakeErrorReporter } from '../test/FakeErrorReporter.js'
+import { errorReporterPlugin } from './errorReporterPlugin.js'
+
+async function initApp(routeHandler: RouteHandlerMethod, errorReporter: ErrorReporter) {
+  const app = fastify({
+    logger: true,
+  })
+  await app.register(errorReporterPlugin, { errorReporter })
+
+  app.route({
+    method: 'GET',
+    url: '/',
+    handler: routeHandler,
+  })
+
+  await app.ready()
+  return app
+}
+
+describe('errorHandlerPlugin', () => {
+  let app: FastifyInstance
+
+  afterAll(async () => {
+    await app.close()
+  })
+
+  const performRequest = async () => app.inject().get('/').end()
+
+  it('generic errors are reported', async () => {
+    const fakeErrorReporter = new FakeErrorReporter()
+    const error = new Error('Generic error')
+    let logSpy: MockInstance | undefined
+    app = await initApp((req) => {
+      logSpy = vi.spyOn(req.log, 'error')
+      throw error
+    }, fakeErrorReporter)
+
+    await performRequest()
+
+    expect(fakeErrorReporter.calls).length(1)
+    expect(fakeErrorReporter.calls[0]).toEqual({ error })
+    expect(logSpy).toHaveBeenCalledWith({
+      message: error.message,
+      error: pino.stdSerializers.err({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }),
+    })
+  })
+
+  it('internal errors are reported', async () => {
+    const fakeErrorReporter = new FakeErrorReporter()
+    const error = new InternalError({
+      message: 'Internal error',
+      errorCode: 'INTERNAL_ERROR',
+    })
+    let logSpy: MockInstance | undefined
+    app = await initApp((req) => {
+      logSpy = vi.spyOn(req.log, 'error')
+      throw error
+    }, fakeErrorReporter)
+
+    await performRequest()
+
+    expect(fakeErrorReporter.calls).length(1)
+    expect(fakeErrorReporter.calls[0]).toEqual({ error })
+    expect(logSpy).toHaveBeenCalledWith({
+      message: error.message,
+      code: error.errorCode,
+      details: error.details ? JSON.stringify(error.details) : undefined,
+      error: pino.stdSerializers.err({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }),
+    })
+  })
+
+  it('5xx errors are reported', async () => {
+    const fakeErrorReporter = new FakeErrorReporter()
+    const error = new PublicNonRecoverableError({
+      httpStatusCode: 500,
+      message: 'Internal error',
+      errorCode: 'INTERNAL_ERROR',
+    })
+    let logSpy: MockInstance | undefined
+    app = await initApp((req) => {
+      logSpy = vi.spyOn(req.log, 'error')
+      throw error
+    }, fakeErrorReporter)
+
+    await performRequest()
+
+    expect(fakeErrorReporter.calls).length(1)
+    expect(fakeErrorReporter.calls[0]).toEqual({ error })
+    expect(logSpy).toHaveBeenCalledWith({
+      message: error.message,
+      error: pino.stdSerializers.err({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }),
+    })
+  })
+
+  it('4xx erros are ignored', async () => {
+    const fakeErrorReporter = new FakeErrorReporter()
+    const error = new PublicNonRecoverableError({
+      httpStatusCode: 400,
+      message: 'test',
+      errorCode: 'TEST',
+    })
+    app = await initApp(() => {
+      throw error
+    }, fakeErrorReporter)
+
+    await performRequest()
+
+    expect(fakeErrorReporter.calls).length(0)
+  })
+})

package/src/errorReporterPlugin.ts

@@ -0,0 +1,73 @@
+import { constants as httpConstants } from 'node:http2'
+
+import type { ErrorReporter } from '@lokalise/node-core'
+import {
+  isError,
+  isInternalError,
+  isObject,
+  isPublicNonRecoverableError,
+} from '@lokalise/node-core'
+import type { FastifyInstance } from 'fastify'
+import fp from 'fastify-plugin'
+import { pino } from 'pino'
+
+export type ErrorReporterOptions = {
+  errorReporter: ErrorReporter
+}
+
+function resolveLogObject(error: unknown): Record<string, unknown> {
+  if (isInternalError(error)) {
+    return {
+      message: error.message,
+      code: error.errorCode,
+      details: error.details ? JSON.stringify(error.details) : undefined,
+      error: pino.stdSerializers.err({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }),
+    }
+  }
+  if (isError(error)) {
+    return {
+      message: error.message,
+      error: pino.stdSerializers.err({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }),
+    }
+  }
+
+  return {
+    message: isObject(error) ? error.message : JSON.stringify(error),
+    error,
+  }
+}
+
+function plugin(
+  fastify: FastifyInstance,
+  pluginOptions: ErrorReporterOptions,
+  next: (err?: Error) => void,
+) {
+  fastify.addHook('onError', (request, _reply, error, done) => {
+    let statusCode = error.statusCode ?? httpConstants.HTTP_STATUS_INTERNAL_SERVER_ERROR
+    if (isPublicNonRecoverableError(error)) {
+      statusCode = error.httpStatusCode
+    }
+
+    if (statusCode >= httpConstants.HTTP_STATUS_INTERNAL_SERVER_ERROR) {
+      request.log.error(resolveLogObject(error))
+      pluginOptions.errorReporter.report({ error })
+    }
+
+    done()
+  })
+
+  next()
+}
+
+export const errorReporterPlugin = fp<ErrorReporterOptions>(plugin, {
+  fastify: '>=4.0.0',
+  name: 'error-reporter',
+})

package/src/index.ts

@@ -0,0 +1,3 @@
+export { type AuthConfig, basicAuth } from './basicAuth.js'
+export { type BullBoardOptions, bullBoard, type QueueProConstructor } from './bullBoard.js'
+export { type ErrorReporterOptions, errorReporterPlugin } from './errorReporterPlugin.js'

package/test/FakeErrorReporter.ts

@@ -0,0 +1,18 @@
+import type { ErrorReport } from '@lokalise/fastify-extras'
+import type { ErrorReporter } from '@lokalise/node-core'
+
+export class FakeErrorReporter implements ErrorReporter {
+  private _calls: ErrorReport[] = []
+
+  report(errorReport: ErrorReport): void {
+    this._calls.push(errorReport)
+  }
+
+  clean(): void {
+    this._calls = []
+  }
+
+  get calls(): ErrorReport[] {
+    return this._calls
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,5 @@
+{
+    "extends": ["./tsconfig.json", "@lokalise/tsconfig/build-public-lib"],
+    "include": ["src/**/*"],
+    "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+    "extends": "@lokalise/tsconfig/tsc",
+    "include": ["src/**/*", "vitest.config.ts"],
+    "compilerOptions": {
+        "types": ["vitest/globals"]
+    }
+}

package/vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config'
+
+// biome-ignore lint/style/noDefaultExport: vite expects default export
+export default defineConfig({
+  test: {
+    globals: true,
+    watch: false,
+    restoreMocks: true,
+    pool: 'threads',
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.ts'],
+      exclude: ['src/index.ts'],
+      thresholds: {
+        lines: 84,
+        functions: 80,
+        branches: 86,
+        statements: 84,
+      },
+    },
+  },
+})