fix tests

# Conflicts:
#	hooks/storage/badger/badger.go
#	server.go

.github/workflows/build.yml

@@ -0,0 +1,73 @@
+name: build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: 1.21
+      - name: Vet
+        run: go vet ./...
+      - name: Test
+        run: go test -race ./... && echo true
+
+  coverage:
+    name: Test with Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: '1.21'
+      - name: Check out code
+        uses: actions/checkout@v3
+      - name: Install dependencies
+        run: |
+          go mod download
+      - name: Run Unit tests
+        run: |
+          go test -race -covermode atomic -coverprofile=covprofile ./...
+      - name: Install goveralls
+        run: go install github.com/mattn/goveralls@latest
+      - name: Send coverage
+        env:
+          COVERALLS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: goveralls -coverprofile=covprofile -service=github
+
+  docker:
+    if: github.repository == 'mochi-mqtt/server' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: mochimqtt/server
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ endsWith(github.ref, 'main') }}
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -0,0 +1,5 @@
+cmd/mqtt
+.DS_Store
+*.db
+.idea
+vendor

.golangci.yml

@@ -0,0 +1,103 @@
+linters:
+  disable-all: false
+  fix: false # Fix found issues (if it's supported by the linter).
+  enable:
+    # - asasalint
+    # - asciicheck
+    # - bidichk
+    # - bodyclose
+    # - containedctx
+    # - contextcheck
+    #- cyclop
+    # - deadcode
+    - decorder
+    # - depguard
+    # - dogsled
+    # - dupl
+    - durationcheck
+    # - errchkjson
+    # - errname
+    - errorlint
+    # - execinquery
+    # - exhaustive
+    # - exhaustruct
+    # - exportloopref
+    #- forcetypeassert
+    #- forbidigo
+    #- funlen
+    #- gci
+    # - gochecknoglobals
+    # - gochecknoinits
+    # - gocognit
+    # - goconst
+    # - gocritic
+    - gocyclo
+    - godot
+    # - godox
+    # - goerr113
+    # - gofmt
+    # - gofumpt
+    # - goheader
+    - goimports
+    # - golint
+    # - gomnd
+    # - gomoddirectives
+    # - gomodguard
+    # - goprintffuncname
+    - gosec
+    - gosimple
+    - govet
+    # - grouper
+    # - ifshort
+    - importas
+    - ineffassign
+    # - interfacebloat
+    # - interfacer
+    # - ireturn
+    # - lll
+    # - maintidx
+    # - makezero
+    - maligned
+    - misspell
+    # - nakedret
+    # - nestif
+    # - nilerr
+    # - nilnil
+    # - nlreturn
+    # - noctx
+    # - nolintlint
+    # - nonamedreturns
+    # - nosnakecase
+    # - nosprintfhostport
+    # - paralleltest
+    # - prealloc
+    # - predeclared
+    # - promlinter
+    - reassign
+    # - revive
+    # - rowserrcheck
+    # - scopelint
+    # - sqlclosecheck
+    # - staticcheck
+    # - structcheck
+    # - stylecheck
+    # - tagliatelle
+    # - tenv
+    # - testpackage
+    # - thelper
+    - tparallel
+    # - typecheck
+    - unconvert
+    - unparam
+    - unused
+    - usestdlibvars
+    # - varcheck
+    # - varnamelen
+    - wastedassign
+    - whitespace
+    # - wrapcheck
+    # - wsl
+  disable:
+    - errcheck
+
+

Dockerfile

@@ -0,0 +1,22 @@
+FROM golang:1.21.0-alpine3.18 AS builder
+
+RUN apk update
+RUN apk add git
+
+WORKDIR /app
+
+COPY go.mod ./
+COPY go.sum ./
+RUN go mod download
+
+COPY . ./
+
+RUN go build -o /app/mochi ./cmd/docker
+
+FROM alpine
+
+WORKDIR /
+COPY --from=builder /app/mochi .
+
+ENTRYPOINT [ "/mochi" ]
+CMD ["/cmd/docker", "--config", "config.yaml"]

LICENSE.md

@@ -1,7 +1,8 @@
 
 The MIT License (MIT)
 
-Copyright (c) 2019 Jonathan Blake (mochi)
+Copyright (c) 2023 Mochi-MQTT Organisation
+Copyright (c) 2019, 2022, 2023 Jonathan Blake (mochi-co)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README-CN.md

@@ -0,0 +1,505 @@
+# Mochi-MQTT Server
+
+<p align="center">
+    
+![build status](https://github.com/mochi-mqtt/server/actions/workflows/build.yml/badge.svg) 
+[![Coverage Status](https://coveralls.io/repos/github/mochi-mqtt/server/badge.svg?branch=master&v2)](https://coveralls.io/github/mochi-mqtt/server?branch=master)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mochi-mqtt/server)](https://goreportcard.com/report/github.com/mochi-mqtt/server/v2)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mochi-mqtt/server.svg)](https://pkg.go.dev/github.com/mochi-mqtt/server/v2)
+[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/mochi-mqtt/server/issues)
+
+</p>
+
+[English](README.md) | [简体中文](README-CN.md) | [日本語](README-JP.md) | [招募翻译者!](https://github.com/orgs/mochi-mqtt/discussions/310)
+
+
+🎆 **mochi-co/mqtt 现在已经是新的 mochi-mqtt 组织的一部分。** 详细信息请[阅读公告.](https://github.com/orgs/mochi-mqtt/discussions/271)
+
+
+### Mochi-MQTT 是一个完全兼容的、可嵌入的高性能 Go MQTT v5（以及 v3.1.1）中间件/服务器。
+
+Mochi MQTT 是一个[完全兼容 MQTT v5](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html) 的可嵌入的中间件/服务器，完全使用 Go 语言编写，旨在用于遥测和物联网项目的开发。它可以作为独立的二进制文件使用，也可以嵌入到你自己的应用程序中作为库来使用，经过精心设计以实现尽可能的轻量化和快速部署，同时也极为重视代码的质量和可维护性。
+
+#### 什么是 MQTT?
+MQTT 代表 MQ Telemetry Transport。它是一种发布/订阅、非常简单和轻量的消息传递协议，专为受限设备和低带宽、高延迟或不可靠网络设计而成（[了解更多](https://mqtt.org/faq)）。Mochi MQTT 实现了完整的 MQTT 协议的 5.0.0 版本。
+
+#### Mochi-MQTT 特性
+- 完全兼容 MQTT v5 功能，与 MQTT v3.1.1 和 v3.0.0 兼容：
+    - MQTT v5 用户和数据包属性
+    - 主题别名(Topic Aliases)
+    - 共享订阅(Shared Subscriptions)
+    - 订阅选项和订阅标识符(Identifiers)
+    - 消息过期(Message Expiry)
+    - 客户端会话过期(Client Session Expiry)
+    - 发送和接收 QoS 流量控制配额(Flow Control Quotas)
+    - 服务器端的断开连接和数据包的权限验证(Auth Packets)
+    - 遗愿消息延迟间隔(Will Delay Intervals)
+    - 还有 Mochi MQTT v1 的所有原始 MQTT 功能，例如完全的 QoS（0,1,2）、$SYS 主题、保留消息等。
+- 面向开发者：
+    - 核心代码都已开放并可访问，以便开发者完全控制。
+    - 功能丰富且灵活的基于钩子(Hook)的接口系统，支持便捷的“插件(plugin)”开发。
+    - 使用特殊的内联客户端(inline client)进行服务端的消息发布，也支持服务端伪装成现有的客户端。
+- 高性能且稳定：
+    - 基于经典前缀树 Trie 的主题-订阅模型。
+    - 客户端特定的写入缓冲区，避免因读取速度慢或客户端不规范行为而产生的问题。
+    - 通过所有 [Paho互操作性测试](https://github.com/eclipse/paho.mqtt.testing/tree/master/interoperability)（MQTT v5 和 MQTT v3）。
+    - 超过一千多个经过仔细考虑的单元测试场景。
+- 支持 TCP、Websocket（包括 SSL/TLS）和$SYS 服务状态监控。
+- 内置 基于Redis、Badger 和 Bolt 的持久化（使用Hook钩子，你也可以自己创建）。
+- 内置基于规则的认证和 ACL 权限管理（使用Hook钩子，你也可以自己创建）。
+
+### 兼容性说明(Compatibility Notes)
+由于 v5 规范与 MQTT 的早期版本存在重叠，因此服务器可以接受 v5 和 v3 客户端，但在连接了 v5 和 v3 客户端的情况下，为 v5 客户端提供的属性和功能将会对 v3 客户端进行降级处理（例如用户属性）。
+
+对于 MQTT v3.0.0 和 v3.1.1 的支持被视为混合兼容性。在 v3 规范中没有明确限制的情况下，将使用更新的和以安全为首要考虑的 v5 规范 - 例如保留的消息(retained messages)的过期处理，待发送消息(inflight messages)的过期处理、客户端过期处理以及QOS消息数量的限制等。
+
+#### 版本更新时间
+除非涉及关键问题，新版本通常在周末发布。
+
+## 规划路线图(Roadmap)
+- 请[提出问题](https://github.com/mochi-mqtt/server/issues)来请求新功能或新的hook钩子接口！
+- 集群支持。
+- 统计度量支持。
+- 配置文件支持（支持 Docker）。
+
+## 快速开始(Quick Start)
+### 使用 Go 运行服务端
+Mochi MQTT 可以作为独立的中间件使用。只需拉取此仓库代码，然后在 [cmd](cmd) 文件夹中运行 [cmd/main.go](cmd/main.go) ，默认将开启下面几个服务端口， tcp (:1883)、websocket (:1882) 和服务状态监控 (:8080) 。
+
+```
+cd cmd
+go build -o mqtt && ./mqtt
+```
+
+### 使用 Docker
+
+你现在可以从 Docker Hub 仓库中拉取并运行Mochi MQTT[官方镜像](https://hub.docker.com/r/mochimqtt/server)：
+```sh
+docker pull mochimqtt/server
+或者
+docker run mochimqtt/server
+```
+
+我们还在积极完善这部分的工作，现在正在实现使用[配置文件的启动](https://github.com/orgs/mochi-mqtt/projects/2)方式。更多关于 Docker 的支持正在[这里](https://github.com/orgs/mochi-mqtt/discussions/281#discussion-5544545)和[这里](https://github.com/orgs/mochi-mqtt/discussions/209)进行讨论。如果你有在这个场景下使用 Mochi-MQTT，也可以参与到讨论中来。
+
+我们提供了一个简单的 Dockerfile，用于运行 cmd/main.go 中的 Websocket(:1882)、TCP(:1883) 和服务端状态信息(:8080)这三个服务监听：
+
+```sh
+docker build -t mochi:latest .
+docker run -p 1883:1883 -p 1882:1882 -p 8080:8080 mochi:latest
+```
+
+
+## 使用 Mochi MQTT 进行开发
+### 将Mochi MQTT作为包导入使用
+将 Mochi MQTT 作为一个包导入只需要几行代码即可开始使用。
+``` go
+import (
+  "log"
+
+  mqtt "github.com/mochi-mqtt/server/v2"
+  "github.com/mochi-mqtt/server/v2/hooks/auth"
+  "github.com/mochi-mqtt/server/v2/listeners"
+)
+
+func main() {
+  // 创建信号用于等待服务端关闭信号
+  sigs := make(chan os.Signal, 1)
+  done := make(chan bool, 1)
+  signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+  go func() {
+    <-sigs
+    done <- true
+  }()
+
+  // 创建新的 MQTT 服务器。
+  server := mqtt.New(nil)
+  
+  // 允许所有连接(权限)。
+  _ = server.AddHook(new(auth.AllowHook), nil)
+  
+  // 在标1883端口上创建一个 TCP 服务端。
+  tcp := listeners.NewTCP("t1", ":1883", nil)
+  err := server.AddListener(tcp)
+  if err != nil {
+    log.Fatal(err)
+  }
+  
+
+  go func() {
+    err := server.Serve()
+    if err != nil {
+      log.Fatal(err)
+    }
+  }()
+
+  // 服务端等待关闭信号
+  <-done
+
+  // 关闭服务端时需要做的一些清理工作
+}
+```
+
+在 [examples](examples) 文件夹中可以找到更多使用不同配置运行服务端的示例。
+
+#### 网络监听器 (Network Listeners)
+
+服务端内置了一些已经实现的网络监听(Network Listeners)，这些Listeners允许服务端接受不同协议的连接。当前的监听Listeners有这些：
+
+| Listener                     | Usage                                                                                        |
+|------------------------------|----------------------------------------------------------------------------------------------|
+| listeners.NewTCP             | 一个 TCP 监听器，接收TCP连接                                                                   |
+| listeners.NewUnixSock        | 一个 Unix 套接字监听器                                                                        |
+| listeners.NewNet             | 一个 net.Listener 监听                                                                       |
+| listeners.NewWebsocket       | 一个 Websocket 监听器                                                                        |
+| listeners.NewHTTPStats       | 一个 HTTP $SYS 服务状态监听器                                                                 |
+| listeners.NewHTTPHealthCheck | 一个 HTTP 健康检测监听器，用于为例如云基础设施提供健康检查响应                                   |
+
+> 可以使用listeners.Listener接口开发新的监听器。如果有兴趣，你可以实现自己的Listener，如果你在此期间你有更好的建议或疑问，你可以[提交问题](https://github.com/mochi-mqtt/server/issues)给我们。 
+
+可以在*listeners.Config 中配置TLS，传递给Listener使其支持TLS。
+我们提供了一些示例，可以在 [示例](examples) 文件夹或 [cmd/main.go](cmd/main.go) 中找到。
+
+### 服务端选项和功能(Server Options and Capabilities)
+
+有许多可配置的选项(Options)可用于更改服务器的行为或限制对某些功能的访问。
+```go
+server := mqtt.New(&mqtt.Options{
+  Capabilities: mqtt.Capabilities{
+    MaximumSessionExpiryInterval: 3600,
+    Compatibilities: mqtt.Compatibilities{
+      ObscureNotAuthorized: true,
+    },
+  },
+  ClientNetWriteBufferSize: 4096,
+  ClientNetReadBufferSize: 4096,
+  SysTopicResendInterval: 10,
+  InlineClient: false,
+})
+```
+请参考 mqtt.Options、mqtt.Capabilities 和 mqtt.Compatibilities 结构体，以查看完整的所有服务端选项。ClientNetWriteBufferSize 和 ClientNetReadBufferSize 可以根据你的需求配置调整每个客户端的内存使用状况。
+
+### 默认配置说明(Default Configuration Notes)
+
+关于决定默认配置的值，在这里进行一些说明：
+
+- 默认情况下，server.Options.Capabilities.MaximumMessageExpiryInterval 的值被设置为 86400（24小时），以防止在使用默认配置时网络上暴露服务器而受到恶意DOS攻击（如果不配置到期时间将允许无限数量的保留retained/待发送inflight消息累积）。如果您在一个受信任的环境中运行，或者您有更大的保留期容量，您可以选择覆盖此设置（设置为0 以取消到期限制）。
+
+## 事件钩子(Event Hooks)
+
+服务端有一个通用的事件钩子(Event Hooks)系统，它允许开发人员在服务器和客户端生命周期的各个阶段定制添加和修改服务端的功能。这些通用Hook钩子用于提供从认证(authentication)、持久性存储(persistent storage)到调试工具(debugging tools)等各种功能。
+
+钩子(Hook)是可叠加的 - 你可以向服务器添加多个钩子(Hook)，它们将按添加的顺序运行。一些钩子(Hook)修改值，这些修改后的值将在所有钩子返回之前传递给后续的钩子(Hook)。
+
+| 类型           | 导入包                                                                   | 描述                                                                       |
+|----------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------|
+| 访问控制 | [mochi-mqtt/server/hooks/auth . AllowHook](hooks/auth/allow_all.go)      | AllowHook	允许所有客户端连接访问并读写所有主题。      | 
+| 访问控制 | [mochi-mqtt/server/hooks/auth . Auth](hooks/auth/auth.go)                | 基于规则的访问权限控制。  | 
+| 数据持久性    | [mochi-mqtt/server/hooks/storage/bolt](hooks/storage/bolt/bolt.go)       | 使用 [BoltDB](https://dbdb.io/db/boltdb) 进行持久性存储（已弃用）。 | 
+| 数据持久性    | [mochi-mqtt/server/hooks/storage/badger](hooks/storage/badger/badger.go) | 使用 [BadgerDB](https://github.com/dgraph-io/badger) 进行持久性存储。   | 
+| 数据持久性    | [mochi-mqtt/server/hooks/storage/redis](hooks/storage/redis/redis.go)    | 使用 [Redis](https://redis.io) 进行持久性存储。                         | 
+| 调试跟踪      | [mochi-mqtt/server/hooks/debug](hooks/debug/debug.go)                    | 调试输出以查看数据包在服务端的链路追踪。   |
+
+许多内部函数都已开放给开发者，你可以参考上述示例创建自己的Hook钩子。如果你有更好的关于Hook钩子方面的建议或者疑问，你可以[提交问题](https://github.com/mochi-mqtt/server/issues)给我们。
+
+### 访问控制(Access Control)
+
+#### 允许所有(Allow Hook)
+
+默认情况下，Mochi MQTT 使用拒绝所有(DENY-ALL)的访问控制规则。要允许连接，必须实现一个访问控制的钩子(Hook)来替代默认的(DENY-ALL)钩子。其中最简单的钩子(Hook)是 auth.AllowAll 钩子(Hook)，它为所有连接、订阅和发布提供允许所有(ALLOW-ALL)的规则。这也是使用最简单的钩子：
+
+```go
+server := mqtt.New(nil)
+_ = server.AddHook(new(auth.AllowHook), nil)
+```
+
+>如果你将服务器暴露在互联网或不受信任的网络上，请不要这样做 - 它真的应该仅用于开发、测试和调试。
+
+#### 权限认证(Auth Ledger)
+
+权限认证钩子(Auth Ledger hook)使用结构化的定义来制定访问规则。认证规则分为两种形式：身份规则（连接时使用）和 ACL权限规则（发布订阅时使用）。
+
+身份规则(Auth rules)有四个可选参数和一个是否允许参数：
+
+| 参数 | 说明 | 
+| -- | -- |
+| Client | 客户端的客户端 ID |
+| Username | 客户端的用户名 |
+| Password | 客户端的密码 |
+| Remote | 客户端的远程地址或 IP |
+| Allow | true（允许此用户）或 false（拒绝此用户） | 
+
+ACL权限规则(ACL rules)有三个可选参数和一个主题匹配参数：
+| 参数 | 说明 | 
+| -- | -- |
+| Client | 客户端的客户端 ID |
+| Username | 客户端的用户名 |
+| Remote | 客户端的远程地址或 IP |
+| Filters | 用于匹配的主题数组 |
+
+规则按索引顺序（0,1,2,3）处理，并在匹配到第一个规则时返回。请查看  [hooks/auth/ledger.go](hooks/auth/ledger.go) 的具体实现。
+
+```go
+server := mqtt.New(nil)
+err := server.AddHook(new(auth.Hook), &auth.Options{
+    Ledger: &auth.Ledger{
+    Auth: auth.AuthRules{ // Auth 默认情况下禁止所有连接
+      {Username: "peach", Password: "password1", Allow: true},
+      {Username: "melon", Password: "password2", Allow: true},
+      {Remote: "127.0.0.1:*", Allow: true},
+      {Remote: "localhost:*", Allow: true},
+    },
+    ACL: auth.ACLRules{ // ACL 默认情况下允许所有连接
+      {Remote: "127.0.0.1:*"}, // 本地用户允许所有连接
+      {
+        // 用户 melon 可以读取和写入自己的主题
+        Username: "melon", Filters: auth.Filters{
+          "melon/#":   auth.ReadWrite,
+          "updates/#": auth.WriteOnly, // 可以写入 updates，但不能从其他人那里读取 updates
+        },
+      },
+      {
+        // 其他的客户端没有发布的权限
+        Filters: auth.Filters{
+          "#":         auth.ReadOnly,
+          "updates/#": auth.Deny,
+        },
+      },
+    },
+  }
+})
+```
+
+规则还可以存储为 JSON 或 YAML，并使用 Data 字段加载文件的二进制数据：
+
+```go
+err := server.AddHook(new(auth.Hook), &auth.Options{
+    Data: data, // 从字节数组（文件二进制）读取规则：yaml 或 json
+})
+```
+详细信息请参阅 [examples/auth/encoded/main.go](examples/auth/encoded/main.go)。
+
+### 持久化存储(Persistent Storage)
+
+#### Redis
+
+我们提供了一个基本的 Redis 存储钩子(Hook)，用于为服务端提供数据持久性。你可以将这个Redis的钩子(Hook)添加到服务器中，Redis的一些参数也是可以配置的。这个钩子(Hook)里使用 github.com/go-redis/redis/v8 这个库，可以通过 Options 来配置一些参数。
+
+```go
+err := server.AddHook(new(redis.Hook), &redis.Options{
+  Options: &rv8.Options{
+    Addr:     "localhost:6379", // Redis服务端地址
+    Password: "",               // Redis服务端的密码
+    DB:       0,                // Redis数据库的index
+  },
+})
+if err != nil {
+  log.Fatal(err)
+}
+```
+有关 Redis 钩子的工作原理或如何使用它的更多信息，请参阅  [examples/persistence/redis/main.go](examples/persistence/redis/main.go) 或 [hooks/storage/redis](hooks/storage/redis) 。
+
+#### Badger DB
+
+如果您更喜欢基于文件的存储，还有一个 BadgerDB 存储钩子(Hook)可用。它可以以与其他钩子大致相同的方式添加和配置（具有较少的选项）。
+
+```go
+err := server.AddHook(new(badger.Hook), &badger.Options{
+  Path: badgerPath,
+})
+if err != nil {
+  log.Fatal(err)
+}
+```
+
+有关 Badger 钩子(Hook)的工作原理或如何使用它的更多信息，请参阅 [examples/persistence/badger/main.go](examples/persistence/badger/main.go) 或 [hooks/storage/badger](hooks/storage/badger)。
+
+还有一个 BoltDB 钩子(Hook)，已被弃用，推荐使用 Badger，但如果你想使用它，请参考 [examples/persistence/bolt/main.go](examples/persistence/bolt/main.go)。
+
+## 使用事件钩子 Event Hooks 进行开发
+
+在服务端和客户端生命周期中，开发者可以使用各种钩子(Hook)增加对服务端或客户端的一些自定义的处理。
+所有的钩子都定义在mqtt.Hook这个接口中了，可以在 [hooks.go](hooks.go) 中找到这些钩子(Hook)函数。
+
+> 最灵活的事件钩子是 OnPacketRead、OnPacketEncode 和 OnPacketSent - 这些钩子可以用来控制和修改所有传入和传出的数据包。
+
+| 钩子函数               | 说明                                                                                                                                                                                                                                                                                                      | 
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| OnStarted              | 在服务器成功启动时调 |用。                                                                                                                                                                                                                                                          |
+| OnStopped              | 在服务器成功停止时调用。                                                                                                                                                                                                                                                           | 
+| OnConnectAuthenticate  | 当用户尝试与服务器进行身份验证时调用。必须实现此方法来允许或拒绝对服务器的访问（请参阅 hooks/auth/allow_all 或 basic）。它可以在自定义Hook钩子中使用，以检查连接的用户是否与现有用户数据库中的用户匹配。如果允许访问，则返回 true。 |
+| OnACLCheck             | 当用户尝试发布或订阅主题时调用，用来检测ACL规则。                                                                                                                                                                                                                          |
+| OnSysInfoTick          | 当 $SYS 主题相关的消息被发布时调用。                                                                                                                                                                                                                                                      |
+| OnConnect              |  当新客户端连接时调用，可能返回一个错误或错误码以中断客户端的连接。                                                                                                                                                                                        | 
+| OnSessionEstablish     | 在新客户端连接并进行身份验证后，会立即调用此方法，并在会话建立和发送CONNACK之前立即调用。                                                                                                                                                                 |
+| OnSessionEstablished   | 在新客户端成功建立会话（在OnConnect之后）时调用。                                                                                                                                                                                                                            | 
+| OnDisconnect           | 当客户端因任何原因断开连接时调用。                                                                                                                                                                                                                                                      | 
+| OnAuthPacket           | 当接收到认证数据包时调用。它旨在允许开发人员创建自己的 MQTT v5 认证数据包处理机制。在这里允许数据包的修改。                                                                                                                                       | 
+| OnPacketRead           | 当从客户端接收到数据包时调用。允许对数据包进行修改。                                                                                                                                                                                                                               | 
+| OnPacketEncode         | 在数据包被编码并发送给客户端之前立即调用。允许修改数据包。                                                                                                                                                                                                          | 
+| OnPacketSent           | 在数据包已发送给客户端后调用。                                                                                                                                                                                                                                                 | 
+| OnPacketProcessed      | 在数据包已接收并成功由服务端处理后调用。                                                                                                                                                                                                                             | 
+| OnSubscribe            | 当客户端订阅一个或多个主题时调用。允许修改数据包。                                                                                                                                                                                                                       | 
+| OnSubscribed           | 当客户端成功订阅一个或多个主题时调用。                                                                                                                                                                                                                                       | 
+| OnSelectSubscribers    |  当订阅者已被关联到一个主题中，在选择共享订阅的订阅者之前调用。允许接收者修改。                                                                                                                                                  | 
+| OnUnsubscribe          | 当客户端取消订阅一个或多个主题时调用。允许包修改。                                                                                                                                                                                                                   | 
+| OnUnsubscribed         | 当客户端成功取消订阅一个或多个主题时调用。                                                                                                                                                                                                                                   | 
+| OnPublish              | 当客户端发布消息时调用。允许修改数据包。                                                                                                                                                                                                                                     | 
+| OnPublished            | 当客户端向订阅者发布消息后调用。|                                        
+| OnPublishDropped       |  消息传递给客户端之前消息已被丢弃，将调用此方法。 例如当客户端响应时间过长需要丢弃消息时。   | 
+| OnRetainMessage        | 当消息被保留时调用。                                                                                                                                                                                                                                                              | 
+| OnRetainPublished      | 当保留的消息被发布给客户端时调用。                                                                                                                                                                                                                                                  | 
+| OnQosPublish           | 当发出QoS >= 1 的消息给订阅者后调用。                                                                                                                                                                                                                               | 
+| OnQosComplete          | 在消息的QoS流程走完之后调用。                                                                                                                                                                                                                                                 | 
+| OnQosDropped           | 在消息的QoS流程未完成，同时消息到期时调用。                                                                                                                                                                                                                                                 | 
+| OnPacketIDExhausted    | 当packet ids已经用完后，没有可用的id可再分配时调用。                                                                                                                                                                                                                                        | 
+| OnWill                 | 当客户端断开连接并打算发布遗嘱消息时调用。允许修改数据包。                                                                                                                                                                                                          | 
+| OnWillSent             | 遗嘱消息发送完成后被调用。                                                                                                                                                                                                                             | 
+| OnClientExpired        | 在客户端会话已过期并应删除时调用。                                                                                                                                                                                                                                            | 
+| OnRetainedExpired      | 在保留的消息已过期并应删除时调用。|                                                                                                                                                                                                                                         | 
+| StoredClients          | 这个接口需要返回客户端列表，例如从持久化数据库中获取客户端列表。                                                                                                                                                                                          | 
+| StoredSubscriptions    | 返回客户端的所有订阅，例如从持久化数据库中获取客户端的订阅列表。                            | 
+| StoredInflightMessages | 返回待发送消息（inflight messages），例如从持久化数据库中获取到还有哪些消息未完成传输。                                                                                                                                                                                                                                               | 
+| StoredRetainedMessages | 返回保留的消息，例如从持久化数据库获取保留的消息。                                                                                                                                                                                                                                                   | 
+| StoredSysInfo          | 返回存储的系统状态信息，例如从持久化数据库获取的系统状态信息。     | 
+
+如果你想自己实现一个持久化存储的Hook钩子，请参考现有的持久存储Hook钩子以获取灵感和借鉴。如果您正在构建一个身份验证Hook钩子，您将需要实现OnACLCheck 和 OnConnectAuthenticate这两个函数接口。
+
+### 内联客户端 (Inline Client v2.4.0+支持)
+
+现在可以通过使用内联客户端功能直接在服务端上订阅主题和发布消息。内联客户端是内置在服务端中的特殊的客户端，可以在服务端的配置中启用：
+
+```go
+server := mqtt.New(&mqtt.Options{
+  InlineClient: true,
+})
+```
+启用上述配置后，你将能够使用 server.Publish、server.Subscribe 和 server.Unsubscribe 方法来在服务端中直接发布和接收消息。
+
+具体如何使用请参考 [direct examples](examples/direct/main.go) 。
+
+#### 内联发布(Inline Publish)
+要想在服务端中直接发布Publish一个消息，可以使用 `server.Publish`方法。
+
+```go
+err := server.Publish("direct/publish", []byte("packet scheduled message"), false, 0)
+```
+> 在这种情况下，QoS级别只对订阅者有效，按照 MQTT v5 规范。
+
+#### 内联订阅(Inline Subscribe)
+要想在服务端中直接订阅一个主题，可以使用 `server.Subscribe`方法并提供一个处理订阅消息的回调函数。内联订阅的 QoS默认都是0。如果您希望对相同的主题有多个回调，可以使用 MQTTv5 的 subscriptionId 属性进行区分。
+
+```go
+callbackFn := func(cl *mqtt.Client, sub packets.Subscription, pk packets.Packet) {
+    server.Log.Info("inline client received message from subscription", "client", cl.ID, "subscriptionId", sub.Identifier, "topic", pk.TopicName, "payload", string(pk.Payload))
+}
+server.Subscribe("direct/#", 1, callbackFn)
+```
+
+#### 取消内联订阅(Inline Unsubscribe)
+如果您使用内联客户端订阅了某个主题，如果需要取消订阅。您可以使用 `server.Unsubscribe` 方法取消内联订阅：
+
+```go
+server.Unsubscribe("direct/#", 1)
+```
+
+### 注入数据包(Packet Injection)
+
+如果你想要更多的服务端控制，或者想要设置特定的MQTT v5属性或其他属性，你可以选择指定的客户端创建自己的发布包(publish packets)。这种方法允许你将MQTT数据包(packets)直接注入到运行中的服务端，相当于服务端直接自己模拟接收到了某个客户端的数据包。
+
+数据包注入(Packet Injection)可用于任何MQTT数据包，包括ping请求、订阅等。你可以获取客户端的详细信息，因此你甚至可以直接在服务端模拟某个在线的客户端，发布一个数据包。
+
+大多数情况下，您可能希望使用上面描述的内联客户端(Inline Client)，因为它具有独特的特权：它可以绕过所有ACL和主题验证检查，这意味着它甚至可以发布到$SYS主题。你也可以自己从头开始制定一个自己的内联客户端，它将与内置的内联客户端行为相同。
+
+```go
+cl := server.NewClient(nil, "local", "inline", true)
+server.InjectPacket(cl, packets.Packet{
+  FixedHeader: packets.FixedHeader{
+    Type: packets.Publish,
+  },
+  TopicName: "direct/publish",
+  Payload: []byte("scheduled message"),
+})
+```
+
+> MQTT数据包仍然需要满足规范的结构，所以请参考[测试用例中数据包的定义](packets/tpackets.go) 和 [MQTTv5规范](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html) 以获取一些帮助。
+
+具体如何使用请参考 [hooks example](examples/hooks/main.go) 。
+
+
+### 测试(Testing)
+#### 单元测试(Unit Tests)
+
+Mochi MQTT 使用精心编写的单元测试，测试了一千多种场景，以确保每个函数都表现出我们期望的行为。您可以使用以下命令运行测试：
+```
+go run --cover ./...
+```
+
+#### Paho 互操作性测试(Paho Interoperability Test)
+
+您可以使用 `examples/paho/main.go` 启动服务器，然后在 _interoperability_ 文件夹中运行 `python3 client_test5.py` 来检查代理是否符合 [Paho互操作性测试](https://github.com/eclipse/paho.mqtt.testing/tree/master/interoperability) 的要求，包括 MQTT v5 和 v3 的测试。
+
+> 请注意，关于 paho 测试套件存在一些尚未解决的问题，因此在 `paho/main.go` 示例中启用了某些兼容性模式。
+
+
+## 基准测试(Performance Benchmarks)
+
+Mochi MQTT 的性能与其他的一些主流的mqtt中间件（如 Mosquitto、EMQX 等）不相上下。
+
+基准测试是使用 [MQTT-Stresser](https://github.com/inovex/mqtt-stresser) 在 Apple Macbook Air M2 上进行的，使用 `cmd/main.go` 默认设置。考虑到高低吞吐量的突发情况，中位数分数是最有用的。数值越高越好。
+
+
+> 基准测试中呈现的数值不代表真实每秒消息吞吐量。它们依赖于 mqtt-stresser 的一种不寻常的计算方法，但它们在所有代理之间是一致的。性能基准测试的结果仅供参考。这些比较都是使用默认配置进行的。
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=2 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10      | 124,772 | 125,456 | 124,614 | 314,461 | 313,186 | 311,910 |
+| [Mosquitto v2.0.15](https://github.com/eclipse/mosquitto) | 155,920 | 155,919 | 155,918 | 185,485 | 185,097 | 184,709 |
+| [EMQX v5.0.11](https://github.com/emqx/emqx)      | 156,945 | 156,257 | 155,568 | 17,918 | 17,783 | 17,649 |
+| [Rumqtt v0.21.0](https://github.com/bytebeamio/rumqtt) | 112,208 | 108,480 | 104,753 | 135,784 | 126,446 | 117,108 |
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=10 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10      | 41,825 | 31,663| 23,008 | 144,058 | 65,903 | 37,618 |
+| Mosquitto v2.0.15 | 42,729 | 38,633 | 29,879 | 23,241 | 19,714 | 18,806 |
+| EMQX v5.0.11      | 21,553 | 17,418 | 14,356 | 4,257 | 3,980 | 3,756 |
+| Rumqtt v0.21.0    | 42,213 | 23,153 | 20,814 | 49,465 | 36,626 | 19,283 |
+
+百万消息挑战（立即向服务器发送100万条消息）:
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=100 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10     | 13,532 | 4,425 | 2,344 | 52,120 | 7,274 | 2,701 |
+| Mosquitto v2.0.15 | 3,826 | 3,395 | 3,032 | 1,200 | 1,150 | 1,118 |
+| EMQX v5.0.11      | 4,086 | 2,432 | 2,274 | 434 | 333 | 311 |
+| Rumqtt v0.21.0    | 78,972 | 5,047 | 3,804 | 4,286 | 3,249 | 2,027 |
+
+> 这里还不确定EMQX是不是哪里出了问题，可能是因为 Docker 的默认配置优化不对，所以要持保留意见，因为我们确实知道它是一款可靠的软件。
+
+## 贡献指南(Contribution Guidelines)
+
+我们欢迎代码贡献和反馈！如果你发现了漏洞(bug)或者有任何疑问，又或者是有新的需求，请[提交给我们](https://github.com/mochi-mqtt/server/issues)。如果您提交了一个PR(pull request)请求，请尽量遵循以下准则：
+
+- 在合理的情况下，尽量保持测试覆盖率。
+- 清晰地说明PR(pull request)请求的作用和原因。
+- 请不要忘记在你贡献的文件中添加 SPDX FileContributor 标签。
+
+[SPDX 注释] (https://spdx.dev) 用于智能的识别每个文件的许可证、版权和贡献。如果您正在向本仓库添加一个新文件，请确保它具有以下 SPDX 头部：
+```go
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt
+// SPDX-FileContributor: Your name or alias <optional@email.address>
+
+package name
+```
+
+请确保为文件的每位贡献者添加一个新的SPDX-FileContributor 行。可以参考其他文件的示例。请务必记得这样做，你对这个项目的贡献是有价值且受到赞赏的 - 获得认可非常重要！
+
+## 给我们星星的人数（Stargazers over time） 🥰
+[![Stargazers over time](https://starchart.cc/mochi-mqtt/server.svg)](https://starchart.cc/mochi-mqtt/server)
+
+您是否在项目中使用 Mochi MQTT？[请告诉我们！](https://github.com/mochi-mqtt/server/issues)
+

README-JP.md

@@ -0,0 +1,494 @@
+# Mochi-MQTT Server
+
+<p align="center">
+    
+![build status](https://github.com/mochi-mqtt/server/actions/workflows/build.yml/badge.svg) 
+[![Coverage Status](https://coveralls.io/repos/github/mochi-mqtt/server/badge.svg?branch=master&v2)](https://coveralls.io/github/mochi-mqtt/server?branch=master)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mochi-mqtt/server)](https://goreportcard.com/report/github.com/mochi-mqtt/server/v2)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mochi-mqtt/server.svg)](https://pkg.go.dev/github.com/mochi-mqtt/server/v2)
+[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/mochi-mqtt/server/issues)
+
+</p>
+
+[English](README.md) | [简体中文](README-CN.md) | [日本語](README-JP.md) | [Translators Wanted!](https://github.com/orgs/mochi-mqtt/discussions/310)
+
+🎆 **mochi-co/mqtt は新しい mochi-mqtt organisation の一部です.** [このページをお読みください](https://github.com/orgs/mochi-mqtt/discussions/271)
+
+
+### Mochi-MQTTは MQTT v5 (と v3.1.1)に完全に準拠しているアプリケーションに組み込み可能なハイパフォーマンスなbroker/serverです.
+
+Mochi MQTT は Goで書かれたMQTT v5に完全に[準拠](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html)しているMQTTブローカーで、IoTプロジェクトやテレメトリの開発プロジェクト向けに設計されています。 スタンドアロンのバイナリで使ったり、アプリケーションにライブラリとして組み込むことができ、プロジェクトのメンテナンス性と品質を確保できるように配慮しながら、 軽量で可能な限り速く動作するように設計されています。
+
+#### MQTTとは?
+MQTT は [MQ Telemetry Transport](https://en.wikipedia.org/wiki/MQTT)を意味します。 Pub/Sub型のシンプルで軽量なメッセージプロトコルで、低帯域、高遅延、不安定なネットワーク下での制約を考慮して設計されています([MQTTについて詳しくはこちら](https://mqtt.org/faq))。 Mochi MQTTはMQTTプロトコルv5.0.0に完全準拠した実装をしています。
+
+#### Mochi-MQTTのもつ機能
+
+- MQTTv5への完全な準拠とMQTT v3.1.1 および v3.0.0 との互換性:
+    - MQTT v5で拡張されたユーザープロパティ
+    - トピック・エイリアス
+    - 共有サブスクリプション
+    - サブスクリプションオプションとサブスクリプションID
+    - メッセージの有効期限
+    - クライアントセッション
+    - 送受信QoSフロー制御クォータ
+    - サーバサイド切断と認証パケット
+    - Will遅延間隔
+    - 上記に加えてQoS(0,1,2)、$SYSトピック、retain機能などすべてのMQTT v1の特徴を持ちます
+- Developer-centric:
+    - 開発者が制御できるように、ほとんどのコアブローカーのコードをエクスポートにしてアクセスできるようにしました。
+    - フル機能で柔軟なフックベースのインターフェイスにすることで簡単に'プラグイン'を開発できるようにしました。
+    - 特別なインラインクライアントを利用することでパケットインジェクションを行うか、既存のクライアントとしてマスカレードすることができます。
+- パフォーマンスと安定性:
+    - 古典的なツリーベースのトピックサブスクリプションモデル
+    - クライアント固有に書き込みバッファーをもたせることにより、読み込みの遅さや不規則なクライアントの挙動の問題を回避しています。
+    - MQTT v5 and MQTT v3のすべての[Paho互換性テスト](https://github.com/eclipse/paho.mqtt.testing/tree/master/interoperability)をpassしています。
+    - 慎重に検討された多くのユニットテストシナリオでテストされています。
+- TCP, Websocket (SSL/TLSを含む), $SYSのダッシュボードリスナー
+- フックを利用した保存機能としてRedis, Badger, Boltを使うことができます（自作のHookも可能です）。
+- フックを利用したルールベース認証機能とアクセス制御リストLedgerを使うことができます（自作のHookも可能です）。
+
+### 互換性に関する注意事項
+MQTTv5とそれ以前との互換性から、サーバーはv5とv3両方のクライアントを受け入れることができますが、v5とv3のクライアントが接続された場合はv5でクライアント向けの特徴と機能はv3クライアントにダウングレードされます（ユーザープロパティなど）。
+MQTT v3.0.0 と v3.1.1 のサポートはハイブリッド互換性があるとみなされます。それはv3と仕様に制限されていない場合、例えば、送信メッセージ、保持メッセージの有効期限とQoSフロー制御制限などについては、よりモダンで安全なv5の動作が使用されます
+
+#### リリースされる時期について
+クリティカルなイシュー出ない限り、新しいリリースがされるのは週末です。
+
+## Roadmap
+- 新しい特徴やイベントフックのリクエストは [open an issue](https://github.com/mochi-mqtt/server/issues) へ！
+- クラスターのサポート
+- メトリックスサポートの強化
+- ファイルベースの設定(Dockerイメージのサポート)
+
+## Quick Start
+### GoでのBrokerの動かし方
+Mochi MQTTはスタンドアロンのブローカーとして使うことができます。単純にこのレポジトリーをチェックアウトして、[cmd/main.go](cmd/main.go) を起動すると内部の [cmd](cmd) フォルダのエントリポイントにしてtcp (:1883), websocket (:1882),  dashboard (:8080)のポートを外部にEXPOSEします。
+
+```
+cd cmd
+go build -o mqtt && ./mqtt
+```
+
+### Dockerで利用する
+Dockerレポジトリの [official Mochi MQTT image](https://hub.docker.com/r/mochimqtt/server) から Pullして起動することができます。
+
+```sh
+docker pull mochimqtt/server
+or
+docker run mochimqtt/server
+```
+
+これは実装途中です。[file-based configuration](https://github.com/orgs/mochi-mqtt/projects/2) は、この実装をよりよくサポートするために開発中です。
+より実質的なdockerのサポートが議論されています。_Docker環境で使っている方は是非この議論に参加してください。_ [ここ](https://github.com/orgs/mochi-mqtt/discussions/281#discussion-5544545) や [ここ](https://github.com/orgs/mochi-mqtt/discussions/209)。
+
+[cmd/main.go](cmd/main.go)の Websocket, TCP, Statsサーバを実行するために、シンプルなDockerfileが提供されます。 
+
+
+```sh
+docker build -t mochi:latest .
+docker run -p 1883:1883 -p 1882:1882 -p 8080:8080 mochi:latest
+```
+
+## Mochi MQTTを使って開発するには
+### パッケージをインポート
+Mochi MQTTをパッケージとしてインポートするにはほんの数行のコードで始めることができます。
+``` go
+import (
+  "log"
+
+  mqtt "github.com/mochi-mqtt/server/v2"
+  "github.com/mochi-mqtt/server/v2/hooks/auth"
+  "github.com/mochi-mqtt/server/v2/listeners"
+)
+
+func main() {
+  // Create signals channel to run server until interrupted
+  sigs := make(chan os.Signal, 1)
+  done := make(chan bool, 1)
+  signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+  go func() {
+    <-sigs
+    done <- true
+  }()
+
+  // Create the new MQTT Server.
+  server := mqtt.New(nil)
+  
+  // Allow all connections.
+  _ = server.AddHook(new(auth.AllowHook), nil)
+  
+  // Create a TCP listener on a standard port.
+  tcp := listeners.NewTCP("t1", ":1883", nil)
+  err := server.AddListener(tcp)
+  if err != nil {
+    log.Fatal(err)
+  }
+  
+
+  go func() {
+    err := server.Serve()
+    if err != nil {
+      log.Fatal(err)
+    }
+  }()
+
+  // Run server until interrupted
+  <-done
+
+  // Cleanup
+}
+```
+
+ブローカーの動作例は [examples](examples)フォルダにあります。
+
+#### Network Listeners
+サーバは様々なプロトコルのコネクションのリスナーに対応しています。現在の対応リスナーは、
+
+| Listener                     | Usage                                                                                        |
+|------------------------------|----------------------------------------------------------------------------------------------|
+| listeners.NewTCP             | TCPリスナー                                                                              |
+| listeners.NewUnixSock        | Unixソケットリスナー                                                                      |
+| listeners.NewNet             | net.Listenerリスナー                                                                      |
+| listeners.NewWebsocket       | Websocketリスナー                                                                         |
+| listeners.NewHTTPStats       | HTTP $SYSダッシュボード                                                                 |
+| listeners.NewHTTPHealthCheck | ヘルスチェック応答を提供するためのHTTPヘルスチェックリスナー(クラウドインフラ) |
+
+> 新しいリスナーを開発するためには `listeners.Listener` を使ってください。使ったら是非教えてください！
+
+TLSを設定するには`*listeners.Config`を渡すことができます。
+
+[examples](examples) フォルダと [cmd/main.go](cmd/main.go)に使用例があります。
+
+
+## 設定できるオプションと機能
+たくさんのオプションが利用可能です。サーバーの動作を変更したり、特定の機能へのアクセスを制限することができます。
+
+```go
+server := mqtt.New(&mqtt.Options{
+  Capabilities: mqtt.Capabilities{
+    MaximumSessionExpiryInterval: 3600,
+    Compatibilities: mqtt.Compatibilities{
+      ObscureNotAuthorized: true,
+    },
+  },
+  ClientNetWriteBufferSize: 4096,
+  ClientNetReadBufferSize: 4096,
+  SysTopicResendInterval: 10,
+  InlineClient: false,
+})
+```
+
+mqtt.Options、mqtt.Capabilities、mqtt.Compatibilitiesの構造体はオプションの理解に役立ちます。
+必要に応じて`ClientNetWriteBufferSize`と`ClientNetReadBufferSize`はクライアントの使用するメモリに合わせて設定できます。
+
+### デフォルト設定に関する注意事項
+
+いくつかのデフォルトの設定を決める際にいくつかの決定がなされましたのでここに記しておきます:
+- デフォルトとして、敵対的なネットワーク上のDoSアタックにさらされるのを防ぐために `server.Options.Capabilities.MaximumMessageExpiryInterval`は86400 (24時間)に、とセットされています。有効期限を無限にすると、保持、送信メッセージが無限に蓄積されるからです。もし信頼できる環境であったり、より大きな保存期間が可能であれば、この設定はオーバーライドできます（`0` を設定すると有効期限はなくなります。）
+
+## Event Hooks 
+ユニバーサルイベントフックシステムは、開発者にサーバとクライアントの様々なライフサイクルをフックすることができ、ブローカーの機能を追加/変更することができます。それらのユニバーサルフックは認証、永続ストレージ、デバッグツールなど、あらゆるものに使用されています。
+フックは複数重ねることができ、サーバに複数のフックを設定することができます。それらは追加した順番に動作します。いくつかのフックは値を変えて、その値は動作コードに返される前にあとに続くフックに渡されます。
+
+
+| Type           | Import                                                                   | Info                                                                       |
+|----------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------|
+| Access Control | [mochi-mqtt/server/hooks/auth . AllowHook](hooks/auth/allow_all.go)      | すべてのトピックに対しての読み書きをすべてのクライアントに対して許可します。     | 
+| Access Control | [mochi-mqtt/server/hooks/auth . Auth](hooks/auth/auth.go)                | ルールベースのアクセスコントロール台帳です。                                         | 
+| Persistence    | [mochi-mqtt/server/hooks/storage/bolt](hooks/storage/bolt/bolt.go)       |  [BoltDB](https://dbdb.io/db/boltdb) を使った永続ストレージ (非推奨). | 
+| Persistence    | [mochi-mqtt/server/hooks/storage/badger](hooks/storage/badger/badger.go) | [BadgerDB](https://github.com/dgraph-io/badger)を使った永続ストレージ  | 
+| Persistence    | [mochi-mqtt/server/hooks/storage/redis](hooks/storage/redis/redis.go)    | [Redis](https://redis.io)を使った永続ストレージ                   | 
+| Debugging      | [mochi-mqtt/server/hooks/debug](hooks/debug/debug.go)                    | パケットフローを可視化するデバッグ用のフック                       | 
+
+たくさんの内部関数が開発者に公開されています、なので、上記の例を使って自分でフックを作ることができます。もし作ったら是非[Open an issue](https://github.com/mochi-mqtt/server/issues)に投稿して教えてください！
+
+### アクセスコントロール
+#### Allow Hook
+デフォルトで、Mochi MQTTはアクセスコントロールルールにDENY-ALLを使用しています。コネクションを許可するためには、アクセスコントロールフックを上書きする必要があります。一番単純なのは`auth.AllowAll`フックで、ALLOW-ALLルールがすべてのコネクション、サブスクリプション、パブリッシュに適用されます。使い方は下記のようにするだけです: 
+
+```go
+server := mqtt.New(nil)
+_ = server.AddHook(new(auth.AllowHook), nil)
+```
+
+> もしインターネットや信頼できないネットワークにさらされる場合は行わないでください。これは開発・テスト・デバッグ用途のみであるべきです。
+
+#### Auth Ledger
+Auth Ledgerは構造体で定義したアクセスルールの洗練された仕組みを提供します。Auth Ledgerルール２つの形式から成ります、認証ルール(コネクション)とACLルール(パブリッシュ、サブスクライブ)です。
+
+認証ルールは4つのクライテリアとアサーションフラグがあります: 
+| Criteria | Usage | 
+| -- | -- |
+| Client | 接続クライアントのID |
+| Username | 接続クライアントのユーザー名 |
+| Password | 接続クライアントのパスワード |
+| Remote | クライアントのリモートアドレスもしくはIP |
+| Allow | true(このユーザーを許可する)もしくはfalse(このユーザを拒否する) | 
+
+アクセスコントロールルールは3つのクライテリアとフィルターマッチがあります:
+| Criteria | Usage | 
+| -- | -- |
+| Client | 接続クライアントのID |
+| Username | 接続クライアントのユーザー名 |
+| Remote | クライアントのリモートアドレスもしくはIP |
+| Filters | 合致するフィルターの配列 |
+
+ルールはインデックス順(0,1,2,3)に処理され、はじめに合致したルールが適用されます。 [hooks/auth/ledger.go](hooks/auth/ledger.go) の構造体を見てください。
+
+
+```go
+server := mqtt.New(nil)
+err := server.AddHook(new(auth.Hook), &auth.Options{
+    Ledger: &auth.Ledger{
+    Auth: auth.AuthRules{ // Auth disallows all by default
+      {Username: "peach", Password: "password1", Allow: true},
+      {Username: "melon", Password: "password2", Allow: true},
+      {Remote: "127.0.0.1:*", Allow: true},
+      {Remote: "localhost:*", Allow: true},
+    },
+    ACL: auth.ACLRules{ // ACL allows all by default
+      {Remote: "127.0.0.1:*"}, // local superuser allow all
+      {
+        // user melon can read and write to their own topic
+        Username: "melon", Filters: auth.Filters{
+          "melon/#":   auth.ReadWrite,
+          "updates/#": auth.WriteOnly, // can write to updates, but can't read updates from others
+        },
+      },
+      {
+        // Otherwise, no clients have publishing permissions
+        Filters: auth.Filters{
+          "#":         auth.ReadOnly,
+          "updates/#": auth.Deny,
+        },
+      },
+    },
+  }
+})
+```
+
+ledgeはデータフィールドを使用してJSONもしくはYAML形式で保存したものを使用することもできます。
+```go
+err := server.AddHook(new(auth.Hook), &auth.Options{
+    Data: data, // build ledger from byte slice: yaml or json
+})
+```
+より詳しくは[examples/auth/encoded/main.go](examples/auth/encoded/main.go)を見てください。
+
+### 永続ストレージ
+#### Redis
+ブローカーに永続性を提供する基本的な Redis ストレージフックが利用可能です。他のフックと同じ方法で、いくつかのオプションを使用してサーバーに追加できます。それはフック内部で github.com/go-redis/redis/v8 を使用し、Optionsの値で詳しい設定を行うことができます。
+```go
+err := server.AddHook(new(redis.Hook), &redis.Options{
+  Options: &rv8.Options{
+    Addr:     "localhost:6379", // default redis address
+    Password: "",               // your password
+    DB:       0,                // your redis db
+  },
+})
+if err != nil {
+  log.Fatal(err)
+}
+```
+Redisフックがどのように動くか、どのように使用するかについての詳しくは、[examples/persistence/redis/main.go](examples/persistence/redis/main.go) か [hooks/storage/redis](hooks/storage/redis) のソースコードを見てください。
+
+#### Badger DB
+もしファイルベースのストレージのほうが適しているのであれば、BadgerDBストレージも使用することができます。それもまた、他のフックと同様に追加、設定することができます（オプションは若干少ないです）。
+
+```go
+err := server.AddHook(new(badger.Hook), &badger.Options{
+  Path: badgerPath,
+})
+if err != nil {
+  log.Fatal(err)
+}
+```
+
+badgerフックがどのように動くか、どのように使用するかについての詳しくは、[examples/persistence/badger/main.go](examples/persistence/badger/main.go) か [hooks/storage/badger](hooks/storage/badger) のソースコードを見てください。
+
+BoltDBフックはBadgerに代わって非推奨となりましたが、もし必要ならば [examples/persistence/bolt/main.go](examples/persistence/bolt/main.go)をチェックしてください。
+
+## イベントフックを利用した開発
+
+ブローカーとクライアントのライフサイクルに関わるたくさんのフックが利用できます。
+そのすべてのフックと`mqtt.Hook`インターフェイスの関数シグネチャは[hooks.go](hooks.go)に記載されています。
+
+> もっと柔軟なイベントフックはOnPacketRead、OnPacketEncodeとOnPacketSentです。それらは、すべての流入パケットと流出パケットをコントロール及び変更に使用されるフックです。
+
+
+| Function               | Usage                                                                                                                                                                                                                                                                                                      | 
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| OnStarted              | サーバーが正常にスタートした際に呼ばれます。                                                                                                                                                                                                                                                         |
+| OnStopped              | サーバーが正常に終了した際に呼ばれます。                                                                                                                                                                                                                                                           | 
+| OnConnectAuthenticate  | ユーザーがサーバと認証を試みた際に呼ばれます。このメソッドはサーバーへのアクセス許可もしくは拒否するためには必ず使用する必要があります（hooks/auth/allow_all or basicを見てください）。これは、データベースにユーザーが存在するか照合してチェックするカスタムフックに利用できます。許可する場合はtrueを返す実装をします。|
+| OnACLCheck             | ユーザーがあるトピックフィルタにpublishかsubscribeした際に呼ばれます。上と同様です                                                   |
+| OnSysInfoTick          | $SYSトピック値がpublishされた場合に呼ばれます。                                                                                                                                      |
+| OnConnect              | 新しいクライアントが接続した際によばれます、エラーかパケットコードを返して切断する場合があります。                                                                                                                                                 | 
+| OnSessionEstablish     | 新しいクライアントが接続された後すぐ、セッションが確立されてCONNACKが送信される前に呼ばれます。                                                                                                                              |
+| OnSessionEstablished   | 新しいクライアントがセッションを確立した際(OnConnectの後)に呼ばれます。                                                                                                                                               | 
+| OnDisconnect           | クライアントが何らかの理由で切断された場合に呼ばれます。                                                                                                                                                                                                                             | 
+| OnAuthPacket           | 認証パケットを受け取ったときに呼ばれます。これは開発者にmqtt v5の認証パケットを取り扱う仕組みを作成すること意図しています。パケットを変更することができます。                                                                                                                                        | 
+| OnPacketRead           | クライアントからパケットを受け取った際に呼ばれます。パケットを変更することができます。                                                                                                                                                                                                                                | 
+| OnPacketEncode         | エンコードされたパケットがクライアントに送信する直前に呼ばれます。パケットを変更することができます。                                                                                                   | 
+| OnPacketSent           | クライアントにパケットが送信された際に呼ばれます。                                                                                                                                                                                                                                                           | 
+| OnPacketProcessed      | パケットが届いてブローカーが正しく処理できた場合に呼ばれます。                                                                                                                                                                                                                      | 
+| OnSubscribe            | クライアントが１つ以上のフィルタをsubscribeした場合に呼ばれます。パケットの変更ができます。                                                                                                                                                                                                              | 
+| OnSubscribed           | クライアントが１つ以上のフィルタをsubscribeに成功した場合に呼ばれます。                                                                                                                                                                                                                                       | 
+| OnSelectSubscribers    | サブスクライバーがトピックに収集されたとき、共有サブスクライバーが選択される前に呼ばれる。受信者は変更可能。                                                                                                                                               | 
+| OnUnsubscribe          | １つ以上のあんサブスクライブが呼ばれた場合。パケットの変更は可能。                                                                                                                                                                                                                 | 
+| OnUnsubscribed         | クライアントが正常に1つ以上のトピックフィルタをサブスクライブ解除した場合。                                                                                                                                                                                                                                   | 
+| OnPublish              | クライアントがメッセージをパブリッシュした場合。パケットの変更は可能。                                                                                                                                                   | 
+| OnPublished            | クライアントがサブスクライバーにメッセージをパブリッシュし終わった場合。                                                                                                                                                                                                                                      | 
+| OnPublishDropped       | あるクライアントが反応に時間がかかった場合等のようにクライアントに到達する前にメッセージが失われた場合に呼ばれる。                                                                                                                                                                                         | 
+| OnRetainMessage        | パブリッシュされたメッセージが保持された場合に呼ばれる。                                                                                                                                                                                                                                                    | 
+| OnRetainPublished      | 保持されたメッセージがクライアントに到達した場合に呼ばれる。                                                                                                                                                                                                                                          | 
+| OnQosPublish           | QoSが1以上のパケットがサブスクライバーに発行された場合。                                                                                                                                                                                | 
+| OnQosComplete          | そのメッセージQoSフローが完了した場合に呼ばれる。                                                                                                                                                                                                             | 
+| OnQosDropped           | インフライトメッセージが完了前に期限切れになった場合に呼ばれる。                                                                                                                                                                                                                                                | 
+| OnPacketIDExhausted    |  クライアントがパケットに割り当てるIDが枯渇した場合に呼ばれる。                                                                                                                                                                                                                                             | 
+| OnWill                 | クライアントが切断し、WILLメッセージを発行しようとした場合に呼ばれる。パケットの変更が可能。                                                                                                                                                                                        | 
+| OnWillSent             | LWTメッセージが切断されたクライアントから発行された場合に呼ばれる                                                                                                                                                                                                                                   | 
+| OnClientExpired        | クライアントセッションが期限切れで削除するべき場合に呼ばれる。                                                                                                                                                                                                                                 | 
+| OnRetainedExpired      | 保持メッセージが期限切れで削除すべき場合に呼ばれる。                                                                                                                                                                               | 
+| StoredClients          | クライアントを返す。例えば永続ストレージから。                                                                                                                                                                                                                                                             | 
+| StoredSubscriptions    | クライアントのサブスクリプションを返す。例えば永続ストレージから。                                                                                                                                                                                                                                            | 
+| StoredInflightMessages | インフライトメッセージを返す。例えば永続ストレージから。                                                                                                                                                                                                                                                | 
+| StoredRetainedMessages | 保持されたメッセージを返す。例えば永続ストレージから。                                                                                                                                                                                                                                                 | 
+| StoredSysInfo          | システム情報の値を返す。例えば永続ストレージから。                                                                                                                                                                                                                                        | 
+
+もし永続ストレージフックを作成しようとしているのであれば、すでに存在する永続的なフックを見てインスピレーションとどのようなパターンがあるか見てみてください。もし認証フックを作成しようとしているのであれば、`OnACLCheck`と`OnConnectAuthenticate`が役立つでしょう。
+
+### Inline Client (v2.4.0+)
+トピックに対して埋め込まれたコードから直接サブスクライブとパブリッシュできます。そうするには`inline client`機能を使うことができます。インラインクライアント機能はサーバの一部として組み込まれているクライアントでサーバーのオプションとしてEnableにできます。
+```go
+server := mqtt.New(&mqtt.Options{
+  InlineClient: true,
+})
+```
+Enableにすると、`server.Publish`, `server.Subscribe`, `server.Unsubscribe`のメソッドを利用できて、ブローカーから直接メッセージを送受信できます。
+> 実際の使用例は[direct examples](examples/direct/main.go)を見てください。
+
+#### Inline Publish
+組み込まれたアプリケーションからメッセージをパブリッシュするには`server.Publish(topic string, payload []byte, retain bool, qos byte) error`メソッドを利用します。
+
+```go
+err := server.Publish("direct/publish", []byte("packet scheduled message"), false, 0)
+```
+> このケースでのQoSはサブスクライバーに設定できる上限でしか使用されません。これはMQTTv5の仕様に従っています。
+
+#### Inline Subscribe
+組み込まれたアプリケーション内部からトピックフィルタをサブスクライブするには、`server.Subscribe(filter string, subscriptionId int, handler InlineSubFn) error`メソッドがコールバックも含めて使用できます。
+インラインサブスクリプションではQoS0のみが適用されます。もし複数のコールバックを同じフィルタに設定したい場合は、MQTTv5の`subscriptionId`のプロパティがその区別に使用できます。
+
+```go
+callbackFn := func(cl *mqtt.Client, sub packets.Subscription, pk packets.Packet) {
+    server.Log.Info("inline client received message from subscription", "client", cl.ID, "subscriptionId", sub.Identifier, "topic", pk.TopicName, "payload", string(pk.Payload))
+}
+server.Subscribe("direct/#", 1, callbackFn)
+```
+
+#### Inline Unsubscribe
+インラインクライアントでサブスクリプション解除をしたい場合は、`server.Unsubscribe(filter string, subscriptionId int) error` メソッドで行うことができます。
+
+```go
+server.Unsubscribe("direct/#", 1)
+```
+
+### Packet Injection
+もし、より制御したい場合や、特定のMQTTv5のプロパティやその他の値をセットしたい場合は、クライアントからのパブリッシュパケットを自ら作成することができます。この方法は単なるパブリッシュではなく、MQTTパケットをまるで特定のクライアントから受け取ったかのようにランタイムに直接インジェクションすることができます。
+
+このパケットインジェクションは例えばPING ReqやサブスクリプションなどのどんなMQTTパケットでも使用できます。そしてクライアントの構造体とメソッドはエクスポートされているので、(もし、非常にカスタマイズ性の高い要求がある場合には)まるで接続されたクライアントに代わってパケットをインジェクションすることさえできます。
+
+たいていの場合は上記のインラインクライアントを使用するのが良いでしょう、それはACLとトピックバリデーションをバイパスできる特権があるからです。これは$SYSトピックにさえパブリッシュできることも意味します。ビルトインのクライアントと同様に振る舞うインラインクライアントを作成できます。
+
+```go
+cl := server.NewClient(nil, "local", "inline", true)
+server.InjectPacket(cl, packets.Packet{
+  FixedHeader: packets.FixedHeader{
+    Type: packets.Publish,
+  },
+  TopicName: "direct/publish",
+  Payload: []byte("scheduled message"),
+})
+```
+
+> MQTTのパケットは正しく構成する必要があり、なので[the test packets catalogue](packets/tpackets.go)と[MQTTv5 Specification](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html)を参照してください。
+
+この機能の動作を確認するには[hooks example](examples/hooks/main.go) を見てください。
+
+
+### Testing
+#### ユニットテスト
+それぞれの関数が期待通りの動作をするように考えられてMochi MQTTテストが作成されています。テストを走らせるには:
+```
+go run --cover ./...
+```
+
+#### Paho相互運用性テスト
+`examples/paho/main.go`を使用してブローカーを起動し、_interoperability_フォルダの`python3 client_test5.py`のmqttv5とv3のテストを実行することで、[Paho Interoperability Test](https://github.com/eclipse/paho.mqtt.testing/tree/master/interoperability)を確認することができます。
+
+> pahoスイートには現在は何個かの偽陰性に関わるissueがあるので、`paho/main.go`の例ではいくつかの互換性モードがオンになっていることに注意してください。
+
+
+
+## ベンチマーク
+Mochi MQTTのパフォーマンスはMosquitto、EMQX、その他などの有名なブローカーに匹敵します。
+
+ベンチマークはApple Macbook Air M2上で[MQTT-Stresser](https://github.com/inovex/mqtt-stresser)、セッティングとして`cmd/main.go`のデフォルト設定を使用しています。高スループットと低スループットのバーストを考慮すると、中央値のスコアが最も信頼できます。この値は高いほど良いです。
+
+> ベンチマークの値は1秒あたりのメッセージ数のスループットのそのものを表しているわけではありません。これは、mqtt-stresserによる固有の計算に依存するものではありますが、すべてのブローカーに渡って一貫性のある値として利用しています。
+> ベンチマークは一般的なパフォーマンス予測ガイドラインとしてのみ提供されます。比較はそのまま使用したデフォルトの設定値で実行しています。
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=2 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10      | 124,772 | 125,456 | 124,614 | 314,461 | 313,186 | 311,910 |
+| [Mosquitto v2.0.15](https://github.com/eclipse/mosquitto) | 155,920 | 155,919 | 155,918 | 185,485 | 185,097 | 184,709 |
+| [EMQX v5.0.11](https://github.com/emqx/emqx)      | 156,945 | 156,257 | 155,568 | 17,918 | 17,783 | 17,649 |
+| [Rumqtt v0.21.0](https://github.com/bytebeamio/rumqtt) | 112,208 | 108,480 | 104,753 | 135,784 | 126,446 | 117,108 |
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=10 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10      | 41,825 | 31,663| 23,008 | 144,058 | 65,903 | 37,618 |
+| Mosquitto v2.0.15 | 42,729 | 38,633 | 29,879 | 23,241 | 19,714 | 18,806 |
+| EMQX v5.0.11      | 21,553 | 17,418 | 14,356 | 4,257 | 3,980 | 3,756 |
+| Rumqtt v0.21.0    | 42,213 | 23,153 | 20,814 | 49,465 | 36,626 | 19,283 |
+
+100万メッセージ試験 (100 万メッセージを一斉にサーバーに送信します):
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=100 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10     | 13,532 | 4,425 | 2,344 | 52,120 | 7,274 | 2,701 |
+| Mosquitto v2.0.15 | 3,826 | 3,395 | 3,032 | 1,200 | 1,150 | 1,118 |
+| EMQX v5.0.11      | 4,086 | 2,432 | 2,274 | 434 | 333 | 311 |
+| Rumqtt v0.21.0    | 78,972 | 5,047 | 3,804 | 4,286 | 3,249 | 2,027 |
+
+> EMQXのここでの結果は何が起きているのかわかりませんが、おそらくDockerのそのままの設定が最適ではなかったのでしょう、なので、この結果はソフトウェアのひとつの側面にしか過ぎないと捉えてください。
+
+
+## Contribution Guidelines
+コントリビューションとフィードバックは両方とも歓迎しています![Open an issue](https://github.com/mochi-mqtt/server/issues)でバグを報告したり、質問したり、新機能のリクエストをしてください。もしプルリクエストするならば下記のガイドラインに従うようにしてください。
+- 合理的で可能な限りテストカバレッジを維持してください
+- なぜPRをしたのかとそのPRの内容について明確にしてください。
+- 有意義な貢献をした場合はSPDX FileContributorタグをファイルにつけてください。
+
+[SPDX Annotations](https://spdx.dev)はそのライセンス、著作権表記、コントリビューターについて明確するのために、それぞれのファイルに機械可読な形式で記されています。もし、新しいファイルをレポジトリに追加した場合は、下記のようなSPDXヘッダーを付与していることを確かめてください。
+
+```go
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt
+// SPDX-FileContributor: Your name or alias <optional@email.address>
+
+package name
+```
+
+ファイルにそれぞれのコントリビューターの`SPDX-FileContributor`が追加されていることを確認してください、他のファイルを参考にしてください。あなたのこのプロジェクトへのコントリビュートは価値があり、高く評価されます！
+
+
+## Stargazers over time 🥰
+[![Stargazers over time](https://starchart.cc/mochi-mqtt/server.svg)](https://starchart.cc/mochi-mqtt/server)
+Mochi MQTTをプロジェクトで使用していますか？ [是非私達に教えてください!](https://github.com/mochi-mqtt/server/issues)
+

README.md

@@ -1,178 +1,515 @@
-# Mochi MQTT 
-### A High-performance MQTT server in Go (v3.0 | v3.1.1) 
+# Mochi-MQTT Server
 
-Mochi MQTT is an embeddable high-performance MQTT broker server written in Go, and compliant with the MQTT v3.0 and v3.1.1 specification for the development of IoT and smarthome projects. The server can be used either as a standalone binary or embedded as a library in your own projects. Mochi MQTT message throughput is comparable with world favourites such as Mosquitto, Mosca, and VerneMQ.
+<p align="center">
+    
+![build status](https://github.com/mochi-mqtt/server/actions/workflows/build.yml/badge.svg) 
+[![Coverage Status](https://coveralls.io/repos/github/mochi-mqtt/server/badge.svg?branch=master&v2)](https://coveralls.io/github/mochi-mqtt/server?branch=master)
+[![Go Report Card](https://goreportcard.com/badge/github.com/mochi-mqtt/server)](https://goreportcard.com/report/github.com/mochi-mqtt/server/v2)
+[![Go Reference](https://pkg.go.dev/badge/github.com/mochi-mqtt/server.svg)](https://pkg.go.dev/github.com/mochi-mqtt/server/v2)
+[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/mochi-mqtt/server/issues)
+
+</p>
+
+[English](README.md) | [简体中文](README-CN.md) | [日本語](README-JP.md) | [Translators Wanted!](https://github.com/orgs/mochi-mqtt/discussions/310)
+
+🎆 **mochi-co/mqtt is now part of the new mochi-mqtt organisation.** [Read about this announcement here.](https://github.com/orgs/mochi-mqtt/discussions/271)
+
+
+### Mochi-MQTT is a fully compliant, embeddable high-performance Go MQTT v5 (and v3.1.1) broker/server
+
+Mochi MQTT is an embeddable [fully compliant](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html) MQTT v5 broker server written in Go, designed for the development of telemetry and internet-of-things projects. The server can be used either as a standalone binary or embedded as a library in your own applications, and has been designed to be as lightweight and fast as possible, with great care taken to ensure the quality and maintainability of the project. 
 
 #### What is MQTT?
-MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks. [Learn more](https://mqtt.org/faq)
+MQTT stands for [MQ Telemetry Transport](https://en.wikipedia.org/wiki/MQTT). It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks ([Learn more](https://mqtt.org/faq)). Mochi MQTT fully implements version 5.0.0 of the MQTT protocol.
 
-#### Mochi MQTT Features
-- Paho MQTT 3.0 / 3.1.1 compatible. 
-- Full MQTT Feature-set (QoS, Retained, $SYS)
-- Trie-based Subscription model.
-- Ring Buffer packet codec.
-- TCP, Websocket, (including SSL/TLS) and Dashboard listeners.
-- Interfaces for Client Authentication and Topic access control.
-- Bolt-backed persistence and storage interfaces.
+#### Mochi-MQTT Features
 
-#### Roadmap
-- Inline Pub-sub (without client) and event hooks
-- Docker Image
-- MQTT v5 compatibility
+- Full MQTTv5 Feature Compliance, compatibility for MQTT v3.1.1 and v3.0.0:
+    - User and MQTTv5 Packet Properties
+    - Topic Aliases
+    - Shared Subscriptions
+    - Subscription Options and Subscription Identifiers
+    - Message Expiry
+    - Client Session Expiry
+    - Send and Receive QoS Flow Control Quotas
+    - Server-side Disconnect and Auth Packets
+    - Will Delay Intervals
+    - Plus all the original MQTT features of Mochi MQTT v1, such as Full QoS(0,1,2), $SYS topics, retained messages, etc. 
+- Developer-centric:
+    - Most core broker code is now exported and accessible, for total developer control.
+    - Full-featured and flexible Hook-based interfacing system to provide easy 'plugin' development.
+    - Direct Packet Injection using special inline client, or masquerade as existing clients.
+- Performant and Stable:
+    - Our classic trie-based Topic-Subscription model.
+    - Client-specific write buffers to avoid issues with slow-reading or irregular client behaviour.
+    - Passes all [Paho Interoperability Tests](https://github.com/eclipse/paho.mqtt.testing/tree/master/interoperability) for MQTT v5 and MQTT v3.
+    - Over a thousand carefully considered unit test scenarios.
+- TCP, Websocket (including SSL/TLS), and $SYS Dashboard listeners.
+- Built-in Redis, Badger, and Bolt Persistence using Hooks (but you can also make your own).
+- Built-in Rule-based Authentication and ACL Ledger using Hooks (also make your own).
 
-#### Performance (messages/second)
-Performance benchmarks were tested using [MQTT-Stresser](https://github.com/inovex/mqtt-stresser) on a  13-inch, Early 2015 Macbook Pro (2.7 GHz Intel Core i5). Taking into account bursts of high and low throughput, the median scores are the most useful. Higher is better. 
+### Compatibility Notes
+Because of the overlap between the v5 specification and previous versions of mqtt, the server can accept both v5 and v3 clients, but note that in cases where both v5 an v3 clients are connected, properties and features provided for v5 clients will be downgraded for v3 clients (such as user properties).
 
-> As usual, any performance benchmarks should be taken with a pinch of salt, but are shown to demonstrate typical throughput compared to the other leading MQTT brokers.
+Support for MQTT v3.0.0 and v3.1.1 is considered hybrid-compatibility. Where not specifically restricted in the v3 specification, more modern and safety-first v5 behaviours are used instead - such as expiry for inflight and retained messages, and clients - and quality-of-service flow control limits.
 
-**Single Client, 10,000 messages**
+#### When is this repo updated?
+Unless it's a critical issue, new releases typically go out over the weekend. 
 
-![1 Client, 10,000 Messages](assets/benchmarkchart_1_10000.png "1 Client, 10,000 Messages")
+## Roadmap
+- Please [open an issue](https://github.com/mochi-mqtt/server/issues) to request new features or event hooks!
+- Cluster support.
+- Enhanced Metrics support.
 
-`mqtt-stresser -broker tcp://localhost:1883 -num-clients=1 -num-messages=10000`
-
-|              | Mochi     | Mosquitto   | EMQX     | VerneMQ   | Mosca   |  
-| :----------- | --------: | ----------: | -------: | --------: | --------:
-| SEND High    | 36505  |   30597  | 27202  | 32782  | 30125   |
-| SEND Low    |  36505    |  30597  | 27202   |  32782  | 30125  |
-| SEND Median  | 36505   | 30597   | 27202   |32782    | 30125  |
-| RECV High    | 152221  |  59130  | 7879   | 17551   | 9145   |
-| RECV Low    | 152221  | 59130   | 7879   |  17551    |  9145    |
-| RECV Median    | 152221  |  59130  | 7879   |  17551   |  9145   |
-
-**10 Clients, 1,000 Messages**
-
-![10 Clients, 1,000 Messages](assets/benchmarkchart_10_1000.png "10 Clients, 1,000 Messages")
-
-`mqtt-stresser -broker tcp://localhost:1883 -num-clients=10 -num-messages=1000`
-
-|              | Mochi     | Mosquitto   | EMQX     | VerneMQ   | Mosca   |  
-| :----------- | --------: | ----------: | -------: | --------: | --------:
-| SEND High    |  37193 | 	15775 |	17455 |	34138 |	36575  |
-| SEND Low    |   6529 |	6446 |	7714 |	8583 |	7383      |
-| SEND Median  |  15127 |	7813 | 	10305 |	9887 |	8169     |
-| RECV High    |  33535	 | 3710	| 3022 |	4534 |	9411    |
-| RECV Low    |   7484	| 2661	| 1689 |	2021 |	2275     |
-| RECV Median    |   11427 |  3142 | 1831 |	2468 |	4692      |
-
-**10 Clients, 10,000 Messages**
-
-![10 Clients, 10000 Messages](assets/benchmarkchart_10_10000.png "10 Clients, 10000 Messages")
-
-`mqtt-stresser -broker tcp://localhost:1883 -num-clients=10 -num-messages=10000`
-
-|              | Mochi     | Mosquitto   | EMQX     | VerneMQ   | Mosca   |  
-| :----------- | --------: | ----------: | -------: | --------: | --------:
-| SEND High    |   13153 |	13270 |	12229 |	13025 |	38446  |
-| SEND Low    |  8728	| 8513	| 8193 | 	6483 |	3889    |
-| SEND Median  |   9045	| 9532	| 9252 |	8031 |	9210    |
-| RECV High    |  20774	| 5052	| 2093 |	2071 | 	43008    |
-| RECV Low    |   10718	 |3995	| 1531	| 1673	| 18764   |
-| RECV Median    |  16339 |	4607 |	1620 | 	1907	| 33524  |
-
-**500 Clients, 100 Messages**
-
-![500 Clients, 100 Messages](assets/benchmarkchart_500_100.png "500 Clients, 100 Messages")
-
-`mqtt-stresser -broker tcp://localhost:1883 -num-clients=500 -num-messages=100`
-
-|              | Mochi     | Mosquitto   | EMQX     | VerneMQ   | Mosca   |  
-| :----------- | --------: | ----------: | -------: | --------: | --------:
-| SEND High    |  70688	| 72686	| 71392 |	75336 |	73192   |
-| SEND Low    |   1021	| 2577 |	1603 |	8417 |	2344  |
-| SEND Median  |  49871	| 33076 |	33637 |	35200 |	31312   |
-| RECV High    |  116163 |	4215 |	3427 |	5484 |	10100 |
-| RECV Low    |   1044	| 156 | 	56 | 	83	| 169   |
-| RECV Median    |     24398 | 208 |	94 |	413 |	474     |
-
-#### Using the Broker
-Mochi MQTT can be used as a standalone broker. Simply checkout this repository and run the `main.go` entrypoint in the `cmd` folder which will expose tcp (:1883), websocket (:1882), and dashboard (:8080) listeners. A docker image is coming soon.
+## Quick Start
+### Running the Broker with Go
+Mochi MQTT can be used as a standalone broker. Simply checkout this repository and run the [cmd/main.go](cmd/main.go) entrypoint in the [cmd](cmd) folder which will expose tcp (:1883), websocket (:1882), and dashboard (:8080) listeners.
 
 ```
 cd cmd
 go build -o mqtt && ./mqtt
 ```
 
-#### Quick Start
+### Using Docker
+You can now pull and run the [official Mochi MQTT image](https://hub.docker.com/r/mochimqtt/server) from our Docker repo:
 
+```sh
+docker pull mochimqtt/server
+or
+docker run -v $(pwd)/config.yaml:/config.yaml mochimqtt/server 
+```
+
+For most use cases, you can use File Based Configuration to configure the server, by specifying a valid `yaml` or `json` config file.
+
+A simple Dockerfile is provided for running the [cmd/main.go](cmd/main.go) Websocket, TCP, and Stats server, using the `allow-all` auth hook. 
+
+```sh
+docker build -t mochi:latest .
+docker run -p 1883:1883 -p 1882:1882 -p 8080:8080 -v $(pwd)/config.yaml:/config.yaml mochi:latest
+```
+
+### File Based Configuration
+You can use File Based Configuration with either the Docker image (described above), or by running the build binary with the `--config=config.yaml` or `--config=config.json` parameter.
+
+Configuration files provide a convenient mechanism for easily preparing a server with the most common configurations. You can enable and configure built-in hooks and listeners, and specify server options and compatibilities:
+
+```yaml
+listeners:
+  - type: "tcp"
+    id: "tcp12"
+    address: ":1883"
+  - type: "ws"
+    id: "ws1"
+    address: ":1882"
+  - type: "sysinfo"
+    id: "stats"
+    address: ":1880"
+hooks:
+  auth:
+    allow_all: true
+options:
+  inline_client: true
+```
+
+Please review the examples found in `examples/config` for all available configuration options.
+
+There are a few conditions to note:
+1. If you use file-based configuration, you can only have one of each hook type.
+2. You can only use built in hooks with file-based configuration, as the type and configuration structure needs to be known by the server in order for it to be applied.
+3. You can only use built in listeners, for the reasons above.
+
+If you need to implement custom hooks or listeners, please do so using the traditional manner indicated in `cmd/main.go`.
+
+## Developing with Mochi MQTT
+### Importing as a package
+Importing Mochi MQTT as a package requires just a few lines of code to get started.
 ``` go
 import (
-    mqtt "github.com/mochi-co/mqtt/server"
+  "log"
+
+  mqtt "github.com/mochi-mqtt/server/v2"
+  "github.com/mochi-mqtt/server/v2/hooks/auth"
+  "github.com/mochi-mqtt/server/v2/listeners"
 )
 
 func main() {
-    // Create the new MQTT Server.
-    server := mqtt.New()
-    
-    // Create a TCP listener on a standard port.
-    tcp := listeners.NewTCP("t1", ":1883")
-    
-    // Add the listener to the server with default options (nil).
-    err := server.AddListener(tcp, nil)
-	if err != nil {
-		log.Fatal(err)
-	}
-	
-	// Start the broker. Serve() is blocking - see examples folder 
-	// for usage ideas.
-    err = server.Serve()
-	if err != nil {
-		log.Fatal(err)
-	}
+  // Create signals channel to run server until interrupted
+  sigs := make(chan os.Signal, 1)
+  done := make(chan bool, 1)
+  signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+  go func() {
+    <-sigs
+    done <- true
+  }()
+
+  // Create the new MQTT Server.
+  server := mqtt.New(nil)
+  
+  // Allow all connections.
+  _ = server.AddHook(new(auth.AllowHook), nil)
+  
+  // Create a TCP listener on a standard port.
+  tcp := listeners.NewTCP("t1", ":1883", nil)
+  err := server.AddListener(tcp)
+  if err != nil {
+    log.Fatal(err)
+  }
+  
+
+  go func() {
+    err := server.Serve()
+    if err != nil {
+      log.Fatal(err)
+    }
+  }()
+
+  // Run server until interrupted
+  <-done
+
+  // Cleanup
 }
 ```
 
-Examples of running the broker with various configurations can be found in the `examples` folder. 
+Examples of running the broker with various configurations can be found in the [examples](examples) folder. 
 
 #### Network Listeners
 The server comes with a variety of pre-packaged network listeners which allow the broker to accept connections on different protocols. The current listeners are:
-- `listeners.NewTCP(id, address string)` - A TCP Listener, taking a unique ID and a network address to bind.
-- `listeners.NewWebsocket(id, address string)` A Websocket Listener
-- `listeners.NewHTTPStats()` An HTTP $SYS info dashboard
 
-##### Configuring Network Listeners
-When a listener is added to the server using `server.AddListener`, a `*listeners.Config` may be passed as the second argument.
+| Listener                     | Usage                                                                                        |
+|------------------------------|----------------------------------------------------------------------------------------------|
+| listeners.NewTCP             | A TCP listener                                                                               |
+| listeners.NewUnixSock        | A Unix Socket listener                                                                       |
+| listeners.NewNet             | A net.Listener listener                                                                      |
+| listeners.NewWebsocket       | A Websocket listener                                                                         |
+| listeners.NewHTTPStats       | An HTTP $SYS info dashboard                                                                  |
+| listeners.NewHTTPHealthCheck | An HTTP healthcheck listener to provide health check responses for e.g. cloud infrastructure |
 
-##### Authentication and ACL
-Authentication and ACL may be configured on a per-listener basis by providing an Auth Controller to the listener configuration. Custom Auth Controllers should satisfy the `auth.Controller` interface found in `listeners/auth`. Two default controllers are provided, `auth.Allow`, which allows all traffic, and `auth.Disallow`, which denies all traffic. 
+> Use the `listeners.Listener` interface to develop new listeners. If you do, please let us know!
+
+A `*listeners.Config` may be passed to configure TLS. 
+
+Examples of usage can be found in the [examples](examples) folder or [cmd/main.go](cmd/main.go).
+
+
+## Server Options and Capabilities
+A number of configurable options are available which can be used to alter the behaviour or restrict access to certain features in the server.
 
 ```go
-    err := server.AddListener(tcp, &listeners.Config{
-		Auth: new(auth.Allow),
-	})
+server := mqtt.New(&mqtt.Options{
+  Capabilities: mqtt.Capabilities{
+    MaximumSessionExpiryInterval: 3600,
+    Compatibilities: mqtt.Compatibilities{
+      ObscureNotAuthorized: true,
+    },
+  },
+  ClientNetWriteBufferSize: 4096,
+  ClientNetReadBufferSize: 4096,
+  SysTopicResendInterval: 10,
+  InlineClient: false,
+})
 ```
 
-> If no auth controller is provided in the listener configuration, the server will default to _Disallowing_ all traffic to prevent unintentional security issues.
+Review the mqtt.Options, mqtt.Capabilities, and mqtt.Compatibilities structs for a comprehensive list of options. `ClientNetWriteBufferSize` and `ClientNetReadBufferSize` can be configured to adjust memory usage per client, based on your needs.
+
+### Default Configuration Notes
+
+Some choices were made when deciding the default configuration that need to be mentioned here:
+
+- By default, the value of `server.Options.Capabilities.MaximumMessageExpiryInterval` is set to 86400 (24 hours), in order to prevent exposing the broker to DOS attacks on hostile networks when using the out-of-the-box configuration (as an infinite expiry would allow an infinite number of retained/inflight messages to accumulate). If you are operating in a trusted environment, or you have capacity for a larger retention period, you may wish to override this (set to `0` for no expiry).
+
+## Event Hooks 
+A universal event hooks system allows developers to hook into various parts of the server and client life cycle to add and modify functionality of the broker. These universal hooks are used to provide everything from authentication, persistent storage, to debugging tools.
+
+Hooks are stackable - you can add multiple hooks to a server, and they will be run in the order they were added. Some hooks modify values, and these modified values will be passed to the subsequent hooks before being returned to the runtime code.
+
+| Type           | Import                                                                   | Info                                                                       |
+|----------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------|
+| Access Control | [mochi-mqtt/server/hooks/auth . AllowHook](hooks/auth/allow_all.go)      | Allow access to all connecting clients and read/write to  all topics.      | 
+| Access Control | [mochi-mqtt/server/hooks/auth . Auth](hooks/auth/auth.go)                | Rule-based access control ledger.                                          | 
+| Persistence    | [mochi-mqtt/server/hooks/storage/bolt](hooks/storage/bolt/bolt.go)       | Persistent storage using [BoltDB](https://dbdb.io/db/boltdb) (deprecated). | 
+| Persistence    | [mochi-mqtt/server/hooks/storage/badger](hooks/storage/badger/badger.go) | Persistent storage using [BadgerDB](https://github.com/dgraph-io/badger).  | 
+| Persistence    | [mochi-mqtt/server/hooks/storage/redis](hooks/storage/redis/redis.go)    | Persistent storage using [Redis](https://redis.io).                        | 
+| Debugging      | [mochi-mqtt/server/hooks/debug](hooks/debug/debug.go)                    | Additional debugging output to visualise packet flow.                      | 
+
+Many of the internal server functions are now exposed to developers, so you can make your own Hooks by using the above as examples. If you do, please [Open an issue](https://github.com/mochi-mqtt/server/issues) and let everyone know!
+
+### Access Control 
+#### Allow Hook
+By default, Mochi MQTT uses a DENY-ALL access control rule. To allow connections, this must overwritten using an Access Control hook. The simplest of these hooks is the `auth.AllowAll` hook, which provides ALLOW-ALL rules to all connections, subscriptions, and publishing. It's also the simplest hook to use:
 
-##### SSL
-SSL may be configured on both the TCP and Websocket listeners by providing a public-private PEM key pair to the listener configuration as `[]byte` slices.
 ```go
-    err := server.AddListener(tcp, &listeners.Config{
-		Auth: new(auth.Allow),
-		TLS: &listeners.TLS{
-			Certificate: publicCertificate, 
-			PrivateKey:  privateKey,
-		},
-	})
+server := mqtt.New(nil)
+_ = server.AddHook(new(auth.AllowHook), nil)
 ```
-> Note the mandatory inclusion of the Auth Controller!
 
-#### Data Persistence
-Mochi MQTT provides a `persistence.Store` interface for developing and attaching persistent stores to the broker. The default persistence mechanism packaged with the broker is backed by [Bolt](https://github.com/etcd-io/bbolt) and can be enabled by assigning a `*bolt.Store` to the server.
+> Don't do this if you are exposing your server to the internet or untrusted networks - it should really be used for development, testing, and debugging only.
+
+#### Auth Ledger
+The Auth Ledger hook provides a sophisticated mechanism for defining access rules in a struct format. Auth ledger rules come in two forms: Auth rules (connection), and ACL rules (publish subscribe). 
+
+Auth rules have 4 optional criteria and an assertion flag:
+| Criteria | Usage | 
+| -- | -- |
+| Client | client id of the connecting client |
+| Username | username of the connecting client |
+| Password | password of the connecting client |
+| Remote | the remote address or ip of the client |
+| Allow | true (allow this user) or false (deny this user) | 
+
+ACL rules have 3 optional criteria and an filter match:
+| Criteria | Usage | 
+| -- | -- |
+| Client | client id of the connecting client |
+| Username | username of the connecting client |
+| Remote | the remote address or ip of the client |
+| Filters | an array of filters to match |
+
+Rules are processed in index order (0,1,2,3), returning on the first matching rule. See [hooks/auth/ledger.go](hooks/auth/ledger.go) to review the structs.
+
 ```go
-    // import "github.com/mochi-co/mqtt/server/persistence/bolt"
-    err = server.AddStore(bolt.New("mochi.db", nil))
-	if err != nil {
-		log.Fatal(err)
-	}
+server := mqtt.New(nil)
+err := server.AddHook(new(auth.Hook), &auth.Options{
+    Ledger: &auth.Ledger{
+    Auth: auth.AuthRules{ // Auth disallows all by default
+      {Username: "peach", Password: "password1", Allow: true},
+      {Username: "melon", Password: "password2", Allow: true},
+      {Remote: "127.0.0.1:*", Allow: true},
+      {Remote: "localhost:*", Allow: true},
+    },
+    ACL: auth.ACLRules{ // ACL allows all by default
+      {Remote: "127.0.0.1:*"}, // local superuser allow all
+      {
+        // user melon can read and write to their own topic
+        Username: "melon", Filters: auth.Filters{
+          "melon/#":   auth.ReadWrite,
+          "updates/#": auth.WriteOnly, // can write to updates, but can't read updates from others
+        },
+      },
+      {
+        // Otherwise, no clients have publishing permissions
+        Filters: auth.Filters{
+          "#":         auth.ReadOnly,
+          "updates/#": auth.Deny,
+        },
+      },
+    },
+  }
+})
+```
+
+The ledger can also be stored as JSON or YAML and loaded using the Data field:
+```go
+err := server.AddHook(new(auth.Hook), &auth.Options{
+    Data: data, // build ledger from byte slice: yaml or json
+})
+```
+See [examples/auth/encoded/main.go](examples/auth/encoded/main.go) for more information.
+
+### Persistent Storage 
+#### Redis
+A basic Redis storage hook is available which provides persistence for the broker. It can be added to the server in the same fashion as any other hook, with several options. It uses github.com/go-redis/redis/v8 under the hook, and is completely configurable through the Options value. 
+```go
+err := server.AddHook(new(redis.Hook), &redis.Options{
+  Options: &rv8.Options{
+    Addr:     "localhost:6379", // default redis address
+    Password: "",               // your password
+    DB:       0,                // your redis db
+  },
+})
+if err != nil {
+  log.Fatal(err)
+}
+```
+For more information on how the redis hook works, or how to use it, see the [examples/persistence/redis/main.go](examples/persistence/redis/main.go) or [hooks/storage/redis](hooks/storage/redis) code.
+
+#### Badger DB
+There's also a BadgerDB storage hook if you prefer file based storage. It can be added and configured in much the same way as the other hooks (with somewhat less options).
+```go
+err := server.AddHook(new(badger.Hook), &badger.Options{
+  Path: badgerPath,
+})
+if err != nil {
+  log.Fatal(err)
+}
+```
+For more information on how the badger hook works, or how to use it, see the [examples/persistence/badger/main.go](examples/persistence/badger/main.go) or [hooks/storage/badger](hooks/storage/badger) code.
+
+There is also a BoltDB hook which has been deprecated in favour of Badger, but if you need it, check [examples/persistence/bolt/main.go](examples/persistence/bolt/main.go).
+
+## Developing with Event Hooks
+Many hooks are available for interacting with the broker and client lifecycle. 
+The function signatures for all the hooks and `mqtt.Hook` interface can be found in [hooks.go](hooks.go).
+
+> The most flexible event hooks are OnPacketRead, OnPacketEncode, and OnPacketSent - these hooks be used to control and modify all incoming and outgoing packets.
+
+| Function               | Usage                                                                                                                                                                                                                                                                                                      | 
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| OnStarted              | Called when the server has successfully started.                                                                                                                                                                                                                                                           |
+| OnStopped              | Called when the server has successfully stopped.                                                                                                                                                                                                                                                           | 
+| OnConnectAuthenticate  | Called when a user attempts to authenticate with the server. An implementation of this method MUST be used to allow or deny access to the server (see hooks/auth/allow_all or basic). It can be used in custom hooks to check connecting users against an existing user database. Returns true if allowed. |
+| OnACLCheck             | Called when a user attempts to publish or subscribe to a topic filter. As above.                                                                                                                                                                                                                           |
+| OnSysInfoTick          | Called when the $SYS topic values are published out.                                                                                                                                                                                                                                                       |
+| OnConnect              | Called when a new client connects, may return an error or packet code to halt the client connection process.                                                                                                                                                                                               | 
+| OnSessionEstablish     | Called immediately after a new client connects and authenticates and immediately before the session is established and CONNACK is sent.                                                                                                                                                                    |
+| OnSessionEstablished   | Called when a new client successfully establishes a session (after OnConnect)                                                                                                                                                                                                                              | 
+| OnDisconnect           | Called when a client is disconnected for any reason.                                                                                                                                                                                                                                                       | 
+| OnAuthPacket           | Called when an auth packet is received. It is intended to allow developers to create their own mqtt v5 Auth Packet handling mechanisms. Allows packet modification.                                                                                                                                        | 
+| OnPacketRead           | Called when a packet is received from a client. Allows packet modification.                                                                                                                                                                                                                                | 
+| OnPacketEncode         | Called immediately before a packet is encoded to be sent to a client. Allows packet modification.                                                                                                                                                                                                          | 
+| OnPacketSent           | Called when a packet has been sent to a client.                                                                                                                                                                                                                                                            | 
+| OnPacketProcessed      | Called when a packet has been received and successfully handled by the broker.                                                                                                                                                                                                                             | 
+| OnSubscribe            | Called when a client subscribes to one or more filters. Allows packet modification.                                                                                                                                                                                                                        | 
+| OnSubscribed           | Called when a client successfully subscribes to one or more filters.                                                                                                                                                                                                                                       | 
+| OnSelectSubscribers    | Called when subscribers have been collected for a topic, but before shared subscription subscribers have been selected. Allows receipient modification.                                                                                                                                                    | 
+| OnUnsubscribe          | Called when a client unsubscribes from one or more filters. Allows packet modification.                                                                                                                                                                                                                    | 
+| OnUnsubscribed         | Called when a client successfully unsubscribes from one or more filters.                                                                                                                                                                                                                                   | 
+| OnPublish              | Called when a client publishes a message. Allows packet modification.                                                                                                                                                                                                                                      | 
+| OnPublished            | Called when a client has published a message to subscribers.                                                                                                                                                                                                                                               | 
+| OnPublishDropped       | Called when a message to a client is dropped before delivery, such as if the client is taking too long to respond.                                                                                                                                                                                         | 
+| OnRetainMessage        | Called then a published message is retained.                                                                                                                                                                                                                                                               | 
+| OnRetainPublished      | Called then a retained message is published to a client.                                                                                                                                                                                                                                                   | 
+| OnQosPublish           | Called when a publish packet with Qos >= 1 is issued to a subscriber.                                                                                                                                                                                                                                      | 
+| OnQosComplete          | Called when the Qos flow for a message has been completed.                                                                                                                                                                                                                                                 | 
+| OnQosDropped           | Called when an inflight message expires before completion.                                                                                                                                                                                                                                                 | 
+| OnPacketIDExhausted    | Called when a client runs out of unused packet ids to assign.                                                                                                                                                                                                                                              | 
+| OnWill                 | Called when a client disconnects and intends to issue a will message. Allows packet modification.                                                                                                                                                                                                          | 
+| OnWillSent             | Called when an LWT message has been issued from a disconnecting client.                                                                                                                                                                                                                                    | 
+| OnClientExpired        | Called when a client session has expired and should be deleted.                                                                                                                                                                                                                                            | 
+| OnRetainedExpired      | Called when a retained message has expired and should be deleted.                                                                                                                                                                                                                                          | 
+| StoredClients          | Returns clients, eg. from a persistent store.                                                                                                                                                                                                                                                              | 
+| StoredSubscriptions    | Returns client subscriptions, eg. from a persistent store.                                                                                                                                                                                                                                                 | 
+| StoredInflightMessages | Returns inflight messages, eg. from a persistent store.                                                                                                                                                                                                                                                    | 
+| StoredRetainedMessages | Returns retained messages, eg. from a persistent store.                                                                                                                                                                                                                                                    | 
+| StoredSysInfo          | Returns stored system info values, eg. from a persistent store.                                                                                                                                                                                                                                            | 
+
+If you are building a persistent storage hook, see the existing persistent hooks for inspiration and patterns. If you are building an auth hook, you will need `OnACLCheck` and `OnConnectAuthenticate`.
+
+### Inline Client (v2.4.0+)
+It's now possible to subscribe and publish to topics directly from the embedding code, by using the `inline client` feature. The Inline Client is an embedded client which operates as part of the server, and can be enabled in the server options:
+```go
+server := mqtt.New(&mqtt.Options{
+  InlineClient: true,
+})
+```
+Once enabled, you will be able to use the `server.Publish`, `server.Subscribe`, and `server.Unsubscribe` methods to issue and received messages from broker-adjacent code.
+
+> See [direct examples](examples/direct/main.go) for real-life usage examples.
+
+#### Inline Publish
+To publish basic message to a topic from within the embedding application, you can use the `server.Publish(topic string, payload []byte, retain bool, qos byte) error` method.
+
+```go
+err := server.Publish("direct/publish", []byte("packet scheduled message"), false, 0)
+```
+> The Qos byte in this case is only used to set the upper qos limit available for subscribers, as per MQTT v5 spec.
+
+#### Inline Subscribe
+To subscribe to a topic filter from within the embedding application, you can use the `server.Subscribe(filter string, subscriptionId int, handler InlineSubFn) error` method with a callback function. Note that only QoS 0 is supported for inline subscriptions. If you wish to have multiple callbacks for the same filter, you can use the MQTTv5 `subscriptionId` property to differentiate.
+
+```go
+callbackFn := func(cl *mqtt.Client, sub packets.Subscription, pk packets.Packet) {
+    server.Log.Info("inline client received message from subscription", "client", cl.ID, "subscriptionId", sub.Identifier, "topic", pk.TopicName, "payload", string(pk.Payload))
+}
+server.Subscribe("direct/#", 1, callbackFn)
+```
+
+#### Inline Unsubscribe
+You may wish to unsubscribe if you have subscribed to a filter using the inline client. You can do this easily with the `server.Unsubscribe(filter string, subscriptionId int) error` method:
+
+```go
+server.Unsubscribe("direct/#", 1)
+```
+
+### Packet Injection
+If you want more control, or want to set specific MQTT v5 properties and other values you can create your own publish packets from a client of your choice. This method allows you to inject MQTT packets (no just publish) directly into the runtime as though they had been received by a specific client. 
+
+Packet injection can be used for any MQTT packet, including ping requests, subscriptions, etc. And because the Clients structs and methods are now exported, you can even inject packets on behalf of a connected client (if you have a very custom requirements).
+
+Most of the time you'll want to use the Inline Client described above, as it has unique privileges: it bypasses all ACL and topic validation checks, meaning it can even publish to $SYS topics. In this case, you can create an inline client from scratch which will behave the same as the built-in inline client.
+
+```go
+cl := server.NewClient(nil, "local", "inline", true)
+server.InjectPacket(cl, packets.Packet{
+  FixedHeader: packets.FixedHeader{
+    Type: packets.Publish,
+  },
+  TopicName: "direct/publish",
+  Payload: []byte("scheduled message"),
+})
+```
+
+> MQTT packets still need to be correctly formed, so refer our [the test packets catalogue](packets/tpackets.go) and [MQTTv5 Specification](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html) for inspiration.
+
+See the [hooks example](examples/hooks/main.go) to see this feature in action.
+
+
+### Testing
+#### Unit Tests
+Mochi MQTT tests over a thousand scenarios with thoughtfully hand written unit tests to ensure each function does exactly what we expect. You can run the tests using go:
+```
+go run --cover ./...
 ```
-> Persistence is on-demand (not flushed) and will potentially reduce throughput when compared to the standard in-memory store. Only use it if you need to maintain state through restarts.
 
 #### Paho Interoperability Test
-You can check the broker against the [Paho Interoperability Test](https://github.com/eclipse/paho.mqtt.testing/tree/master/interoperability) by starting the broker using `examples/paho/main.go`, and then running the test with `python3 client_test.py` from the _interoperability_ folder.
+You can check the broker against the [Paho Interoperability Test](https://github.com/eclipse/paho.mqtt.testing/tree/master/interoperability) by starting the broker using `examples/paho/main.go`, and then running the mqtt v5 and v3 tests with `python3 client_test5.py` from the _interoperability_ folder. 
 
-## Contributions
-Contributions and feedback are both welcomed and encouraged! Open an [issue](https://github.com/mochi-co/mqtt/issues) to report a bug, ask a question, or make a feature request.
+> Note that there are currently a number of outstanding issues regarding false negatives in the paho suite, and as such, certain compatibility modes are enabled in the `paho/main.go` example.
 
 
+## Performance Benchmarks
+Mochi MQTT performance is comparable with popular brokers such as Mosquitto, EMQX, and others.
+
+Performance benchmarks were tested using [MQTT-Stresser](https://github.com/inovex/mqtt-stresser) on a Apple Macbook Air M2, using `cmd/main.go` default settings. Taking into account bursts of high and low throughput, the median scores are the most useful. Higher is better.
+
+> The values presented in the benchmark are not representative of true messages per second throughput. They rely on an unusual calculation by mqtt-stresser, but are usable as they are consistent across all brokers.
+> Benchmarks are provided as a general performance expectation guideline only. Comparisons are performed using out-of-the-box default configurations.
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=2 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10      | 124,772 | 125,456 | 124,614 | 314,461 | 313,186 | 311,910 |
+| [Mosquitto v2.0.15](https://github.com/eclipse/mosquitto) | 155,920 | 155,919 | 155,918 | 185,485 | 185,097 | 184,709 |
+| [EMQX v5.0.11](https://github.com/emqx/emqx)      | 156,945 | 156,257 | 155,568 | 17,918 | 17,783 | 17,649 |
+| [Rumqtt v0.21.0](https://github.com/bytebeamio/rumqtt) | 112,208 | 108,480 | 104,753 | 135,784 | 126,446 | 117,108 |
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=10 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10      | 41,825 | 31,663| 23,008 | 144,058 | 65,903 | 37,618 |
+| Mosquitto v2.0.15 | 42,729 | 38,633 | 29,879 | 23,241 | 19,714 | 18,806 |
+| EMQX v5.0.11      | 21,553 | 17,418 | 14,356 | 4,257 | 3,980 | 3,756 |
+| Rumqtt v0.21.0    | 42,213 | 23,153 | 20,814 | 49,465 | 36,626 | 19,283 |
+
+Million Message Challenge (hit the server with 1 million messages immediately):
+
+`mqtt-stresser -broker tcp://localhost:1883 -num-clients=100 -num-messages=10000`
+| Broker            | publish fastest | median | slowest | receive fastest | median | slowest | 
+| --                | --             | --   | --   | --             | --   | --   |
+| Mochi v2.2.10     | 13,532 | 4,425 | 2,344 | 52,120 | 7,274 | 2,701 |
+| Mosquitto v2.0.15 | 3,826 | 3,395 | 3,032 | 1,200 | 1,150 | 1,118 |
+| EMQX v5.0.11      | 4,086 | 2,432 | 2,274 | 434 | 333 | 311 |
+| Rumqtt v0.21.0    | 78,972 | 5,047 | 3,804 | 4,286 | 3,249 | 2,027 |
+
+> Not sure what's going on with EMQX here, perhaps the docker out-of-the-box settings are not optimal, so take it with a pinch of salt as we know for a fact it's a solid piece of software.
+
+## Contribution Guidelines
+Contributions and feedback are both welcomed and encouraged! [Open an issue](https://github.com/mochi-mqtt/server/issues) to report a bug, ask a question, or make a feature request. If you open a pull request, please try to follow the following guidelines:
+- Try to maintain test coverage where reasonably possible.
+- Clearly state what the PR does and why.
+- Please remember to add your SPDX FileContributor tag to files where you have made a meaningful contribution.
+
+[SPDX Annotations](https://spdx.dev) are used to clearly indicate the license, copyright, and contributions of each file in a machine-readable format. If you are adding a new file to the repository, please ensure it has the following SPDX header:
+```go
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt
+// SPDX-FileContributor: Your name or alias <optional@email.address>
+
+package name
+```
+
+Please ensure to add a new `SPDX-FileContributor` line for each contributor to the file. Refer to other files for examples. Please remember to do this, your contributions to this project are valuable and appreciated - it's important to receive credit! 
+
+## Stargazers over time 🥰
+[![Stargazers over time](https://starchart.cc/mochi-mqtt/server.svg)](https://starchart.cc/mochi-mqtt/server)
+Are you using Mochi MQTT in a project? [Let us know!](https://github.com/mochi-mqtt/server/issues)
 

clients.go

@@ -0,0 +1,644 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package mqtt
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/rs/xid"
+
+	"github.com/mochi-mqtt/server/v2/packets"
+)
+
+const (
+	defaultKeepalive             uint16 = 10 // the default connection keepalive value in seconds.
+	defaultClientProtocolVersion byte   = 4  // the default mqtt protocol version of connecting clients (if somehow unspecified).
+	minimumKeepalive             uint16 = 5  // the minimum recommended keepalive - values under with display a warning.
+)
+
+var (
+	ErrMinimumKeepalive = errors.New("client keepalive is below minimum recommended value and may exhibit connection instability")
+)
+
+// ReadFn is the function signature for the function used for reading and processing new packets.
+type ReadFn func(*Client, packets.Packet) error
+
+// Clients contains a map of the clients known by the broker.
+type Clients struct {
+	internal map[string]*Client // clients known by the broker, keyed on client id.
+	sync.RWMutex
+}
+
+// NewClients returns an instance of Clients.
+func NewClients() *Clients {
+	return &Clients{
+		internal: make(map[string]*Client),
+	}
+}
+
+// Add adds a new client to the clients map, keyed on client id.
+func (cl *Clients) Add(val *Client) {
+	cl.Lock()
+	defer cl.Unlock()
+	cl.internal[val.ID] = val
+}
+
+// GetAll returns all the clients.
+func (cl *Clients) GetAll() map[string]*Client {
+	cl.RLock()
+	defer cl.RUnlock()
+	m := map[string]*Client{}
+	for k, v := range cl.internal {
+		m[k] = v
+	}
+	return m
+}
+
+// Get returns the value of a client if it exists.
+func (cl *Clients) Get(id string) (*Client, bool) {
+	cl.RLock()
+	defer cl.RUnlock()
+	val, ok := cl.internal[id]
+	return val, ok
+}
+
+// Len returns the length of the clients map.
+func (cl *Clients) Len() int {
+	cl.RLock()
+	defer cl.RUnlock()
+	val := len(cl.internal)
+	return val
+}
+
+// Delete removes a client from the internal map.
+func (cl *Clients) Delete(id string) {
+	cl.Lock()
+	defer cl.Unlock()
+	delete(cl.internal, id)
+}
+
+// GetByListener returns clients matching a listener id.
+func (cl *Clients) GetByListener(id string) []*Client {
+	cl.RLock()
+	defer cl.RUnlock()
+	clients := make([]*Client, 0, cl.Len())
+	for _, client := range cl.internal {
+		if client.Net.Listener == id && !client.Closed() {
+			clients = append(clients, client)
+		}
+	}
+	return clients
+}
+
+// Client contains information about a client known by the broker.
+type Client struct {
+	Properties   ClientProperties // client properties
+	State        ClientState      // the operational state of the client.
+	Net          ClientConnection // network connection state of the client
+	ID           string           // the client id.
+	ops          *ops             // ops provides a reference to server ops.
+	sync.RWMutex                  // mutex
+}
+
+// ClientConnection contains the connection transport and metadata for the client.
+type ClientConnection struct {
+	Conn     net.Conn      // the net.Conn used to establish the connection
+	bconn    *bufio.Reader // a buffered net.Conn for reading packets
+	outbuf   *bytes.Buffer // a buffer for writing packets
+	Remote   string        // the remote address of the client
+	Listener string        // listener id of the client
+	Inline   bool          // if true, the client is the built-in 'inline' embedded client
+}
+
+// ClientProperties contains the properties which define the client behaviour.
+type ClientProperties struct {
+	Props           packets.Properties
+	Will            Will
+	Username        []byte
+	ProtocolVersion byte
+	Clean           bool
+}
+
+// Will contains the last will and testament details for a client connection.
+type Will struct {
+	Payload           []byte                 // -
+	User              []packets.UserProperty // -
+	TopicName         string                 // -
+	Flag              uint32                 // 0,1
+	WillDelayInterval uint32                 // -
+	Qos               byte                   // -
+	Retain            bool                   // -
+}
+
+// ClientState tracks the state of the client.
+type ClientState struct {
+	TopicAliases    TopicAliases         // a map of topic aliases
+	stopCause       atomic.Value         // reason for stopping
+	Inflight        *Inflight            // a map of in-flight qos messages
+	Subscriptions   *Subscriptions       // a map of the subscription filters a client maintains
+	disconnected    int64                // the time the client disconnected in unix time, for calculating expiry
+	outbound        chan *packets.Packet // queue for pending outbound packets
+	endOnce         sync.Once            // only end once
+	isTakenOver     uint32               // used to identify orphaned clients
+	packetID        uint32               // the current highest packetID
+	open            context.Context      // indicate that the client is open for packet exchange
+	cancelOpen      context.CancelFunc   // cancel function for open context
+	outboundQty     int32                // number of messages currently in the outbound queue
+	Keepalive       uint16               // the number of seconds the connection can wait
+	ServerKeepalive bool                 // keepalive was set by the server
+}
+
+// newClient returns a new instance of Client. This is almost exclusively used by Server
+// for creating new clients, but it lives here because it's not dependent.
+func newClient(c net.Conn, o *ops) *Client {
+	ctx, cancel := context.WithCancel(context.Background())
+	cl := &Client{
+		State: ClientState{
+			Inflight:      NewInflights(),
+			Subscriptions: NewSubscriptions(),
+			TopicAliases:  NewTopicAliases(o.options.Capabilities.TopicAliasMaximum),
+			open:          ctx,
+			cancelOpen:    cancel,
+			Keepalive:     defaultKeepalive,
+			outbound:      make(chan *packets.Packet, o.options.Capabilities.MaximumClientWritesPending),
+		},
+		Properties: ClientProperties{
+			ProtocolVersion: defaultClientProtocolVersion, // default protocol version
+		},
+		ops: o,
+	}
+
+	if c != nil {
+		cl.Net = ClientConnection{
+			Conn:   c,
+			bconn:  bufio.NewReaderSize(c, o.options.ClientNetReadBufferSize),
+			Remote: c.RemoteAddr().String(),
+		}
+	}
+
+	return cl
+}
+
+// WriteLoop ranges over pending outbound messages and writes them to the client connection.
+func (cl *Client) WriteLoop() {
+	for {
+		select {
+		case pk := <-cl.State.outbound:
+			if err := cl.WritePacket(*pk); err != nil {
+				// TODO : Figure out what to do with error
+				cl.ops.log.Debug("failed publishing packet", "error", err, "client", cl.ID, "packet", pk)
+			}
+			atomic.AddInt32(&cl.State.outboundQty, -1)
+		case <-cl.State.open.Done():
+			return
+		}
+	}
+}
+
+// ParseConnect parses the connect parameters and properties for a client.
+func (cl *Client) ParseConnect(lid string, pk packets.Packet) {
+	cl.Net.Listener = lid
+
+	cl.Properties.ProtocolVersion = pk.ProtocolVersion
+	cl.Properties.Username = pk.Connect.Username
+	cl.Properties.Clean = pk.Connect.Clean
+	cl.Properties.Props = pk.Properties.Copy(false)
+
+	if cl.Properties.Props.ReceiveMaximum > cl.ops.options.Capabilities.MaximumInflight { // 3.3.4 Non-normative
+		cl.Properties.Props.ReceiveMaximum = cl.ops.options.Capabilities.MaximumInflight
+	}
+
+	if pk.Connect.Keepalive <= minimumKeepalive {
+		cl.ops.log.Warn(
+			ErrMinimumKeepalive.Error(),
+			"client", cl.ID,
+			"keepalive", pk.Connect.Keepalive,
+			"recommended", minimumKeepalive,
+		)
+	}
+
+	cl.State.Keepalive = pk.Connect.Keepalive                                              // [MQTT-3.2.2-22]
+	cl.State.Inflight.ResetReceiveQuota(int32(cl.ops.options.Capabilities.ReceiveMaximum)) // server receive max per client
+	cl.State.Inflight.ResetSendQuota(int32(cl.Properties.Props.ReceiveMaximum))            // client receive max
+	cl.State.TopicAliases.Outbound = NewOutboundTopicAliases(cl.Properties.Props.TopicAliasMaximum)
+
+	cl.ID = pk.Connect.ClientIdentifier
+	if cl.ID == "" {
+		cl.ID = xid.New().String() // [MQTT-3.1.3-6] [MQTT-3.1.3-7]
+		cl.Properties.Props.AssignedClientID = cl.ID
+	}
+
+	if pk.Connect.WillFlag {
+		cl.Properties.Will = Will{
+			Qos:               pk.Connect.WillQos,
+			Retain:            pk.Connect.WillRetain,
+			Payload:           pk.Connect.WillPayload,
+			TopicName:         pk.Connect.WillTopic,
+			WillDelayInterval: pk.Connect.WillProperties.WillDelayInterval,
+			User:              pk.Connect.WillProperties.User,
+		}
+		if pk.Properties.SessionExpiryIntervalFlag &&
+			pk.Properties.SessionExpiryInterval < pk.Connect.WillProperties.WillDelayInterval {
+			cl.Properties.Will.WillDelayInterval = pk.Properties.SessionExpiryInterval
+		}
+		if pk.Connect.WillFlag {
+			cl.Properties.Will.Flag = 1 // atomic for checking
+		}
+	}
+}
+
+// refreshDeadline refreshes the read/write deadline for the net.Conn connection.
+func (cl *Client) refreshDeadline(keepalive uint16) {
+	var expiry time.Time // nil time can be used to disable deadline if keepalive = 0
+	if keepalive > 0 {
+		expiry = time.Now().Add(time.Duration(keepalive+(keepalive/2)) * time.Second) // [MQTT-3.1.2-22]
+	}
+
+	if cl.Net.Conn != nil {
+		_ = cl.Net.Conn.SetDeadline(expiry) // [MQTT-3.1.2-22]
+	}
+}
+
+// NextPacketID returns the next available (unused) packet id for the client.
+// If no unused packet ids are available, an error is returned and the client
+// should be disconnected.
+func (cl *Client) NextPacketID() (i uint32, err error) {
+	cl.Lock()
+	defer cl.Unlock()
+
+	i = atomic.LoadUint32(&cl.State.packetID)
+	started := i
+	overflowed := false
+	for {
+		if overflowed && i == started {
+			return 0, packets.ErrQuotaExceeded
+		}
+
+		if i >= cl.ops.options.Capabilities.maximumPacketID {
+			overflowed = true
+			i = 0
+			continue
+		}
+
+		i++
+
+		if _, ok := cl.State.Inflight.Get(uint16(i)); !ok {
+			atomic.StoreUint32(&cl.State.packetID, i)
+			return i, nil
+		}
+	}
+}
+
+// ResendInflightMessages attempts to resend any pending inflight messages to connected clients.
+func (cl *Client) ResendInflightMessages(force bool) error {
+	if cl.State.Inflight.Len() == 0 {
+		return nil
+	}
+
+	for _, tk := range cl.State.Inflight.GetAll(false) {
+		if tk.FixedHeader.Type == packets.Publish {
+			tk.FixedHeader.Dup = true // [MQTT-3.3.1-1] [MQTT-3.3.1-3]
+		}
+
+		cl.ops.hooks.OnQosPublish(cl, tk, tk.Created, 0)
+		err := cl.WritePacket(tk)
+		if err != nil {
+			return err
+		}
+
+		if tk.FixedHeader.Type == packets.Puback || tk.FixedHeader.Type == packets.Pubcomp {
+			if ok := cl.State.Inflight.Delete(tk.PacketID); ok {
+				cl.ops.hooks.OnQosComplete(cl, tk)
+				atomic.AddInt64(&cl.ops.info.Inflight, -1)
+			}
+		}
+	}
+
+	return nil
+}
+
+// ClearInflights deletes all inflight messages for the client, e.g. for a disconnected user with a clean session.
+func (cl *Client) ClearInflights() {
+	for _, tk := range cl.State.Inflight.GetAll(false) {
+		if ok := cl.State.Inflight.Delete(tk.PacketID); ok {
+			cl.ops.hooks.OnQosDropped(cl, tk)
+			atomic.AddInt64(&cl.ops.info.Inflight, -1)
+		}
+	}
+}
+
+// ClearExpiredInflights deletes any inflight messages which have expired.
+func (cl *Client) ClearExpiredInflights(now, maximumExpiry int64) []uint16 {
+	deleted := []uint16{}
+	for _, tk := range cl.State.Inflight.GetAll(false) {
+		expired := tk.ProtocolVersion == 5 && tk.Expiry > 0 && tk.Expiry < now // [MQTT-3.3.2-5]
+
+		// If the maximum message expiry interval is set (greater than 0), and the message
+		// retention period exceeds the maximum expiry, the message will be forcibly removed.
+		enforced := maximumExpiry > 0 && now-tk.Created > maximumExpiry
+
+		if expired || enforced {
+			if ok := cl.State.Inflight.Delete(tk.PacketID); ok {
+				cl.ops.hooks.OnQosDropped(cl, tk)
+				atomic.AddInt64(&cl.ops.info.Inflight, -1)
+				deleted = append(deleted, tk.PacketID)
+			}
+		}
+	}
+
+	return deleted
+}
+
+// Read reads incoming packets from the connected client and transforms them into
+// packets to be handled by the packetHandler.
+func (cl *Client) Read(packetHandler ReadFn) error {
+	var err error
+
+	for {
+		if cl.Closed() {
+			return nil
+		}
+
+		cl.refreshDeadline(cl.State.Keepalive)
+		fh := new(packets.FixedHeader)
+		err = cl.ReadFixedHeader(fh)
+		if err != nil {
+			return err
+		}
+
+		pk, err := cl.ReadPacket(fh)
+		if err != nil {
+			return err
+		}
+
+		err = packetHandler(cl, pk) // Process inbound packet.
+		if err != nil {
+			return err
+		}
+	}
+}
+
+// Stop instructs the client to shut down all processing goroutines and disconnect.
+func (cl *Client) Stop(err error) {
+	cl.State.endOnce.Do(func() {
+
+		if cl.Net.Conn != nil {
+			_ = cl.Net.Conn.Close() // omit close error
+		}
+
+		if err != nil {
+			cl.State.stopCause.Store(err)
+		}
+
+		if cl.State.cancelOpen != nil {
+			cl.State.cancelOpen()
+		}
+
+		atomic.StoreInt64(&cl.State.disconnected, time.Now().Unix())
+	})
+}
+
+// StopCause returns the reason the client connection was stopped, if any.
+func (cl *Client) StopCause() error {
+	if cl.State.stopCause.Load() == nil {
+		return nil
+	}
+	return cl.State.stopCause.Load().(error)
+}
+
+// Closed returns true if client connection is closed.
+func (cl *Client) Closed() bool {
+	return cl.State.open == nil || cl.State.open.Err() != nil
+}
+
+// ReadFixedHeader reads in the values of the next packet's fixed header.
+func (cl *Client) ReadFixedHeader(fh *packets.FixedHeader) error {
+	if cl.Net.bconn == nil {
+		return ErrConnectionClosed
+	}
+
+	b, err := cl.Net.bconn.ReadByte()
+	if err != nil {
+		return err
+	}
+
+	err = fh.Decode(b)
+	if err != nil {
+		return err
+	}
+
+	var bu int
+	fh.Remaining, bu, err = packets.DecodeLength(cl.Net.bconn)
+	if err != nil {
+		return err
+	}
+
+	if cl.ops.options.Capabilities.MaximumPacketSize > 0 && uint32(fh.Remaining+1) > cl.ops.options.Capabilities.MaximumPacketSize {
+		return packets.ErrPacketTooLarge // [MQTT-3.2.2-15]
+	}
+
+	atomic.AddInt64(&cl.ops.info.BytesReceived, int64(bu+1))
+	return nil
+}
+
+// ReadPacket reads the remaining buffer into an MQTT packet.
+func (cl *Client) ReadPacket(fh *packets.FixedHeader) (pk packets.Packet, err error) {
+	atomic.AddInt64(&cl.ops.info.PacketsReceived, 1)
+
+	pk.ProtocolVersion = cl.Properties.ProtocolVersion // inherit client protocol version for decoding
+	pk.FixedHeader = *fh
+	p := make([]byte, pk.FixedHeader.Remaining)
+	n, err := io.ReadFull(cl.Net.bconn, p)
+	if err != nil {
+		return pk, err
+	}
+
+	atomic.AddInt64(&cl.ops.info.BytesReceived, int64(n))
+
+	// Decode the remaining packet values using a fresh copy of the bytes,
+	// otherwise the next packet will change the data of this one.
+	px := append([]byte{}, p[:]...)
+	switch pk.FixedHeader.Type {
+	case packets.Connect:
+		err = pk.ConnectDecode(px)
+	case packets.Disconnect:
+		err = pk.DisconnectDecode(px)
+	case packets.Connack:
+		err = pk.ConnackDecode(px)
+	case packets.Publish:
+		err = pk.PublishDecode(px)
+		if err == nil {
+			atomic.AddInt64(&cl.ops.info.MessagesReceived, 1)
+		}
+	case packets.Puback:
+		err = pk.PubackDecode(px)
+	case packets.Pubrec:
+		err = pk.PubrecDecode(px)
+	case packets.Pubrel:
+		err = pk.PubrelDecode(px)
+	case packets.Pubcomp:
+		err = pk.PubcompDecode(px)
+	case packets.Subscribe:
+		err = pk.SubscribeDecode(px)
+	case packets.Suback:
+		err = pk.SubackDecode(px)
+	case packets.Unsubscribe:
+		err = pk.UnsubscribeDecode(px)
+	case packets.Unsuback:
+		err = pk.UnsubackDecode(px)
+	case packets.Pingreq:
+	case packets.Pingresp:
+	case packets.Auth:
+		err = pk.AuthDecode(px)
+	default:
+		err = fmt.Errorf("invalid packet type; %v", pk.FixedHeader.Type)
+	}
+
+	if err != nil {
+		return pk, err
+	}
+
+	pk, err = cl.ops.hooks.OnPacketRead(cl, pk)
+	return
+}
+
+// WritePacket encodes and writes a packet to the client.
+func (cl *Client) WritePacket(pk packets.Packet) error {
+	if cl.Closed() {
+		return ErrConnectionClosed
+	}
+
+	if cl.Net.Conn == nil {
+		return nil
+	}
+
+	if pk.Expiry > 0 {
+		pk.Properties.MessageExpiryInterval = uint32(pk.Expiry - time.Now().Unix()) // [MQTT-3.3.2-6]
+	}
+
+	pk.ProtocolVersion = cl.Properties.ProtocolVersion
+	if pk.Mods.MaxSize == 0 { // NB we use this statement to embed client packet sizes in tests
+		pk.Mods.MaxSize = cl.Properties.Props.MaximumPacketSize
+	}
+
+	if cl.Properties.Props.RequestProblemInfoFlag && cl.Properties.Props.RequestProblemInfo == 0x0 {
+		pk.Mods.DisallowProblemInfo = true // [MQTT-3.1.2-29] strict, no problem info on any packet if set
+	}
+
+	if pk.FixedHeader.Type != packets.Connack || cl.Properties.Props.RequestResponseInfo == 0x1 || cl.ops.options.Capabilities.Compatibilities.AlwaysReturnResponseInfo {
+		pk.Mods.AllowResponseInfo = true // [MQTT-3.1.2-28] we need to know which properties we can encode
+	}
+
+	pk = cl.ops.hooks.OnPacketEncode(cl, pk)
+
+	var err error
+	buf := new(bytes.Buffer)
+	switch pk.FixedHeader.Type {
+	case packets.Connect:
+		err = pk.ConnectEncode(buf)
+	case packets.Connack:
+		err = pk.ConnackEncode(buf)
+	case packets.Publish:
+		err = pk.PublishEncode(buf)
+	case packets.Puback:
+		err = pk.PubackEncode(buf)
+	case packets.Pubrec:
+		err = pk.PubrecEncode(buf)
+	case packets.Pubrel:
+		err = pk.PubrelEncode(buf)
+	case packets.Pubcomp:
+		err = pk.PubcompEncode(buf)
+	case packets.Subscribe:
+		err = pk.SubscribeEncode(buf)
+	case packets.Suback:
+		err = pk.SubackEncode(buf)
+	case packets.Unsubscribe:
+		err = pk.UnsubscribeEncode(buf)
+	case packets.Unsuback:
+		err = pk.UnsubackEncode(buf)
+	case packets.Pingreq:
+		err = pk.PingreqEncode(buf)
+	case packets.Pingresp:
+		err = pk.PingrespEncode(buf)
+	case packets.Disconnect:
+		err = pk.DisconnectEncode(buf)
+	case packets.Auth:
+		err = pk.AuthEncode(buf)
+	default:
+		err = fmt.Errorf("%w: %v", packets.ErrNoValidPacketAvailable, pk.FixedHeader.Type)
+	}
+	if err != nil {
+		return err
+	}
+
+	if pk.Mods.MaxSize > 0 && uint32(buf.Len()) > pk.Mods.MaxSize {
+		return packets.ErrPacketTooLarge // [MQTT-3.1.2-24] [MQTT-3.1.2-25]
+	}
+
+	n, err := func() (int64, error) {
+		cl.Lock()
+		defer cl.Unlock()
+		if len(cl.State.outbound) == 0 {
+			if cl.Net.outbuf == nil {
+				return buf.WriteTo(cl.Net.Conn)
+			}
+
+			// first write to buffer, then flush buffer
+			n, _ := cl.Net.outbuf.Write(buf.Bytes()) // will always be successful
+			err = cl.flushOutbuf()
+			return int64(n), err
+		}
+
+		// there are more writes in the queue
+		if cl.Net.outbuf == nil {
+			if buf.Len() >= cl.ops.options.ClientNetWriteBufferSize {
+				return buf.WriteTo(cl.Net.Conn)
+			}
+			cl.Net.outbuf = new(bytes.Buffer)
+		}
+
+		n, _ := cl.Net.outbuf.Write(buf.Bytes()) // will always be successful
+		if cl.Net.outbuf.Len() < cl.ops.options.ClientNetWriteBufferSize {
+			return int64(n), nil
+		}
+
+		err = cl.flushOutbuf()
+		return int64(n), err
+	}()
+	if err != nil {
+		return err
+	}
+
+	atomic.AddInt64(&cl.ops.info.BytesSent, n)
+	atomic.AddInt64(&cl.ops.info.PacketsSent, 1)
+	if pk.FixedHeader.Type == packets.Publish {
+		atomic.AddInt64(&cl.ops.info.MessagesSent, 1)
+	}
+
+	cl.ops.hooks.OnPacketSent(cl, pk, buf.Bytes())
+
+	return err
+}
+
+func (cl *Client) flushOutbuf() (err error) {
+	if cl.Net.outbuf == nil {
+		return
+	}
+
+	_, err = cl.Net.outbuf.WriteTo(cl.Net.Conn)
+	if err == nil {
+		cl.Net.outbuf = nil
+	}
+	return
+}

clients_test.go

@@ -0,0 +1,928 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package mqtt
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"net"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+
+	"github.com/stretchr/testify/require"
+)
+
+const pkInfo = "packet type %v, %s"
+
+var errClientStop = errors.New("test stop")
+
+func newTestClient() (cl *Client, r net.Conn, w net.Conn) {
+	r, w = net.Pipe()
+
+	cl = newClient(w, &ops{
+		info:  new(system.Info),
+		hooks: new(Hooks),
+		log:   logger,
+		options: &Options{
+			Capabilities: &Capabilities{
+				ReceiveMaximum:             10,
+				MaximumInflight:            5,
+				TopicAliasMaximum:          10000,
+				MaximumClientWritesPending: 3,
+				maximumPacketID:            10,
+			},
+		},
+	})
+
+	cl.ID = "mochi"
+	cl.State.Inflight.maximumSendQuota = 5
+	cl.State.Inflight.sendQuota = 5
+	cl.State.Inflight.maximumReceiveQuota = 10
+	cl.State.Inflight.receiveQuota = 10
+	cl.Properties.Props.TopicAliasMaximum = 0
+	cl.Properties.Props.RequestResponseInfo = 0x1
+
+	go cl.WriteLoop()
+
+	return
+}
+
+func TestNewInflights(t *testing.T) {
+	require.NotNil(t, NewInflights().internal)
+}
+
+func TestNewClients(t *testing.T) {
+	cl := NewClients()
+	require.NotNil(t, cl.internal)
+}
+
+func TestClientsAdd(t *testing.T) {
+	cl := NewClients()
+	cl.Add(&Client{ID: "t1"})
+	require.Contains(t, cl.internal, "t1")
+}
+
+func TestClientsGet(t *testing.T) {
+	cl := NewClients()
+	cl.Add(&Client{ID: "t1"})
+	cl.Add(&Client{ID: "t2"})
+	require.Contains(t, cl.internal, "t1")
+	require.Contains(t, cl.internal, "t2")
+
+	client, ok := cl.Get("t1")
+	require.Equal(t, true, ok)
+	require.Equal(t, "t1", client.ID)
+}
+
+func TestClientsGetAll(t *testing.T) {
+	cl := NewClients()
+	cl.Add(&Client{ID: "t1"})
+	cl.Add(&Client{ID: "t2"})
+	cl.Add(&Client{ID: "t3"})
+	require.Contains(t, cl.internal, "t1")
+	require.Contains(t, cl.internal, "t2")
+	require.Contains(t, cl.internal, "t3")
+
+	clients := cl.GetAll()
+	require.Len(t, clients, 3)
+}
+
+func TestClientsLen(t *testing.T) {
+	cl := NewClients()
+	cl.Add(&Client{ID: "t1"})
+	cl.Add(&Client{ID: "t2"})
+	require.Contains(t, cl.internal, "t1")
+	require.Contains(t, cl.internal, "t2")
+	require.Equal(t, 2, cl.Len())
+}
+
+func TestClientsDelete(t *testing.T) {
+	cl := NewClients()
+	cl.Add(&Client{ID: "t1"})
+	require.Contains(t, cl.internal, "t1")
+
+	cl.Delete("t1")
+	_, ok := cl.Get("t1")
+	require.Equal(t, false, ok)
+	require.Nil(t, cl.internal["t1"])
+}
+
+func TestClientsGetByListener(t *testing.T) {
+	cl := NewClients()
+	cl.Add(&Client{ID: "t1", State: ClientState{open: context.Background()}, Net: ClientConnection{Listener: "tcp1"}})
+	cl.Add(&Client{ID: "t2", State: ClientState{open: context.Background()}, Net: ClientConnection{Listener: "ws1"}})
+	require.Contains(t, cl.internal, "t1")
+	require.Contains(t, cl.internal, "t2")
+
+	clients := cl.GetByListener("tcp1")
+	require.NotEmpty(t, clients)
+	require.Equal(t, 1, len(clients))
+	require.Equal(t, "tcp1", clients[0].Net.Listener)
+}
+
+func TestNewClient(t *testing.T) {
+	cl, _, _ := newTestClient()
+
+	require.NotNil(t, cl)
+	require.NotNil(t, cl.State.Inflight.internal)
+	require.NotNil(t, cl.State.Subscriptions)
+	require.NotNil(t, cl.State.TopicAliases)
+	require.Equal(t, defaultKeepalive, cl.State.Keepalive)
+	require.Equal(t, defaultClientProtocolVersion, cl.Properties.ProtocolVersion)
+	require.NotNil(t, cl.Net.Conn)
+	require.NotNil(t, cl.Net.bconn)
+	require.NotNil(t, cl.ops)
+	require.NotNil(t, cl.ops.options.Capabilities)
+	require.False(t, cl.Net.Inline)
+}
+
+func TestClientParseConnect(t *testing.T) {
+	cl, _, _ := newTestClient()
+
+	pk := packets.Packet{
+		ProtocolVersion: 4,
+		Connect: packets.ConnectParams{
+			ProtocolName:     []byte{'M', 'Q', 'T', 'T'},
+			Clean:            true,
+			Keepalive:        60,
+			ClientIdentifier: "mochi",
+			WillFlag:         true,
+			WillTopic:        "lwt",
+			WillPayload:      []byte("lol gg"),
+			WillQos:          1,
+			WillRetain:       false,
+		},
+		Properties: packets.Properties{
+			ReceiveMaximum: uint16(5),
+		},
+	}
+
+	cl.ParseConnect("tcp1", pk)
+	require.Equal(t, pk.Connect.ClientIdentifier, cl.ID)
+	require.Equal(t, pk.Connect.Keepalive, cl.State.Keepalive)
+	require.Equal(t, pk.Connect.Clean, cl.Properties.Clean)
+	require.Equal(t, pk.Connect.ClientIdentifier, cl.ID)
+	require.Equal(t, pk.Connect.WillTopic, cl.Properties.Will.TopicName)
+	require.Equal(t, pk.Connect.WillPayload, cl.Properties.Will.Payload)
+	require.Equal(t, pk.Connect.WillQos, cl.Properties.Will.Qos)
+	require.Equal(t, pk.Connect.WillRetain, cl.Properties.Will.Retain)
+	require.Equal(t, uint32(1), cl.Properties.Will.Flag)
+	require.Equal(t, int32(cl.ops.options.Capabilities.ReceiveMaximum), cl.State.Inflight.receiveQuota)
+	require.Equal(t, int32(cl.ops.options.Capabilities.ReceiveMaximum), cl.State.Inflight.maximumReceiveQuota)
+	require.Equal(t, int32(pk.Properties.ReceiveMaximum), cl.State.Inflight.sendQuota)
+	require.Equal(t, int32(pk.Properties.ReceiveMaximum), cl.State.Inflight.maximumSendQuota)
+}
+
+func TestClientParseConnectReceiveMaxExceedMaxInflight(t *testing.T) {
+	const MaxInflight uint16 = 1
+	cl, _, _ := newTestClient()
+	cl.ops.options.Capabilities.MaximumInflight = MaxInflight
+
+	pk := packets.Packet{
+		ProtocolVersion: 4,
+		Connect: packets.ConnectParams{
+			ProtocolName:     []byte{'M', 'Q', 'T', 'T'},
+			Clean:            true,
+			Keepalive:        60,
+			ClientIdentifier: "mochi",
+			WillFlag:         true,
+			WillTopic:        "lwt",
+			WillPayload:      []byte("lol gg"),
+			WillQos:          1,
+			WillRetain:       false,
+		},
+		Properties: packets.Properties{
+			ReceiveMaximum: uint16(5),
+		},
+	}
+
+	cl.ParseConnect("tcp1", pk)
+	require.Equal(t, pk.Connect.ClientIdentifier, cl.ID)
+	require.Equal(t, pk.Connect.Keepalive, cl.State.Keepalive)
+	require.Equal(t, pk.Connect.Clean, cl.Properties.Clean)
+	require.Equal(t, pk.Connect.ClientIdentifier, cl.ID)
+	require.Equal(t, pk.Connect.WillTopic, cl.Properties.Will.TopicName)
+	require.Equal(t, pk.Connect.WillPayload, cl.Properties.Will.Payload)
+	require.Equal(t, pk.Connect.WillQos, cl.Properties.Will.Qos)
+	require.Equal(t, pk.Connect.WillRetain, cl.Properties.Will.Retain)
+	require.Equal(t, uint32(1), cl.Properties.Will.Flag)
+	require.Equal(t, int32(cl.ops.options.Capabilities.ReceiveMaximum), cl.State.Inflight.receiveQuota)
+	require.Equal(t, int32(cl.ops.options.Capabilities.ReceiveMaximum), cl.State.Inflight.maximumReceiveQuota)
+	require.Equal(t, int32(MaxInflight), cl.State.Inflight.sendQuota)
+	require.Equal(t, int32(MaxInflight), cl.State.Inflight.maximumSendQuota)
+}
+
+func TestClientParseConnectOverrideWillDelay(t *testing.T) {
+	cl, _, _ := newTestClient()
+
+	pk := packets.Packet{
+		ProtocolVersion: 4,
+		Connect: packets.ConnectParams{
+			ProtocolName:     []byte{'M', 'Q', 'T', 'T'},
+			Clean:            true,
+			Keepalive:        60,
+			ClientIdentifier: "mochi",
+			WillFlag:         true,
+			WillProperties: packets.Properties{
+				WillDelayInterval: 200,
+			},
+		},
+		Properties: packets.Properties{
+			SessionExpiryInterval:     100,
+			SessionExpiryIntervalFlag: true,
+		},
+	}
+
+	cl.ParseConnect("tcp1", pk)
+	require.Equal(t, pk.Properties.SessionExpiryInterval, cl.Properties.Will.WillDelayInterval)
+}
+
+func TestClientParseConnectNoID(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.ParseConnect("tcp1", packets.Packet{})
+	require.NotEmpty(t, cl.ID)
+}
+
+func TestClientParseConnectBelowMinimumKeepalive(t *testing.T) {
+	cl, _, _ := newTestClient()
+	var b bytes.Buffer
+	x := bufio.NewWriter(&b)
+	cl.ops.log = slog.New(slog.NewTextHandler(x, nil))
+
+	pk := packets.Packet{
+		ProtocolVersion: 4,
+		Connect: packets.ConnectParams{
+			ProtocolName:     []byte{'M', 'Q', 'T', 'T'},
+			Keepalive:        minimumKeepalive - 1,
+			ClientIdentifier: "mochi",
+		},
+	}
+	cl.ParseConnect("tcp1", pk)
+	err := x.Flush()
+	require.NoError(t, err)
+	require.True(t, strings.Contains(b.String(), ErrMinimumKeepalive.Error()))
+	require.NotEmpty(t, cl.ID)
+}
+
+func TestClientNextPacketID(t *testing.T) {
+	cl, _, _ := newTestClient()
+
+	i, err := cl.NextPacketID()
+	require.NoError(t, err)
+	require.Equal(t, uint32(1), i)
+
+	i, err = cl.NextPacketID()
+	require.NoError(t, err)
+	require.Equal(t, uint32(2), i)
+}
+
+func TestClientNextPacketIDInUse(t *testing.T) {
+	cl, _, _ := newTestClient()
+
+	// skip over 2
+	cl.State.Inflight.Set(packets.Packet{PacketID: 2})
+
+	i, err := cl.NextPacketID()
+	require.NoError(t, err)
+	require.Equal(t, uint32(1), i)
+
+	i, err = cl.NextPacketID()
+	require.NoError(t, err)
+	require.Equal(t, uint32(3), i)
+
+	// Skip over overflow
+	cl.State.Inflight.Set(packets.Packet{PacketID: 65535})
+	atomic.StoreUint32(&cl.State.packetID, 65534)
+
+	i, err = cl.NextPacketID()
+	require.NoError(t, err)
+	require.Equal(t, uint32(1), i)
+}
+
+func TestClientNextPacketIDExhausted(t *testing.T) {
+	cl, _, _ := newTestClient()
+	for i := uint32(1); i <= cl.ops.options.Capabilities.maximumPacketID; i++ {
+		cl.State.Inflight.internal[uint16(i)] = packets.Packet{PacketID: uint16(i)}
+	}
+
+	i, err := cl.NextPacketID()
+	require.Error(t, err)
+	require.ErrorIs(t, err, packets.ErrQuotaExceeded)
+	require.Equal(t, uint32(0), i)
+}
+
+func TestClientNextPacketIDOverflow(t *testing.T) {
+	cl, _, _ := newTestClient()
+	for i := uint32(0); i < cl.ops.options.Capabilities.maximumPacketID; i++ {
+		cl.State.Inflight.internal[uint16(i)] = packets.Packet{}
+	}
+
+	cl.State.packetID = cl.ops.options.Capabilities.maximumPacketID - 1
+	i, err := cl.NextPacketID()
+	require.NoError(t, err)
+	require.Equal(t, cl.ops.options.Capabilities.maximumPacketID, i)
+	cl.State.Inflight.internal[uint16(cl.ops.options.Capabilities.maximumPacketID)] = packets.Packet{}
+
+	cl.State.packetID = cl.ops.options.Capabilities.maximumPacketID
+	_, err = cl.NextPacketID()
+	require.Error(t, err)
+	require.ErrorIs(t, err, packets.ErrQuotaExceeded)
+}
+
+func TestClientClearInflights(t *testing.T) {
+	cl, _, _ := newTestClient()
+	n := time.Now().Unix()
+
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 1, Expiry: n - 1})
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 2, Expiry: n - 2})
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 3, Created: n - 3}) // within bounds
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 5, Created: n - 5}) // over max server expiry limit
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 7, Created: n})
+
+	require.Equal(t, 5, cl.State.Inflight.Len())
+	cl.ClearInflights()
+	require.Equal(t, 0, cl.State.Inflight.Len())
+}
+
+func TestClientClearExpiredInflights(t *testing.T) {
+	cl, _, _ := newTestClient()
+
+	n := time.Now().Unix()
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 1, Expiry: n - 1})
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 2, Expiry: n - 2})
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 3, Created: n - 3}) // within bounds
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 5, Created: n - 5}) // over max server expiry limit
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 7, Created: n})
+	require.Equal(t, 5, cl.State.Inflight.Len())
+
+	deleted := cl.ClearExpiredInflights(n, 4)
+	require.Len(t, deleted, 3)
+	require.ElementsMatch(t, []uint16{1, 2, 5}, deleted)
+	require.Equal(t, 2, cl.State.Inflight.Len())
+
+	cl.State.Inflight.Set(packets.Packet{PacketID: 11, Expiry: n - 1})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 12, Expiry: n - 2})  // expiry is ineffective for v3.
+	cl.State.Inflight.Set(packets.Packet{PacketID: 13, Created: n - 3}) // within bounds for v3
+	cl.State.Inflight.Set(packets.Packet{PacketID: 15, Created: n - 5}) // over max server expiry limit
+	require.Equal(t, 6, cl.State.Inflight.Len())
+
+	deleted = cl.ClearExpiredInflights(n, 4)
+	require.Len(t, deleted, 3)
+	require.ElementsMatch(t, []uint16{11, 12, 15}, deleted)
+	require.Equal(t, 3, cl.State.Inflight.Len())
+
+	cl.State.Inflight.Set(packets.Packet{PacketID: 17, Created: n - 1})
+	deleted = cl.ClearExpiredInflights(n, 0) // maximumExpiry = 0 do not process abandon messages
+	require.Len(t, deleted, 0)
+	require.Equal(t, 4, cl.State.Inflight.Len())
+
+	cl.State.Inflight.Set(packets.Packet{ProtocolVersion: 5, PacketID: 18, Expiry: n - 1})
+	deleted = cl.ClearExpiredInflights(n, 0)        // maximumExpiry = 0 do not abandon messages
+	require.ElementsMatch(t, []uint16{18}, deleted) // expiry is still effective for v5.
+	require.Len(t, deleted, 1)
+	require.Equal(t, 4, cl.State.Inflight.Len())
+}
+
+func TestClientResendInflightMessages(t *testing.T) {
+	pk1 := packets.TPacketData[packets.Puback].Get(packets.TPuback)
+	cl, r, w := newTestClient()
+
+	cl.State.Inflight.Set(*pk1.Packet)
+	require.Equal(t, 1, cl.State.Inflight.Len())
+
+	go func() {
+		err := cl.ResendInflightMessages(true)
+		require.NoError(t, err)
+		time.Sleep(time.Millisecond)
+		_ = w.Close()
+	}()
+
+	buf, err := io.ReadAll(r)
+	require.NoError(t, err)
+	require.Equal(t, 0, cl.State.Inflight.Len())
+	require.Equal(t, pk1.RawBytes, buf)
+}
+
+func TestClientResendInflightMessagesWriteFailure(t *testing.T) {
+	pk1 := packets.TPacketData[packets.Publish].Get(packets.TPublishQos1Dup)
+	cl, r, _ := newTestClient()
+	_ = r.Close()
+
+	cl.State.Inflight.Set(*pk1.Packet)
+	require.Equal(t, 1, cl.State.Inflight.Len())
+	err := cl.ResendInflightMessages(true)
+	require.Error(t, err)
+	require.ErrorIs(t, err, io.ErrClosedPipe)
+	require.Equal(t, 1, cl.State.Inflight.Len())
+}
+
+func TestClientResendInflightMessagesNoMessages(t *testing.T) {
+	cl, _, _ := newTestClient()
+	err := cl.ResendInflightMessages(true)
+	require.NoError(t, err)
+}
+
+func TestClientRefreshDeadline(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.refreshDeadline(10)
+	require.NotNil(t, cl.Net.Conn) // how do we check net.Conn deadline?
+}
+
+func TestClientReadFixedHeader(t *testing.T) {
+	cl, r, _ := newTestClient()
+
+	defer cl.Stop(errClientStop)
+	go func() {
+		_, _ = r.Write([]byte{packets.Connect << 4, 0x00})
+		_ = r.Close()
+	}()
+
+	fh := new(packets.FixedHeader)
+	err := cl.ReadFixedHeader(fh)
+	require.NoError(t, err)
+	require.Equal(t, int64(2), atomic.LoadInt64(&cl.ops.info.BytesReceived))
+}
+
+func TestClientReadFixedHeaderDecodeError(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+
+	go func() {
+		_, _ = r.Write([]byte{packets.Connect<<4 | 1<<1, 0x00, 0x00})
+		_ = r.Close()
+	}()
+
+	fh := new(packets.FixedHeader)
+	err := cl.ReadFixedHeader(fh)
+	require.Error(t, err)
+}
+
+func TestClientReadFixedHeaderPacketOversized(t *testing.T) {
+	cl, r, _ := newTestClient()
+	cl.ops.options.Capabilities.MaximumPacketSize = 2
+	defer cl.Stop(errClientStop)
+
+	go func() {
+		_, _ = r.Write(packets.TPacketData[packets.Publish].Get(packets.TPublishQos1Dup).RawBytes)
+		_ = r.Close()
+	}()
+
+	fh := new(packets.FixedHeader)
+	err := cl.ReadFixedHeader(fh)
+	require.Error(t, err)
+	require.ErrorIs(t, err, packets.ErrPacketTooLarge)
+}
+
+func TestClientReadFixedHeaderReadEOF(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+
+	go func() {
+		_ = r.Close()
+	}()
+
+	fh := new(packets.FixedHeader)
+	err := cl.ReadFixedHeader(fh)
+	require.Error(t, err)
+	require.Equal(t, io.EOF, err)
+}
+
+func TestClientReadFixedHeaderNoLengthTerminator(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+
+	go func() {
+		_, _ = r.Write([]byte{packets.Connect << 4, 0xd5, 0x86, 0xf9, 0x9e, 0x01})
+		_ = r.Close()
+	}()
+
+	fh := new(packets.FixedHeader)
+	err := cl.ReadFixedHeader(fh)
+	require.Error(t, err)
+}
+
+func TestClientReadOK(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+	go func() {
+		_, _ = r.Write([]byte{
+			packets.Publish << 4, 18, // Fixed header
+			0, 5, // Topic Name - LSB+MSB
+			'a', '/', 'b', '/', 'c', // Topic Name
+			'h', 'e', 'l', 'l', 'o', ' ', 'm', 'o', 'c', 'h', 'i', // Payload,
+			packets.Publish << 4, 11, // Fixed header
+			0, 5, // Topic Name - LSB+MSB
+			'd', '/', 'e', '/', 'f', // Topic Name
+			'y', 'e', 'a', 'h', // Payload
+		})
+		_ = r.Close()
+	}()
+
+	var pks []packets.Packet
+	o := make(chan error)
+	go func() {
+		o <- cl.Read(func(cl *Client, pk packets.Packet) error {
+			pks = append(pks, pk)
+			return nil
+		})
+	}()
+
+	err := <-o
+	require.Error(t, err)
+	require.ErrorIs(t, err, io.EOF)
+	require.Equal(t, 2, len(pks))
+	require.Equal(t, []packets.Packet{
+		{
+			ProtocolVersion: cl.Properties.ProtocolVersion,
+			FixedHeader: packets.FixedHeader{
+				Type:      packets.Publish,
+				Remaining: 18,
+			},
+			TopicName: "a/b/c",
+			Payload:   []byte("hello mochi"),
+		},
+		{
+			ProtocolVersion: cl.Properties.ProtocolVersion,
+			FixedHeader: packets.FixedHeader{
+				Type:      packets.Publish,
+				Remaining: 11,
+			},
+			TopicName: "d/e/f",
+			Payload:   []byte("yeah"),
+		},
+	}, pks)
+
+	require.Equal(t, int64(2), atomic.LoadInt64(&cl.ops.info.MessagesReceived))
+}
+
+func TestClientReadDone(t *testing.T) {
+	cl, _, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+	cl.State.cancelOpen()
+
+	o := make(chan error)
+	go func() {
+		o <- cl.Read(func(cl *Client, pk packets.Packet) error {
+			return nil
+		})
+	}()
+
+	require.NoError(t, <-o)
+}
+
+func TestClientStop(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.Stop(nil)
+	require.Equal(t, nil, cl.State.stopCause.Load())
+	require.Equal(t, time.Now().Unix(), cl.State.disconnected)
+	require.True(t, cl.Closed())
+	require.Equal(t, nil, cl.StopCause())
+}
+
+func TestClientClosed(t *testing.T) {
+	cl, _, _ := newTestClient()
+	require.False(t, cl.Closed())
+	cl.Stop(nil)
+	require.True(t, cl.Closed())
+}
+
+func TestClientReadFixedHeaderError(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+	go func() {
+		_, _ = r.Write([]byte{
+			packets.Publish << 4, 11, // Fixed header
+		})
+		_ = r.Close()
+	}()
+
+	cl.Net.bconn = nil
+	fh := new(packets.FixedHeader)
+	err := cl.ReadFixedHeader(fh)
+	require.Error(t, err)
+	require.ErrorIs(t, ErrConnectionClosed, err)
+}
+
+func TestClientReadReadHandlerErr(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+	go func() {
+		_, _ = r.Write([]byte{
+			packets.Publish << 4, 11, // Fixed header
+			0, 5, // Topic Name - LSB+MSB
+			'd', '/', 'e', '/', 'f', // Topic Name
+			'y', 'e', 'a', 'h', // Payload
+		})
+		_ = r.Close()
+	}()
+
+	err := cl.Read(func(cl *Client, pk packets.Packet) error {
+		return errors.New("test")
+	})
+
+	require.Error(t, err)
+}
+
+func TestClientReadReadPacketOK(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+	go func() {
+		_, _ = r.Write([]byte{
+			packets.Publish << 4, 11, // Fixed header
+			0, 5,
+			'd', '/', 'e', '/', 'f',
+			'y', 'e', 'a', 'h',
+		})
+		_ = r.Close()
+	}()
+
+	fh := new(packets.FixedHeader)
+	err := cl.ReadFixedHeader(fh)
+	require.NoError(t, err)
+
+	pk, err := cl.ReadPacket(fh)
+	require.NoError(t, err)
+	require.NotNil(t, pk)
+
+	require.Equal(t, packets.Packet{
+		ProtocolVersion: cl.Properties.ProtocolVersion,
+		FixedHeader: packets.FixedHeader{
+			Type:      packets.Publish,
+			Remaining: 11,
+		},
+		TopicName: "d/e/f",
+		Payload:   []byte("yeah"),
+	}, pk)
+}
+
+func TestClientReadPacket(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+
+	for _, tx := range pkTable {
+		tt := tx // avoid data race
+		t.Run(tt.Desc, func(t *testing.T) {
+			atomic.StoreInt64(&cl.ops.info.PacketsReceived, 0)
+			go func() {
+				_, _ = r.Write(tt.RawBytes)
+			}()
+
+			fh := new(packets.FixedHeader)
+			err := cl.ReadFixedHeader(fh)
+			require.NoError(t, err)
+
+			if tt.Packet.ProtocolVersion == 5 {
+				cl.Properties.ProtocolVersion = 5
+			} else {
+				cl.Properties.ProtocolVersion = 0
+			}
+
+			pk, err := cl.ReadPacket(fh)
+			require.NoError(t, err, pkInfo, tt.Case, tt.Desc)
+			require.NotNil(t, pk, pkInfo, tt.Case, tt.Desc)
+			require.Equal(t, *tt.Packet, pk, pkInfo, tt.Case, tt.Desc)
+
+			if tt.Packet.FixedHeader.Type == packets.Publish {
+				require.Equal(t, int64(1), atomic.LoadInt64(&cl.ops.info.PacketsReceived), pkInfo, tt.Case, tt.Desc)
+			}
+		})
+	}
+}
+
+func TestClientReadPacketInvalidTypeError(t *testing.T) {
+	cl, _, _ := newTestClient()
+	_ = cl.Net.Conn.Close()
+	_, err := cl.ReadPacket(&packets.FixedHeader{})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "invalid packet type")
+}
+
+func TestClientWritePacket(t *testing.T) {
+	for _, tt := range pkTable {
+		cl, r, _ := newTestClient()
+		defer cl.Stop(errClientStop)
+
+		cl.Properties.ProtocolVersion = tt.Packet.ProtocolVersion
+
+		o := make(chan []byte)
+		go func() {
+			buf, err := io.ReadAll(r)
+			require.NoError(t, err)
+			o <- buf
+		}()
+
+		err := cl.WritePacket(*tt.Packet)
+		require.NoError(t, err, pkInfo, tt.Case, tt.Desc)
+
+		time.Sleep(2 * time.Millisecond)
+		_ = cl.Net.Conn.Close()
+
+		require.Equal(t, tt.RawBytes, <-o, pkInfo, tt.Case, tt.Desc)
+
+		cl.Stop(errClientStop)
+		time.Sleep(time.Millisecond * 1)
+
+		// The stop cause is either the test error, EOF, or a
+		// closed pipe, depending on which goroutine runs first.
+		err = cl.StopCause()
+		require.True(t,
+			errors.Is(err, errClientStop) ||
+				errors.Is(err, io.EOF) ||
+				errors.Is(err, io.ErrClosedPipe))
+
+		require.Equal(t, int64(len(tt.RawBytes)), atomic.LoadInt64(&cl.ops.info.BytesSent))
+		require.Equal(t, int64(1), atomic.LoadInt64(&cl.ops.info.PacketsSent))
+		if tt.Packet.FixedHeader.Type == packets.Publish {
+			require.Equal(t, int64(1), atomic.LoadInt64(&cl.ops.info.MessagesSent))
+		}
+	}
+}
+
+func TestClientWritePacketBuffer(t *testing.T) {
+	r, w := net.Pipe()
+
+	cl := newClient(w, &ops{
+		info:  new(system.Info),
+		hooks: new(Hooks),
+		log:   logger,
+		options: &Options{
+			Capabilities: &Capabilities{
+				ReceiveMaximum:             10,
+				TopicAliasMaximum:          10000,
+				MaximumClientWritesPending: 3,
+				maximumPacketID:            10,
+			},
+		},
+	})
+
+	cl.ID = "mochi"
+	cl.State.Inflight.maximumSendQuota = 5
+	cl.State.Inflight.sendQuota = 5
+	cl.State.Inflight.maximumReceiveQuota = 10
+	cl.State.Inflight.receiveQuota = 10
+	cl.Properties.Props.TopicAliasMaximum = 0
+	cl.Properties.Props.RequestResponseInfo = 0x1
+
+	cl.ops.options.ClientNetWriteBufferSize = 10
+	defer cl.Stop(errClientStop)
+
+	small := packets.TPacketData[packets.Publish].Get(packets.TPublishNoPayload).Packet
+	large := packets.TPacketData[packets.Publish].Get(packets.TPublishBasic).Packet
+
+	cl.State.outbound <- small
+
+	tt := []struct {
+		pks  []*packets.Packet
+		size int
+	}{
+		{
+			pks:  []*packets.Packet{small, small},
+			size: 18,
+		},
+		{
+			pks:  []*packets.Packet{large},
+			size: 20,
+		},
+		{
+			pks:  []*packets.Packet{small},
+			size: 0,
+		},
+	}
+
+	go func() {
+		for i, tx := range tt {
+			for _, pk := range tx.pks {
+				cl.Properties.ProtocolVersion = pk.ProtocolVersion
+				err := cl.WritePacket(*pk)
+				require.NoError(t, err, "index: %d", i)
+				if i == len(tt)-1 {
+					cl.Net.Conn.Close()
+				}
+				time.Sleep(100 * time.Millisecond)
+			}
+		}
+	}()
+
+	var n int
+	var err error
+	for i, tx := range tt {
+		buf := make([]byte, 100)
+		if i == len(tt)-1 {
+			buf, err = io.ReadAll(r)
+			n = len(buf)
+		} else {
+			n, err = io.ReadAtLeast(r, buf, 1)
+		}
+		require.NoError(t, err, "index: %d", i)
+		require.Equal(t, tx.size, n, "index: %d", i)
+	}
+}
+
+func TestWriteClientOversizePacket(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.Properties.Props.MaximumPacketSize = 2
+	pk := *packets.TPacketData[packets.Publish].Get(packets.TPublishDropOversize).Packet
+	err := cl.WritePacket(pk)
+	require.Error(t, err)
+	require.ErrorIs(t, packets.ErrPacketTooLarge, err)
+}
+
+func TestClientReadPacketReadingError(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+	go func() {
+		_, _ = r.Write([]byte{
+			0, 11, // Fixed header
+			0, 5,
+			'd', '/', 'e', '/', 'f',
+			'y', 'e', 'a', 'h',
+		})
+		_ = r.Close()
+	}()
+
+	_, err := cl.ReadPacket(&packets.FixedHeader{
+		Type:      0,
+		Remaining: 11,
+	})
+	require.Error(t, err)
+}
+
+func TestClientReadPacketReadUnknown(t *testing.T) {
+	cl, r, _ := newTestClient()
+	defer cl.Stop(errClientStop)
+	go func() {
+		_, _ = r.Write([]byte{
+			0, 11, // Fixed header
+			0, 5,
+			'd', '/', 'e', '/', 'f',
+			'y', 'e', 'a', 'h',
+		})
+		_ = r.Close()
+	}()
+
+	_, err := cl.ReadPacket(&packets.FixedHeader{
+		Remaining: 1,
+	})
+	require.Error(t, err)
+}
+
+func TestClientWritePacketWriteNoConn(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.Stop(errClientStop)
+
+	err := cl.WritePacket(*pkTable[1].Packet)
+	require.Error(t, err)
+	require.Equal(t, ErrConnectionClosed, err)
+}
+
+func TestClientWritePacketWriteError(t *testing.T) {
+	cl, _, _ := newTestClient()
+	_ = cl.Net.Conn.Close()
+
+	err := cl.WritePacket(*pkTable[1].Packet)
+	require.Error(t, err)
+}
+
+func TestClientWritePacketInvalidPacket(t *testing.T) {
+	cl, _, _ := newTestClient()
+	err := cl.WritePacket(packets.Packet{})
+	require.Error(t, err)
+}
+
+var (
+	pkTable = []packets.TPacketCase{
+		packets.TPacketData[packets.Connect].Get(packets.TConnectMqtt311),
+		packets.TPacketData[packets.Connack].Get(packets.TConnackAcceptedMqtt5),
+		packets.TPacketData[packets.Connack].Get(packets.TConnackAcceptedNoSession),
+		packets.TPacketData[packets.Publish].Get(packets.TPublishBasic),
+		packets.TPacketData[packets.Publish].Get(packets.TPublishMqtt5),
+		packets.TPacketData[packets.Puback].Get(packets.TPuback),
+		packets.TPacketData[packets.Pubrec].Get(packets.TPubrec),
+		packets.TPacketData[packets.Pubrel].Get(packets.TPubrel),
+		packets.TPacketData[packets.Pubcomp].Get(packets.TPubcomp),
+		packets.TPacketData[packets.Subscribe].Get(packets.TSubscribe),
+		packets.TPacketData[packets.Subscribe].Get(packets.TSubscribeMqtt5),
+		packets.TPacketData[packets.Suback].Get(packets.TSuback),
+		packets.TPacketData[packets.Suback].Get(packets.TSubackMqtt5),
+		packets.TPacketData[packets.Unsubscribe].Get(packets.TUnsubscribe),
+		packets.TPacketData[packets.Unsubscribe].Get(packets.TUnsubscribeMqtt5),
+		packets.TPacketData[packets.Unsuback].Get(packets.TUnsuback),
+		packets.TPacketData[packets.Unsuback].Get(packets.TUnsubackMqtt5),
+		packets.TPacketData[packets.Pingreq].Get(packets.TPingreq),
+		packets.TPacketData[packets.Pingresp].Get(packets.TPingresp),
+		packets.TPacketData[packets.Disconnect].Get(packets.TDisconnect),
+		packets.TPacketData[packets.Disconnect].Get(packets.TDisconnectMqtt5),
+		packets.TPacketData[packets.Auth].Get(packets.TAuth),
+	}
+)

cmd/docker/main.go

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt
+// SPDX-FileContributor: dgduncan, mochi-co
+
+package main
+
+import (
+	"flag"
+	"fmt"
+	"github.com/mochi-mqtt/server/v2/config"
+	"log"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+)
+
+func main() {
+	slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, nil))) // set basic logger to ensure logs before configuration are in a consistent format
+
+	configFile := flag.String("config", "config.yaml", "path to mochi config yaml or json file")
+	flag.Parse()
+
+	entries, err := os.ReadDir("./")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, e := range entries {
+		fmt.Println(e.Name())
+	}
+
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	configBytes, err := os.ReadFile(*configFile)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	options, err := config.FromBytes(configBytes)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	server := mqtt.New(options)
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("mochi mqtt shutdown complete")
+}

cmd/main.go

@@ -1,17 +1,19 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
 package main
 
 import (
 	"flag"
-	"fmt"
 	"log"
 	"os"
 	"os/signal"
 	"syscall"
 
-	"github.com/logrusorgru/aurora"
-
-	mqtt "github.com/mochi-co/mqtt/server"
-	"github.com/mochi-co/mqtt/server/listeners"
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/listeners"
 )
 
 func main() {
@@ -28,37 +30,48 @@ func main() {
 		done <- true
 	}()
 
-	fmt.Println(aurora.Magenta("Mochi MQTT Broker initializing..."))
-	fmt.Println(aurora.Cyan("TCP"), *tcpAddr)
-	fmt.Println(aurora.Cyan("Websocket"), *wsAddr)
-	fmt.Println(aurora.Cyan("$SYS Dashboard"), *infoAddr)
+	server := mqtt.New(nil)
+	_ = server.AddHook(new(auth.AllowHook), nil)
 
-	server := mqtt.New()
-	tcp := listeners.NewTCP("t1", *tcpAddr)
-	err := server.AddListener(tcp, nil)
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: *tcpAddr,
+	})
+	err := server.AddListener(tcp)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	ws := listeners.NewWebsocket("ws1", *wsAddr)
-	err = server.AddListener(ws, nil)
+	ws := listeners.NewWebsocket(listeners.Config{
+		ID:      "ws1",
+		Address: *wsAddr,
+	})
+	err = server.AddListener(ws)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	stats := listeners.NewHTTPStats("stats", *infoAddr)
-	err = server.AddListener(stats, nil)
+	stats := listeners.NewHTTPStats(
+		listeners.Config{
+			ID:      "info",
+			Address: *infoAddr,
+		},
+		server.Info,
+	)
+	err = server.AddListener(stats)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	go server.Serve()
-	fmt.Println(aurora.BgMagenta("  Started!  "))
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
 
 	<-done
-	fmt.Println(aurora.BgRed("  Caught Signal  "))
-
-	server.Close()
-	fmt.Println(aurora.BgGreen("  Finished  "))
-
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("mochi mqtt shutdown complete")
 }

config.yaml

@@ -0,0 +1,15 @@
+listeners:
+  - type: "tcp"
+    id: "tcp12"
+    address: ":1883"
+  - type: "ws"
+    id: "ws1"
+    address: ":1882"
+  - type: "sysinfo"
+    id: "stats"
+    address: ":1880"
+hooks:
+  auth:
+    allow_all: true
+options:
+  inline_client: true

config/config.go

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package config
+
+import (
+	"encoding/json"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/hooks/debug"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/badger"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/bolt"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/redis"
+	"github.com/mochi-mqtt/server/v2/listeners"
+	"gopkg.in/yaml.v3"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+)
+
+// config defines the structure of configuration data to be parsed from a config source.
+type config struct {
+	Options     mqtt.Options
+	Listeners   []listeners.Config `yaml:"listeners" json:"listeners"`
+	HookConfigs HookConfigs        `yaml:"hooks" json:"hooks"`
+}
+
+// HookConfigs contains configurations to enable individual hooks.
+type HookConfigs struct {
+	Auth    *HookAuthConfig    `yaml:"auth" json:"auth"`
+	Storage *HookStorageConfig `yaml:"storage" json:"storage"`
+	Debug   *debug.Options     `yaml:"debug" json:"debug"`
+}
+
+// HookAuthConfig contains configurations for the auth hook.
+type HookAuthConfig struct {
+	Ledger   auth.Ledger `yaml:"ledger" json:"ledger"`
+	AllowAll bool        `yaml:"allow_all" json:"allow_all"`
+}
+
+// HookStorageConfig contains configurations for the different storage hooks.
+type HookStorageConfig struct {
+	Badger *badger.Options `yaml:"badger" json:"badger"`
+	Bolt   *bolt.Options   `yaml:"bolt" json:"bolt"`
+	Redis  *redis.Options  `yaml:"redis" json:"redis"`
+}
+
+// ToHooks converts Hook file configurations into Hooks to be added to the server.
+func (hc HookConfigs) ToHooks() []mqtt.HookLoadConfig {
+	var hlc []mqtt.HookLoadConfig
+
+	if hc.Auth != nil {
+		hlc = append(hlc, hc.toHooksAuth()...)
+	}
+
+	if hc.Storage != nil {
+		hlc = append(hlc, hc.toHooksStorage()...)
+	}
+
+	if hc.Debug != nil {
+		hlc = append(hlc, mqtt.HookLoadConfig{
+			Hook:   new(debug.Hook),
+			Config: hc.Debug,
+		})
+	}
+
+	return hlc
+}
+
+// toHooksAuth converts auth hook configurations into auth hooks.
+func (hc HookConfigs) toHooksAuth() []mqtt.HookLoadConfig {
+	var hlc []mqtt.HookLoadConfig
+	if hc.Auth.AllowAll {
+		hlc = append(hlc, mqtt.HookLoadConfig{
+			Hook: new(auth.AllowHook),
+		})
+	} else {
+		hlc = append(hlc, mqtt.HookLoadConfig{
+			Hook: new(auth.Hook),
+			Config: &auth.Options{
+				Ledger: &auth.Ledger{ // avoid copying sync.Locker
+					Users: hc.Auth.Ledger.Users,
+					Auth:  hc.Auth.Ledger.Auth,
+					ACL:   hc.Auth.Ledger.ACL,
+				},
+			},
+		})
+	}
+	return hlc
+}
+
+// toHooksAuth converts storage hook configurations into storage hooks.
+func (hc HookConfigs) toHooksStorage() []mqtt.HookLoadConfig {
+	var hlc []mqtt.HookLoadConfig
+	if hc.Storage.Badger != nil {
+		hlc = append(hlc, mqtt.HookLoadConfig{
+			Hook:   new(badger.Hook),
+			Config: hc.Storage.Badger,
+		})
+	}
+
+	if hc.Storage.Bolt != nil {
+		hlc = append(hlc, mqtt.HookLoadConfig{
+			Hook:   new(bolt.Hook),
+			Config: hc.Storage.Bolt,
+		})
+	}
+
+	if hc.Storage.Redis != nil {
+		hlc = append(hlc, mqtt.HookLoadConfig{
+			Hook:   new(redis.Hook),
+			Config: hc.Storage.Redis,
+		})
+	}
+	return hlc
+}
+
+// FromBytes unmarshals a byte slice of JSON or YAML config data into a valid server options value.
+// Any hooks configurations are converted into Hooks using the toHooks methods in this package.
+func FromBytes(b []byte) (*mqtt.Options, error) {
+	c := new(config)
+	o := mqtt.Options{}
+
+	if len(b) == 0 {
+		return nil, nil
+	}
+
+	if b[0] == '{' {
+		err := json.Unmarshal(b, c)
+		if err != nil {
+			return nil, err
+		}
+	} else {
+		err := yaml.Unmarshal(b, c)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	o = c.Options
+	o.Hooks = c.HookConfigs.ToHooks()
+	o.Listeners = c.Listeners
+
+	return &o, nil
+}

config/config_test.go

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package config
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/badger"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/bolt"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/redis"
+	"github.com/mochi-mqtt/server/v2/listeners"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+)
+
+var (
+	yamlBytes = []byte(`
+listeners:
+  - type: "tcp"
+    id: "file-tcp1"
+    address: ":1883"
+hooks:
+  auth:
+    allow_all: true
+options:
+  client_net_write_buffer_size: 2048
+  capabilities:
+    minimum_protocol_version: 3
+    compatibilities:
+      restore_sys_info_on_restart: true
+`)
+
+	jsonBytes = []byte(`{
+   "listeners": [
+      {
+         "type": "tcp",
+         "id": "file-tcp1",
+         "address": ":1883"
+      }
+   ],
+   "hooks": {
+      "auth": {
+         "allow_all": true
+      }
+   },
+   "options": {
+      "client_net_write_buffer_size": 2048,
+      "capabilities": {
+         "minimum_protocol_version": 3,
+         "compatibilities": {
+            "restore_sys_info_on_restart": true
+         }
+      }
+   }
+}
+`)
+
+	parsedOptions = mqtt.Options{
+		Listeners: []listeners.Config{
+			{
+				Type:    listeners.TypeTCP,
+				ID:      "file-tcp1",
+				Address: ":1883",
+			},
+		},
+		Hooks: []mqtt.HookLoadConfig{
+			{
+				Hook: new(auth.AllowHook),
+			},
+		},
+		ClientNetWriteBufferSize: 2048,
+		Capabilities: &mqtt.Capabilities{
+			MinimumProtocolVersion: 3,
+			Compatibilities: mqtt.Compatibilities{
+				RestoreSysInfoOnRestart: true,
+			},
+		},
+	}
+)
+
+func TestFromBytesEmptyL(t *testing.T) {
+	_, err := FromBytes([]byte{})
+	require.NoError(t, err)
+}
+
+func TestFromBytesYAML(t *testing.T) {
+	o, err := FromBytes(yamlBytes)
+	require.NoError(t, err)
+	require.Equal(t, parsedOptions, *o)
+}
+
+func TestFromBytesYAMLError(t *testing.T) {
+	_, err := FromBytes(append(yamlBytes, 'a'))
+	require.Error(t, err)
+}
+
+func TestFromBytesJSON(t *testing.T) {
+	o, err := FromBytes(jsonBytes)
+	require.NoError(t, err)
+	require.Equal(t, parsedOptions, *o)
+}
+
+func TestFromBytesJSONError(t *testing.T) {
+	_, err := FromBytes(append(jsonBytes, 'a'))
+	require.Error(t, err)
+}
+
+func TestToHooksAuthAllowAll(t *testing.T) {
+	hc := HookConfigs{
+		Auth: &HookAuthConfig{
+			AllowAll: true,
+		},
+	}
+
+	th := hc.toHooksAuth()
+	expect := []mqtt.HookLoadConfig{
+		{Hook: new(auth.AllowHook)},
+	}
+	require.Equal(t, expect, th)
+}
+
+func TestToHooksAuthAllowLedger(t *testing.T) {
+	hc := HookConfigs{
+		Auth: &HookAuthConfig{
+			Ledger: auth.Ledger{
+				Auth: auth.AuthRules{
+					{Username: "peach", Password: "password1", Allow: true},
+				},
+			},
+		},
+	}
+
+	th := hc.toHooksAuth()
+	expect := []mqtt.HookLoadConfig{
+		{
+			Hook: new(auth.Hook),
+			Config: &auth.Options{
+				Ledger: &auth.Ledger{ // avoid copying sync.Locker
+					Auth: auth.AuthRules{
+						{Username: "peach", Password: "password1", Allow: true},
+					},
+				},
+			},
+		},
+	}
+	require.Equal(t, expect, th)
+}
+
+func TestToHooksStorageBadger(t *testing.T) {
+	hc := HookConfigs{
+		Storage: &HookStorageConfig{
+			Badger: &badger.Options{
+				Path: "badger",
+			},
+		},
+	}
+
+	th := hc.toHooksStorage()
+	expect := []mqtt.HookLoadConfig{
+		{
+			Hook:   new(badger.Hook),
+			Config: hc.Storage.Badger,
+		},
+	}
+
+	require.Equal(t, expect, th)
+}
+
+func TestToHooksStorageBolt(t *testing.T) {
+	hc := HookConfigs{
+		Storage: &HookStorageConfig{
+			Bolt: &bolt.Options{
+				Path: "bolt",
+			},
+		},
+	}
+
+	th := hc.toHooksStorage()
+	expect := []mqtt.HookLoadConfig{
+		{
+			Hook:   new(bolt.Hook),
+			Config: hc.Storage.Bolt,
+		},
+	}
+
+	require.Equal(t, expect, th)
+}
+
+func TestToHooksStorageRedis(t *testing.T) {
+	hc := HookConfigs{
+		Storage: &HookStorageConfig{
+			Redis: &redis.Options{
+				Username: "test",
+			},
+		},
+	}
+
+	th := hc.toHooksStorage()
+	expect := []mqtt.HookLoadConfig{
+		{
+			Hook:   new(redis.Hook),
+			Config: hc.Storage.Redis,
+		},
+	}
+
+	require.Equal(t, expect, th)
+}

examples/auth/basic/main.go

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/listeners"
+)
+
+func main() {
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	authRules := &auth.Ledger{
+		Auth: auth.AuthRules{ // Auth disallows all by default
+			{Username: "peach", Password: "password1", Allow: true},
+			{Username: "melon", Password: "password2", Allow: true},
+			{Remote: "127.0.0.1:*", Allow: true},
+			{Remote: "localhost:*", Allow: true},
+		},
+		ACL: auth.ACLRules{ // ACL allows all by default
+			{Remote: "127.0.0.1:*"}, // local superuser allow all
+			{
+				// user melon can read and write to their own topic
+				Username: "melon", Filters: auth.Filters{
+					"melon/#":   auth.ReadWrite,
+					"updates/#": auth.WriteOnly, // can write to updates, but can't read updates from others
+				},
+			},
+			{
+				// Otherwise, no clients have publishing permissions
+				Filters: auth.Filters{
+					"#":         auth.ReadOnly,
+					"updates/#": auth.Deny,
+				},
+			},
+		},
+	}
+
+	// you may also find this useful...
+	// d, _ := authRules.ToYAML()
+	// d, _ := authRules.ToJSON()
+	// fmt.Println(string(d))
+
+	server := mqtt.New(nil)
+	err := server.AddHook(new(auth.Hook), &auth.Options{
+		Ledger: authRules,
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
+	})
+	err = server.AddListener(tcp)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/auth/encoded/auth.json

@@ -0,0 +1,40 @@
+{
+  "auth": [
+    {
+      "username": "peach",
+      "password": "password1",
+      "allow": true
+    },
+    {
+      "username": "melon",
+      "password": "password2",
+      "allow": true
+    },
+    {
+      "remote": "127.0.0.1:*",
+      "allow": false
+    },
+    {
+      "remote": "localhost:*",
+      "allow": false
+    }
+  ],
+  "acl": [
+    {
+      "remote": "127.0.0.1:*"
+    },
+    {
+      "username": "melon",
+      "filters": {
+        "melon/#": 3,
+        "updates/#": 2
+      }
+    },
+    {
+      "filters": {
+        "#": 1,
+        "updates/#": 0
+      }
+    }
+  ]
+}

examples/auth/encoded/auth.yaml

@@ -0,0 +1,21 @@
+auth:
+    - username: peach
+      password: password1
+      allow: true
+    - username: melon
+      password: password2
+      allow: true
+    # - remote: 127.0.0.1:*
+    #   allow: true
+    # - remote: localhost:*
+    #   allow: true
+acl:
+# 0 = deny, 1 = read only, 2 = write only, 3 = read and write
+    - remote: 127.0.0.1:*
+    - username: melon
+      filters:
+        melon/#: 3
+        updates/#: 2
+    - filters:
+        '#': 1
+        updates/#: 0

examples/auth/encoded/main.go

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"flag"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/listeners"
+)
+
+func main() {
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	// You can also run from top-level server.go folder:
+	// go run examples/auth/encoded/main.go --path=examples/auth/encoded/auth.yaml
+	// go run examples/auth/encoded/main.go --path=examples/auth/encoded/auth.json
+	path := flag.String("path", "auth.yaml", "path to data auth file")
+	flag.Parse()
+
+	// Get ledger from yaml file
+	data, err := os.ReadFile(*path)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	server := mqtt.New(nil)
+	err = server.AddHook(new(auth.Hook), &auth.Options{
+		Data: data, // build ledger from byte slice, yaml or json
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
+	})
+	err = server.AddListener(tcp)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/benchmark/main.go

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"flag"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/listeners"
+)
+
+func main() {
+	tcpAddr := flag.String("tcp", ":1883", "network address for TCP listener")
+	flag.Parse()
+
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	server := mqtt.New(nil)
+	server.Options.Capabilities.MaximumClientWritesPending = 16 * 1024
+	_ = server.AddHook(new(auth.AllowHook), nil)
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: *tcpAddr,
+	})
+	err := server.AddListener(tcp)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/config/config.json

@@ -0,0 +1,92 @@
+{
+  "listeners": [
+    {
+      "type": "tcp",
+      "id": "file-tcp1",
+      "address": ":1883"
+    },
+    {
+      "type": "ws",
+      "id": "file-websocket",
+      "address": ":1882"
+    },
+    {
+      "type": "healthcheck",
+      "id": "file-healthcheck",
+      "address": ":1880"
+    }
+  ],
+  "hooks": {
+    "debug": {
+      "enable": true
+    },
+    "storage": {
+      "badger": {
+        "path": "badger.db",
+        "gc_interval": 3,
+        "gc_discard_ratio": 0.5
+      },
+      "bolt": {
+        "path": "bolt.db"
+      },
+      "redis": {
+        "h_prefix": "mc",
+        "username": "mochi",
+        "password": "melon",
+        "address": "localhost:6379",
+        "database": 1
+      }
+    },
+    "auth": {
+      "allow_all": false,
+      "ledger": {
+        "auth": [
+          {
+            "username": "peach",
+            "password": "password1",
+            "allow": true
+          }
+        ],
+        "acl": [
+          {
+            "remote": "127.0.0.1:*"
+          },
+          {
+            "username": "melon",
+            "filters": null,
+            "melon/#": 3,
+            "updates/#": 2
+          }
+        ]
+      }
+    }
+  },
+  "options": {
+    "client_net_write_buffer_size": 2048,
+    "client_net_read_buffer_size": 2048,
+    "sys_topic_resend_interval": 10,
+    "inline_client": true,
+    "capabilities": {
+      "maximum_message_expiry_interval": 100,
+      "maximum_client_writes_pending": 8192,
+      "maximum_session_expiry_interval": 86400,
+      "maximum_packet_size": 0,
+      "receive_maximum": 1024,
+      "maximum_inflight": 8192,
+      "topic_alias_maximum": 65535,
+      "shared_sub_available": 1,
+      "minimum_protocol_version": 3,
+      "maximum_qos": 2,
+      "retain_available": 1,
+      "wildcard_sub_available": 1,
+      "sub_id_available": 1,
+      "compatibilities": {
+        "obscure_not_authorized": true,
+        "passive_client_disconnect": false,
+        "always_return_response_info": false,
+        "restore_sys_info_on_restart": false,
+        "no_inherited_properties_on_ack": false
+      }
+    }
+  }
+}

examples/config/config.yaml

@@ -0,0 +1,64 @@
+listeners:
+  - type: "tcp"
+    id: "file-tcp1"
+    address: ":1883"
+  - type: "ws"
+    id: "file-websocket"
+    address: ":1882"
+  - type: "healthcheck"
+    id: "file-healthcheck"
+    address: ":1880"
+hooks:
+  debug:
+    enable: true
+  storage:
+    badger:
+      path: badger.db
+      gc_interval: 3
+      gc_discard_ratio: 0.5
+    bolt:
+      path: bolt.db
+    redis:
+      h_prefix: "mc"
+      username: "mochi"
+      password: "melon"
+      address: "localhost:6379"
+      database: 1
+  auth:
+    allow_all: false
+    ledger:
+      auth:
+        - username: peach
+          password: password1
+          allow: true
+      acl:
+        - remote: 127.0.0.1:*
+        - username: melon
+          filters:
+          melon/#: 3
+          updates/#: 2
+options:
+  client_net_write_buffer_size: 2048
+  client_net_read_buffer_size: 2048
+  sys_topic_resend_interval: 10
+  inline_client: true
+  capabilities:
+    maximum_message_expiry_interval: 100
+    maximum_client_writes_pending: 8192
+    maximum_session_expiry_interval: 86400
+    maximum_packet_size: 0
+    receive_maximum: 1024
+    maximum_inflight: 8192
+    topic_alias_maximum: 65535
+    shared_sub_available: 1
+    minimum_protocol_version: 3
+    maximum_qos: 2
+    retain_available: 1
+    wildcard_sub_available: 1
+    sub_id_available: 1
+    compatibilities:
+      obscure_not_authorized: true
+      passive_client_disconnect: false
+      always_return_response_info: false
+      restore_sys_info_on_restart: false
+      no_inherited_properties_on_ack: false

examples/config/main.go

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"github.com/mochi-mqtt/server/v2/config"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+)
+
+func main() {
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	configBytes, err := os.ReadFile("config.json")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	options, err := config.FromBytes(configBytes)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	server := mqtt.New(options)
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/dashboard/main.go

@@ -1,49 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"log"
-	"os"
-	"os/signal"
-	"syscall"
-
-	"github.com/logrusorgru/aurora"
-
-	mqtt "github.com/mochi-co/mqtt/server"
-	"github.com/mochi-co/mqtt/server/listeners"
-)
-
-func main() {
-	sigs := make(chan os.Signal, 1)
-	done := make(chan bool, 1)
-	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
-	go func() {
-		<-sigs
-		done <- true
-	}()
-
-	fmt.Println(aurora.Magenta("Mochi MQTT Server initializing..."), aurora.Cyan("TCP"))
-
-	server := mqtt.New()
-
-	stats := listeners.NewHTTPStats("stats", ":8080")
-	err = server.AddListener(stats, nil)
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	go func() {
-		err := server.Serve()
-		if err != nil {
-			log.Fatal(err)
-		}
-	}()
-	fmt.Println(aurora.BgMagenta("  Started!  "))
-
-	<-done
-	fmt.Println(aurora.BgRed("  Caught Signal  "))
-
-	server.Close()
-	fmt.Println(aurora.BgGreen("  Finished  "))
-
-}

examples/debug/main.go

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"log"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/hooks/debug"
+	"github.com/mochi-mqtt/server/v2/listeners"
+)
+
+func main() {
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	server := mqtt.New(nil)
+
+	level := new(slog.LevelVar)
+	server.Log = slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+		Level: level,
+	}))
+	level.Set(slog.LevelDebug)
+
+	err := server.AddHook(new(debug.Hook), &debug.Options{
+		// ShowPacketData: true,
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	err = server.AddHook(new(auth.AllowHook), nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
+	})
+	err = server.AddListener(tcp)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/direct/main.go

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/packets"
+)
+
+func main() {
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	server := mqtt.New(&mqtt.Options{
+		InlineClient: true, // you must enable inline client to use direct publishing and subscribing.
+	})
+	_ = server.AddHook(new(auth.AllowHook), nil)
+
+	// Start the server
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	// Demonstration of using an inline client to directly subscribe to a topic and receive a message when
+	// that subscription is activated. The inline subscription method uses the same internal subscription logic
+	// as used for external (normal) clients.
+	go func() {
+		// Inline subscriptions can also receive retained messages on subscription.
+		_ = server.Publish("direct/retained", []byte("retained message"), true, 0)
+		_ = server.Publish("direct/alternate/retained", []byte("some other retained message"), true, 0)
+
+		// Subscribe to a filter and handle any received messages via a callback function.
+		callbackFn := func(cl *mqtt.Client, sub packets.Subscription, pk packets.Packet) {
+			server.Log.Info("inline client received message from subscription", "client", cl.ID, "subscriptionId", sub.Identifier, "topic", pk.TopicName, "payload", string(pk.Payload))
+		}
+		server.Log.Info("inline client subscribing")
+		_ = server.Subscribe("direct/#", 1, callbackFn)
+		_ = server.Subscribe("direct/#", 2, callbackFn)
+	}()
+
+	// There is a shorthand convenience function, Publish, for easily sending  publish packets if you are not
+	// concerned with creating your own packets.  If you want to have more control over your packets, you can
+	//directly inject a packet of any kind into the broker. See examples/hooks/main.go for usage.
+	go func() {
+		for range time.Tick(time.Second * 3) {
+			err := server.Publish("direct/publish", []byte("scheduled message"), false, 0)
+			if err != nil {
+				server.Log.Error("server.Publish", "error", err)
+			}
+			server.Log.Info("main.go issued direct message to direct/publish")
+		}
+	}()
+
+	go func() {
+		time.Sleep(time.Second * 10)
+		// Unsubscribe from the same filter to stop receiving messages.
+		server.Log.Info("inline client unsubscribing")
+		_ = server.Unsubscribe("direct/#", 1)
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/hooks/main.go

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/listeners"
+	"github.com/mochi-mqtt/server/v2/packets"
+)
+
+func main() {
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	server := mqtt.New(&mqtt.Options{
+		InlineClient: true, // you must enable inline client to use direct publishing and subscribing.
+	})
+
+	_ = server.AddHook(new(auth.AllowHook), nil)
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
+	})
+	err := server.AddListener(tcp)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Add custom hook (ExampleHook) to the server
+	err = server.AddHook(new(ExampleHook), &ExampleHookOptions{
+		Server: server,
+	})
+
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Start the server
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	// Demonstration of directly publishing messages to a topic via the
+	// `server.Publish` method. Subscribe to `direct/publish` using your
+	// MQTT client to see the messages.
+	go func() {
+		cl := server.NewClient(nil, "local", "inline", true)
+		for range time.Tick(time.Second * 1) {
+			err := server.InjectPacket(cl, packets.Packet{
+				FixedHeader: packets.FixedHeader{
+					Type: packets.Publish,
+				},
+				TopicName: "direct/publish",
+				Payload:   []byte("injected scheduled message"),
+			})
+			if err != nil {
+				server.Log.Error("server.InjectPacket", "error", err)
+			}
+			server.Log.Info("main.go injected packet to direct/publish")
+		}
+	}()
+
+	// There is also a shorthand convenience function, Publish, for easily sending
+	// publish packets if you are not concerned with creating your own packets.
+	go func() {
+		for range time.Tick(time.Second * 5) {
+			err := server.Publish("direct/publish", []byte("packet scheduled message"), false, 0)
+			if err != nil {
+				server.Log.Error("server.Publish", "error", err)
+			}
+			server.Log.Info("main.go issued direct message to direct/publish")
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}
+
+// Options contains configuration settings for the hook.
+type ExampleHookOptions struct {
+	Server *mqtt.Server
+}
+
+type ExampleHook struct {
+	mqtt.HookBase
+	config *ExampleHookOptions
+}
+
+func (h *ExampleHook) ID() string {
+	return "events-example"
+}
+
+func (h *ExampleHook) Provides(b byte) bool {
+	return bytes.Contains([]byte{
+		mqtt.OnConnect,
+		mqtt.OnDisconnect,
+		mqtt.OnSubscribed,
+		mqtt.OnUnsubscribed,
+		mqtt.OnPublished,
+		mqtt.OnPublish,
+	}, []byte{b})
+}
+
+func (h *ExampleHook) Init(config any) error {
+	h.Log.Info("initialised")
+	if _, ok := config.(*ExampleHookOptions); !ok && config != nil {
+		return mqtt.ErrInvalidConfigType
+	}
+
+	h.config = config.(*ExampleHookOptions)
+	if h.config.Server == nil {
+		return mqtt.ErrInvalidConfigType
+	}
+	return nil
+}
+
+// subscribeCallback handles messages for subscribed topics
+func (h *ExampleHook) subscribeCallback(cl *mqtt.Client, sub packets.Subscription, pk packets.Packet) {
+	h.Log.Info("hook subscribed message", "client", cl.ID, "topic", pk.TopicName)
+}
+
+func (h *ExampleHook) OnConnect(cl *mqtt.Client, pk packets.Packet) error {
+	h.Log.Info("client connected", "client", cl.ID)
+
+	// Example demonstrating how to subscribe to a topic within the hook.
+	h.config.Server.Subscribe("hook/direct/publish", 1, h.subscribeCallback)
+
+	// Example demonstrating how to publish a message within the hook
+	err := h.config.Server.Publish("hook/direct/publish", []byte("packet hook message"), false, 0)
+	if err != nil {
+		h.Log.Error("hook.publish", "error", err)
+	}
+
+	return nil
+}
+
+func (h *ExampleHook) OnDisconnect(cl *mqtt.Client, err error, expire bool) {
+	if err != nil {
+		h.Log.Info("client disconnected", "client", cl.ID, "expire", expire, "error", err)
+	} else {
+		h.Log.Info("client disconnected", "client", cl.ID, "expire", expire)
+	}
+
+}
+
+func (h *ExampleHook) OnSubscribed(cl *mqtt.Client, pk packets.Packet, reasonCodes []byte) {
+	h.Log.Info(fmt.Sprintf("subscribed qos=%v", reasonCodes), "client", cl.ID, "filters", pk.Filters)
+}
+
+func (h *ExampleHook) OnUnsubscribed(cl *mqtt.Client, pk packets.Packet) {
+	h.Log.Info("unsubscribed", "client", cl.ID, "filters", pk.Filters)
+}
+
+func (h *ExampleHook) OnPublish(cl *mqtt.Client, pk packets.Packet) (packets.Packet, error) {
+	h.Log.Info("received from client", "client", cl.ID, "payload", string(pk.Payload))
+
+	pkx := pk
+	if string(pk.Payload) == "hello" {
+		pkx.Payload = []byte("hello world")
+		h.Log.Info("received modified packet from client", "client", cl.ID, "payload", string(pkx.Payload))
+	}
+
+	return pkx, nil
+}
+
+func (h *ExampleHook) OnPublished(cl *mqtt.Client, pk packets.Packet) {
+	h.Log.Info("published to client", "client", cl.ID, "payload", string(pk.Payload))
+}

examples/paho.testing/main.go

@@ -1,16 +1,19 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
 package main
 
 import (
-	"fmt"
+	"bytes"
 	"log"
 	"os"
 	"os/signal"
 	"syscall"
 
-	"github.com/logrusorgru/aurora"
-
-	mqtt "github.com/mochi-co/mqtt/server"
-	"github.com/mochi-co/mqtt/server/listeners"
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/listeners"
+	"github.com/mochi-mqtt/server/v2/packets"
 )
 
 func main() {
@@ -22,41 +25,63 @@ func main() {
 		done <- true
 	}()
 
-	fmt.Println(aurora.Magenta("Mochi MQTT Server initializing..."), aurora.Cyan("PAHO Testing Suite"))
+	server := mqtt.New(nil)
+	server.Options.Capabilities.Compatibilities.ObscureNotAuthorized = true
+	server.Options.Capabilities.Compatibilities.PassiveClientDisconnect = true
+	server.Options.Capabilities.Compatibilities.NoInheritedPropertiesOnAck = true
 
-	server := mqtt.New()
-	tcp := listeners.NewTCP("t1", ":1883")
-	err := server.AddListener(tcp, &listeners.Config{
-		Auth: new(Auth),
+	_ = server.AddHook(new(pahoAuthHook), nil)
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
 	})
+	err := server.AddListener(tcp)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	go server.Serve()
-	fmt.Println(aurora.BgMagenta("  Started!  "))
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
 
 	<-done
-	fmt.Println(aurora.BgRed("  Caught Signal  "))
-
-	server.Close()
-	fmt.Println(aurora.BgGreen("  Finished  "))
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
 }
 
-// Auth is an example auth provider for the server.
-type Auth struct{}
+type pahoAuthHook struct {
+	mqtt.HookBase
+}
 
-// Auth returns true if a username and password are acceptable.
-// Auth always returns true.
-func (a *Auth) Authenticate(user, password []byte) bool {
+func (h *pahoAuthHook) ID() string {
+	return "allow-all-auth"
+}
+
+func (h *pahoAuthHook) Provides(b byte) bool {
+	return bytes.Contains([]byte{
+		mqtt.OnConnectAuthenticate,
+		mqtt.OnConnect,
+		mqtt.OnACLCheck,
+	}, []byte{b})
+}
+
+func (h *pahoAuthHook) OnConnectAuthenticate(cl *mqtt.Client, pk packets.Packet) bool {
 	return true
 }
 
-// ACL returns true if a user has access permissions to read or write on a topic.
-// ACL is used to deny access to a specific topic to satisfy Test.test_subscribe_failure.
-func (a *Auth) ACL(user []byte, topic string, write bool) bool {
-	if topic == "test/nosubscribe" {
-		return false
+func (h *pahoAuthHook) OnACLCheck(cl *mqtt.Client, topic string, write bool) bool {
+	return topic != "test/nosubscribe"
+}
+
+func (h *pahoAuthHook) OnConnect(cl *mqtt.Client, pk packets.Packet) error {
+	// Handle paho test_server_keep_alive
+	if pk.Connect.Keepalive == 120 && pk.Connect.Clean {
+		cl.State.Keepalive = 60
+		cl.State.ServerKeepalive = true
 	}
-	return true
+	return nil
 }

examples/persistence/badger/main.go

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	badgerdb "github.com/dgraph-io/badger"
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/badger"
+	"github.com/mochi-mqtt/server/v2/listeners"
+	"github.com/timshannon/badgerhold"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+)
+
+func main() {
+	badgerPath := ".badger"
+	defer os.RemoveAll(badgerPath) // remove the example badger files at the end
+
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	server := mqtt.New(nil)
+	_ = server.AddHook(new(auth.AllowHook), nil)
+
+	// AddHook adds a BadgerDB hook to the server with the specified options.
+	// GcInterval specifies the interval at which BadgerDB garbage collection process runs.
+	// Refer to https://dgraph.io/docs/badger/get-started/#garbage-collection for more information.
+	err := server.AddHook(new(badger.Hook), &badger.Options{
+		Path: badgerPath,
+
+		// Set the interval for garbage collection. Adjust according to your actual scenario.
+		GcInterval: 5 * 60,
+
+		// GcDiscardRatio specifies the ratio of log discard compared to the maximum possible log discard.
+		// Setting it to a higher value would result in fewer space reclaims, while setting it to a lower value
+		// would result in more space reclaims at the cost of increased activity on the LSM tree.
+		// discardRatio must be in the range (0.0, 1.0), both endpoints excluded, otherwise, it will be set to the default value of 0.5.
+		// Adjust according to your actual scenario.
+		GcDiscardRatio: 0.5,
+
+		Options: &badgerhold.Options{
+			// BadgerDB options. Adjust according to your actual scenario.
+			Options: badgerdb.Options{
+				NumCompactors:    2,               // Number of compactors. Compactions can be expensive.
+				MaxTableSize:     64 << 20,        // Maximum size of each table (64 MB).
+				ValueLogFileSize: 100 * (1 << 20), // Set the default size of the log file to 100 MB.
+			},
+		},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
+	})
+	err = server.AddListener(tcp)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/persistence/bolt/main.go

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/bolt"
+	"github.com/mochi-mqtt/server/v2/listeners"
+	"go.etcd.io/bbolt"
+)
+
+func main() {
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	server := mqtt.New(nil)
+	_ = server.AddHook(new(auth.AllowHook), nil)
+
+	err := server.AddHook(new(bolt.Hook), &bolt.Options{
+		Path: "bolt.db",
+		Options: &bbolt.Options{
+			Timeout: 500 * time.Millisecond,
+		},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
+	})
+	err = server.AddListener(tcp)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/persistence/main.go

@@ -1,58 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"log"
-	"os"
-	"os/signal"
-	"syscall"
-
-	"github.com/logrusorgru/aurora"
-	"go.etcd.io/bbolt"
-
-	mqtt "github.com/mochi-co/mqtt/server"
-	"github.com/mochi-co/mqtt/server/listeners"
-	"github.com/mochi-co/mqtt/server/persistence/bolt"
-)
-
-func main() {
-	sigs := make(chan os.Signal, 1)
-	done := make(chan bool, 1)
-	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
-	go func() {
-		<-sigs
-		done <- true
-	}()
-
-	fmt.Println(aurora.Magenta("Mochi MQTT Server initializing..."), aurora.Cyan("Persistence"))
-
-	server := mqtt.New()
-	tcp := listeners.NewTCP("t1", ":1883")
-	err := server.AddListener(tcp, &listeners.Config{
-		Auth: new(Auth),
-	})
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	err = server.AddStore(bolt.New("mochi-test.db", &bbolt.Options{
-		Timeout: 500 * time.Millisecond,
-	}))
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	go func() {
-		err := server.Serve()
-		if err != nil {
-			log.Fatal(err)
-		}
-	}()
-	fmt.Println(aurora.BgMagenta("  Started!  "))
-
-	<-done
-	fmt.Println(aurora.BgRed("  Caught Signal  "))
-
-	server.Close()
-	fmt.Println(aurora.BgGreen("  Finished  "))
-}

examples/persistence/redis/main.go

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package main
+
+import (
+	"log"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/hooks/storage/redis"
+	"github.com/mochi-mqtt/server/v2/listeners"
+
+	rv8 "github.com/go-redis/redis/v8"
+)
+
+func main() {
+	sigs := make(chan os.Signal, 1)
+	done := make(chan bool, 1)
+	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sigs
+		done <- true
+	}()
+
+	server := mqtt.New(nil)
+	_ = server.AddHook(new(auth.AllowHook), nil)
+
+	level := new(slog.LevelVar)
+	server.Log = slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+		Level: level,
+	}))
+	level.Set(slog.LevelDebug)
+
+	err := server.AddHook(new(redis.Hook), &redis.Options{
+		Options: &rv8.Options{
+			Addr:     "localhost:6379", // default redis address
+			Password: "",               // your password
+			DB:       0,                // your redis db
+		},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
+	})
+	err = server.AddListener(tcp)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
+
+	<-done
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
+}

examples/tcp/main.go

@@ -1,16 +1,18 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
 package main
 
 import (
-	"fmt"
 	"log"
 	"os"
 	"os/signal"
 	"syscall"
 
-	"github.com/logrusorgru/aurora"
-
-	mqtt "github.com/mochi-co/mqtt/server"
-	"github.com/mochi-co/mqtt/server/listeners"
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/listeners"
 )
 
 func main() {
@@ -22,13 +24,25 @@ func main() {
 		done <- true
 	}()
 
-	fmt.Println(aurora.Magenta("Mochi MQTT Server initializing..."), aurora.Cyan("TCP"))
+	// An example of configuring various server options...
+	options := &mqtt.Options{
+		// InflightTTL: 60 * 15, // Set an example custom 15-min TTL for inflight messages
+	}
 
-	server := mqtt.New()
-	tcp := listeners.NewTCP("t1", ":1883")
-	err := server.AddListener(tcp, &listeners.Config{
-		Auth: new(Auth),
+	server := mqtt.New(options)
+
+	// For security reasons, the default implementation disallows all connections.
+	// If you want to allow all connections, you must specifically allow it.
+	err := server.AddHook(new(auth.AllowHook), nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:      "t1",
+		Address: ":1883",
 	})
+	err = server.AddListener(tcp)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -39,12 +53,9 @@ func main() {
 			log.Fatal(err)
 		}
 	}()
-	fmt.Println(aurora.BgMagenta("  Started!  "))
 
 	<-done
-	fmt.Println(aurora.BgRed("  Caught Signal  "))
-
-	server.Close()
-	fmt.Println(aurora.BgGreen("  Finished  "))
-
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
 }

examples/tls/main.go

@@ -1,17 +1,19 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
 package main
 
 import (
-	"fmt"
+	"crypto/tls"
 	"log"
 	"os"
 	"os/signal"
 	"syscall"
 
-	"github.com/logrusorgru/aurora"
-
-	mqtt "github.com/mochi-co/mqtt/server"
-	"github.com/mochi-co/mqtt/server/listeners"
-	"github.com/mochi-co/mqtt/server/listeners/auth"
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/listeners"
 )
 
 var (
@@ -55,51 +57,69 @@ func main() {
 		done <- true
 	}()
 
-	fmt.Println(aurora.Magenta("Mochi MQTT Server initializing..."), aurora.Cyan("TLS/SSL"))
-
-	server := mqtt.New()
-	tcp := listeners.NewTCP("t1", ":1883")
-	err := server.AddListener(tcp, &listeners.Config{
-		Auth: new(auth.Allow),
-		TLS: &listeners.TLS{
-			Certificate: testCertificate,
-			PrivateKey:  testPrivateKey,
-		},
-	})
+	cert, err := tls.X509KeyPair(testCertificate, testPrivateKey)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	ws := listeners.NewWebsocket("ws1", ":1882")
-	err = server.AddListener(ws, &listeners.Config{
-		Auth: new(auth.Allow),
-		TLS: &listeners.TLS{
-			Certificate: testCertificate,
-			PrivateKey:  testPrivateKey,
-		},
+	// Basic TLS Config
+	tlsConfig := &tls.Config{
+		Certificates: []tls.Certificate{cert},
+	}
+
+	// Optionally, if you want clients to authenticate only with certs issued by your CA,
+	// you might want to use something like this:
+	// certPool := x509.NewCertPool()
+	// _ = certPool.AppendCertsFromPEM(caCertPem)
+	// tlsConfig := &tls.Config{
+	//	ClientCAs: certPool,
+	// 	ClientAuth: tls.RequireAndVerifyClientCert,
+	// }
+
+	server := mqtt.New(nil)
+	_ = server.AddHook(new(auth.AllowHook), nil)
+
+	tcp := listeners.NewTCP(listeners.Config{
+		ID:        "t1",
+		Address:   ":1883",
+		TLSConfig: tlsConfig,
 	})
+	err = server.AddListener(tcp)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	stats := listeners.NewHTTPStats("stats", ":8080")
-	err = server.AddListener(stats, &listeners.Config{
-		Auth: new(auth.Allow),
-		TLS: &listeners.TLS{
-			Certificate: testCertificate,
-			PrivateKey:  testPrivateKey,
-		},
+	ws := listeners.NewWebsocket(listeners.Config{
+		ID:        "ws1",
+		Address:   ":1882",
+		TLSConfig: tlsConfig,
 	})
+	err = server.AddListener(ws)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	go server.Serve()
-	fmt.Println(aurora.BgMagenta("  Started!  "))
+	stats := listeners.NewHTTPStats(
+		listeners.Config{
+			ID:        "stats",
+			Address:   ":8080",
+			TLSConfig: tlsConfig,
+		}, server.Info,
+	)
+	err = server.AddListener(stats)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	go func() {
+		err := server.Serve()
+		if err != nil {
+			log.Fatal(err)
+		}
+	}()
 
 	<-done
-	fmt.Println(aurora.BgRed("  Caught Signal  "))
-
-	server.Close()
-	fmt.Println(aurora.BgGreen("  Finished  "))
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
 }

examples/websocket/main.go

@@ -1,16 +1,18 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
 package main
 
 import (
-	"fmt"
 	"log"
 	"os"
 	"os/signal"
 	"syscall"
 
-	"github.com/logrusorgru/aurora"
-
-	mqtt "github.com/mochi-co/mqtt/server"
-	"github.com/mochi-co/mqtt/server/listeners"
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/auth"
+	"github.com/mochi-mqtt/server/v2/listeners"
 )
 
 func main() {
@@ -22,11 +24,14 @@ func main() {
 		done <- true
 	}()
 
-	fmt.Println(aurora.Magenta("Mochi MQTT Server initializing..."), aurora.Cyan("TCP"))
+	server := mqtt.New(nil)
+	_ = server.AddHook(new(auth.AllowHook), nil)
 
-	server := mqtt.New()
-	ws := listeners.NewWebsocket("ws1", ":1882")
-	err = server.AddListener(ws, nil)
+	ws := listeners.NewWebsocket(listeners.Config{
+		ID:      "ws1",
+		Address: ":1882",
+	})
+	err := server.AddListener(ws)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -37,11 +42,9 @@ func main() {
 			log.Fatal(err)
 		}
 	}()
-	fmt.Println(aurora.BgMagenta("  Started!  "))
 
 	<-done
-	fmt.Println(aurora.BgRed("  Caught Signal  "))
-
-	server.Close()
-	fmt.Println(aurora.BgGreen("  Finished  "))
+	server.Log.Warn("caught signal, stopping...")
+	_ = server.Close()
+	server.Log.Info("main.go finished")
 }

go.mod

@@ -1,18 +1,37 @@
-module github.com/mochi-co/mqtt
+module github.com/mochi-mqtt/server/v2
 
-go 1.13
+go 1.21
 
 require (
+	github.com/alicebob/miniredis/v2 v2.23.0
 	github.com/asdine/storm v2.1.2+incompatible
-	github.com/asdine/storm/v3 v3.1.0
-	github.com/gorilla/websocket v1.4.1
-	github.com/jinzhu/copier v0.0.0-20190924061706-b57f9002281a
-	github.com/krylovsk/mqtt-benchmark v0.1.1 // indirect
-	github.com/logrusorgru/aurora v0.0.0-20191116043053-66b7ad493a23
-	github.com/rs/xid v1.2.1
-	github.com/stretchr/testify v1.4.0
-	go.etcd.io/bbolt v1.3.3
-	golang.org/x/net v0.0.0-20191209160850-c0dbc17a3553 // indirect
+	github.com/asdine/storm/v3 v3.2.1
+	github.com/go-redis/redis/v8 v8.11.5
+	github.com/gorilla/websocket v1.5.0
+	github.com/jinzhu/copier v0.3.5
+	github.com/rs/xid v1.4.0
+	github.com/stretchr/testify v1.7.1
+	github.com/timshannon/badgerhold v1.0.0
+	go.etcd.io/bbolt v1.3.5
+	gopkg.in/yaml.v3 v3.0.1
 )
 
-replace github.com/mochi-co/debug => /Users/mochimochi/Development/Go/src/github.com/mochi-co/debug
+require (
+	github.com/AndreasBriese/bbloom v0.0.0-20190825152654-46b345b51c96 // indirect
+	github.com/alicebob/gopher-json v0.0.0-20200520072559-a9ecdc9d1d3a // indirect
+	github.com/cespare/xxhash/v2 v2.1.2 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/dgraph-io/badger v1.6.0 // indirect
+	github.com/dgryski/go-farm v0.0.0-20190423205320-6a90982ecee2 // indirect
+	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/dustin/go-humanize v1.0.0 // indirect
+	github.com/golang/protobuf v1.5.0 // indirect
+	github.com/golang/snappy v0.0.3 // indirect
+	github.com/google/go-cmp v0.5.8 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/yuin/gopher-lua v0.0.0-20210529063254-f4c35e4016d9 // indirect
+	golang.org/x/net v0.17.0 // indirect
+	golang.org/x/sys v0.13.0 // indirect
+	google.golang.org/protobuf v1.33.0 // indirect
+)

go.sum

@@ -1,66 +1,139 @@
+github.com/AndreasBriese/bbloom v0.0.0-20190306092124-e2d15f34fcf9/go.mod h1:bOvUY6CB00SOBii9/FifXqc0awNKxLFCL/+pkDPuyl8=
+github.com/AndreasBriese/bbloom v0.0.0-20190825152654-46b345b51c96 h1:cTp8I5+VIoKjsnZuH8vjyaysT/ses3EvZeaV/1UkF2M=
+github.com/AndreasBriese/bbloom v0.0.0-20190825152654-46b345b51c96/go.mod h1:bOvUY6CB00SOBii9/FifXqc0awNKxLFCL/+pkDPuyl8=
+github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
 github.com/DataDog/zstd v1.4.1 h1:3oxKN3wbHibqx897utPC2LTQU4J+IHWWJO+glkAkpFM=
 github.com/DataDog/zstd v1.4.1/go.mod h1:1jcaCB/ufaK+sKp1NBhlGmpz41jOoPQ35bpF36t7BBo=
-github.com/GaryBoone/GoStats v0.0.0-20130122001700-1993eafbef57 h1:EUQH/F+mzJBs53c75r7R5zdM/kz7BHXoWBFsVXzadVw=
-github.com/GaryBoone/GoStats v0.0.0-20130122001700-1993eafbef57/go.mod h1:5zDl2HgTb/k5i9op9y6IUSiuVkZFpUrWGQbZc9tNR40=
 github.com/Sereal/Sereal v0.0.0-20190618215532-0b8ac451a863 h1:BRrxwOZBolJN4gIwvZMJY1tzqBvQgpaZiQRuIDD40jM=
 github.com/Sereal/Sereal v0.0.0-20190618215532-0b8ac451a863/go.mod h1:D0JMgToj/WdxCgd30Kc1UcA9E+WdZoJqeVOuYW7iTBM=
+github.com/alicebob/gopher-json v0.0.0-20200520072559-a9ecdc9d1d3a h1:HbKu58rmZpUGpz5+4FfNmIU+FmZg2P3Xaj2v2bfNWmk=
+github.com/alicebob/gopher-json v0.0.0-20200520072559-a9ecdc9d1d3a/go.mod h1:SGnFV6hVsYE877CKEZ6tDNTjaSXYUk6QqoIK6PrAtcc=
+github.com/alicebob/miniredis/v2 v2.23.0 h1:+lwAJYjvvdIVg6doFHuotFjueJ/7KY10xo/vm3X3Scw=
+github.com/alicebob/miniredis/v2 v2.23.0/go.mod h1:XNqvJdQJv5mSuVMc0ynneafpnL/zv52acZ6kqeS0t88=
+github.com/armon/consul-api v0.0.0-20180202201655-eb2c6b5be1b6/go.mod h1:grANhF5doyWs3UAsr3K4I6qtAmlQcZDesFNEHPZAzj8=
 github.com/asdine/storm v2.1.2+incompatible h1:dczuIkyqwY2LrtXPz8ixMrU/OFgZp71kbKTHGrXYt/Q=
 github.com/asdine/storm v2.1.2+incompatible/go.mod h1:RarYDc9hq1UPLImuiXK3BIWPJLdIygvV3PsInK0FbVQ=
-github.com/asdine/storm/v3 v3.1.0 h1:yrpSNS+E7ef5Y5KjyZDeyW72Dl17lYG7oZ7eUoWvo5s=
-github.com/asdine/storm/v3 v3.1.0/go.mod h1:letAoLCXz4UfodwNgMNILMb2oRH+su337ZfHnkRzqDA=
-github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/asdine/storm/v3 v3.2.1 h1:I5AqhkPK6nBZ/qJXySdI7ot5BlXSZ7qvDY1zAn5ZJac=
+github.com/asdine/storm/v3 v3.2.1/go.mod h1:LEpXwGt4pIqrE/XcTvCnZHT5MgZCV6Ub9q7yQzOFWr0=
+github.com/cespare/xxhash/v2 v2.1.2 h1:YRXhKfTDauu4ajMg1TPgFO5jnlC2HCbmLXMcTG5cbYE=
+github.com/cespare/xxhash/v2 v2.1.2/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
+github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
+github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
+github.com/coreos/etcd v3.3.10+incompatible/go.mod h1:uF7uidLiAD3TWHmW31ZFd/JWoc32PjwdhPthX9715RE=
+github.com/coreos/go-etcd v2.0.0+incompatible/go.mod h1:Jez6KQU2B/sWsbdaef3ED8NzMklzPG4d5KIOhIy30Tk=
+github.com/coreos/go-semver v0.2.0/go.mod h1:nnelYz7RCh+5ahJtPPxZlU+153eP4D4r3EedlOD2RNk=
+github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/eclipse/paho.mqtt.golang v1.2.0 h1:1F8mhG9+aO5/xpdtFkW4SxOJB67ukuDC3t2y2qayIX0=
-github.com/eclipse/paho.mqtt.golang v1.2.0/go.mod h1:H9keYFcgq3Qr5OUJm/JZI/i6U7joQ8SYLhZwfeOo6Ts=
+github.com/dgraph-io/badger v1.6.0 h1:DshxFxZWXUcO0xX476VJC07Xsr6ZCBVRHKZ93Oh7Evo=
+github.com/dgraph-io/badger v1.6.0/go.mod h1:zwt7syl517jmP8s94KqSxTlM6IMsdhYy6psNgSztDR4=
+github.com/dgryski/go-farm v0.0.0-20190423205320-6a90982ecee2 h1:tdlZCpZ/P9DhczCTSixgIKmwPv6+wP5DGjqLYw5SUiA=
+github.com/dgryski/go-farm v0.0.0-20190423205320-6a90982ecee2/go.mod h1:SqUrOPUnsFjfmXRMNPybcSiG0BgUW2AuFH8PAnS2iTw=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/dustin/go-humanize v1.0.0 h1:VSnTsYCnlFHaM2/igO1h6X3HA71jcobQuxemgkq4zYo=
+github.com/dustin/go-humanize v1.0.0/go.mod h1:HtrtbFcZ19U5GC7JDqmcUSB87Iq5E25KnS6fMYU6eOk=
+github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
+github.com/fsnotify/fsnotify v1.4.9 h1:hsms1Qyu0jgnwNXIxa+/V/PDsU6CfLf6CNO8H7IWoS4=
+github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
+github.com/go-redis/redis/v8 v8.11.5 h1:AcZZR7igkdvfVmQTPnu9WE37LRrO/YrBH5zWyjDC0oI=
+github.com/go-redis/redis/v8 v8.11.5/go.mod h1:gREzHqY1hg6oD9ngVRbLStwAWKhA0FEgq8Jd4h5lpwo=
 github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
-github.com/golang/protobuf v1.3.2 h1:6nsPYzhq5kReh6QImI3k5qWzO4PEbvbIW2cwSfR/6xs=
 github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
-github.com/golang/snappy v0.0.1 h1:Qgr9rKW7uDUkrbSmQeiDsGa8SjGyCOGtuasMWwvp2P4=
+github.com/golang/protobuf v1.5.0 h1:LUVKkCeviFUMKqHa4tXIIij/lbhnMbP7Fn5wKdKkRh4=
+github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
 github.com/golang/snappy v0.0.1/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
-github.com/gorilla/websocket v1.4.1 h1:q7AeDBpnBk8AogcD4DSag/Ukw/KV+YhzLj2bP5HvKCM=
-github.com/gorilla/websocket v1.4.1/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
-github.com/jinzhu/copier v0.0.0-20190924061706-b57f9002281a h1:zPPuIq2jAWWPTrGt70eK/BSch+gFAGrNzecsoENgu2o=
-github.com/jinzhu/copier v0.0.0-20190924061706-b57f9002281a/go.mod h1:yL958EeXv8Ylng6IfnvG4oflryUi3vgA3xPs9hmII1s=
+github.com/golang/snappy v0.0.3 h1:fHPg5GQYlCeLIPB9BZqMVR5nR9A+IM5zcgeTdjMYmLA=
+github.com/golang/snappy v0.0.3/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg=
+github.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWmnc=
+github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/hashicorp/hcl v1.0.0/go.mod h1:E5yfLk+7swimpb2L/Alb/PJmXilQ/rhwaUYs4T20WEQ=
+github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
+github.com/jinzhu/copier v0.3.5 h1:GlvfUwHk62RokgqVNvYsku0TATCF7bAHVwEXoBh3iJg=
+github.com/jinzhu/copier v0.3.5/go.mod h1:DfbEm0FYsaqBcKcFuvmOZb218JkPGtvSHsKg8S8hyyg=
 github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
-github.com/krylovsk/mqtt-benchmark v0.1.1 h1:ErPkllMHrX5dAGzWBNH+yYLY/kIufGEBWOPOmOSilmg=
-github.com/krylovsk/mqtt-benchmark v0.1.1/go.mod h1:ud2sw14D+GdIeJGOh9ZZnBfjAVXzPyHQl58Yagk5P9w=
-github.com/logrusorgru/aurora v0.0.0-20191116043053-66b7ad493a23 h1:Wp7NjqGKGN9te9N/rvXYRhlVcrulGdxnz8zadXWs7fc=
-github.com/logrusorgru/aurora v0.0.0-20191116043053-66b7ad493a23/go.mod h1:7rIyQOR62GCctdiQpZ/zOJlFyk6y+94wXzv6RNZgaR4=
+github.com/magiconair/properties v1.8.0/go.mod h1:PppfXfuXeibc/6YijjN8zIbojt8czPbwD3XqdrwzmxQ=
+github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
+github.com/mitchellh/mapstructure v1.1.2/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
+github.com/nxadm/tail v1.4.8 h1:nPr65rt6Y5JFSKQO7qToXr7pePgD6Gwiw05lkbyAQTE=
+github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU=
+github.com/onsi/ginkgo v1.16.5 h1:8xi0RTUf59SOSfEtZMvwTvXYMzG4gV23XVHOZiXNtnE=
+github.com/onsi/ginkgo v1.16.5/go.mod h1:+E8gABHa3K6zRBolWtd+ROzc/U5bkGt0FwiG042wbpU=
+github.com/onsi/gomega v1.18.1 h1:M1GfJqGRrBrrGGsbxzV5dqM2U2ApXefZCQpkukxYRLE=
+github.com/onsi/gomega v1.18.1/go.mod h1:0q+aL8jAiMXy9hbwj2mr5GziHiwhAIQpFmmtT5hitRs=
+github.com/pelletier/go-toml v1.2.0/go.mod h1:5z9KED0ma1S8pY6P1sdut58dfprrGBbd/94hg7ilaic=
+github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/rs/xid v1.2.1 h1:mhH9Nq+C1fY2l1XIpgxIiUOfNpRBYH1kKcr+qfKgjRc=
-github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ=
+github.com/rs/xid v1.4.0 h1:qd7wPTDkN6KQx2VmMBLrpHkiyQwgFXRnkOLacUiaSNY=
+github.com/rs/xid v1.4.0/go.mod h1:trrq9SKmegXys3aeAKXMUTdJsYXVwGY3RLcfgqegfbg=
+github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g=
+github.com/spf13/afero v1.1.2/go.mod h1:j4pytiNVoe2o6bmDsKpLACNPDBIoEAkihy7loJ1B0CQ=
+github.com/spf13/cast v1.3.0/go.mod h1:Qx5cxh0v+4UWYiBimWS+eyWzqEqokIECu5etghLkUJE=
+github.com/spf13/cobra v0.0.5/go.mod h1:3K3wKZymM7VvHMDS9+Akkh4K60UwM26emMESw8tLCHU=
+github.com/spf13/jwalterweatherman v1.0.0/go.mod h1:cQK4TGJAtQXfYWX+Ddv3mKDzgVb68N+wFjFa4jdeBTo=
+github.com/spf13/pflag v1.0.3/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4=
+github.com/spf13/viper v1.3.2/go.mod h1:ZiWeW+zYFKm7srdB9IoDzzZXaJaI5eL9QjNiN/DMA2s=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
-github.com/stretchr/testify v1.4.0 h1:2E4SXV/wtOkTonXsotYi4li6zVWxYlZuYNCXe9XRJyk=
-github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.1 h1:5TQK59W5E3v0r2duFAb7P95B6hEeOyEnHRa8MjYSMTY=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/timshannon/badgerhold v1.0.0 h1:LtqnDRVP7294FWRiZCIfQa6Tt0bGmlzbO8c364QC2Y8=
+github.com/timshannon/badgerhold v1.0.0/go.mod h1:Vv2Jj0PAfzqViEpGvJzLP8PY07x1iXLgKRuLY7bqPOE=
+github.com/ugorji/go/codec v0.0.0-20181204163529-d75b2dcb6bc8/go.mod h1:VFNgLljTbGfSG7qAOspJ7OScBnGdDN/yBr0sguwnwf0=
 github.com/vmihailenco/msgpack v4.0.4+incompatible h1:dSLoQfGFAo3F6OoNhwUmLwVgaUXK79GlxNBwueZn0xI=
 github.com/vmihailenco/msgpack v4.0.4+incompatible/go.mod h1:fy3FlTQTDXWkZ7Bh6AcGMlsjHatGryHQYUTf1ShIgkk=
-go.etcd.io/bbolt v1.3.3 h1:MUGmc65QhB3pIlaQ5bB4LwqSj6GIonVJXpZiaKNyaKk=
-go.etcd.io/bbolt v1.3.3/go.mod h1:IbVyRI1SCnLcuJnV2u8VeU0CEYM7e686BmAb1XKL+uU=
+github.com/xordataexchange/crypt v0.0.3-0.20170626215501-b2862e3d0a77/go.mod h1:aYKd//L2LvnjZzWKhF00oedf4jCCReLcmhLdhm1A27Q=
+github.com/yuin/gopher-lua v0.0.0-20210529063254-f4c35e4016d9 h1:k/gmLsJDWwWqbLCur2yWnJzwQEKRcAHXo6seXGuSwWw=
+github.com/yuin/gopher-lua v0.0.0-20210529063254-f4c35e4016d9/go.mod h1:E1AXubJBdNmFERAOucpDIxNzeGfLzg0mYh+UfMWdChA=
+go.etcd.io/bbolt v1.3.4/go.mod h1:G5EMThwa9y8QZGBClrRx5EY+Yw9kAhnjy3bSjsnlVTQ=
+go.etcd.io/bbolt v1.3.5 h1:XAzx9gjCb0Rxj7EoqcClPD1d5ZBxZJk0jbuoPHenBt0=
+go.etcd.io/bbolt v1.3.5/go.mod h1:G5EMThwa9y8QZGBClrRx5EY+Yw9kAhnjy3bSjsnlVTQ=
+golang.org/x/crypto v0.0.0-20181203042331-505ab145d0a9/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks=
-golang.org/x/net v0.0.0-20191011234655-491137f69257/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20191105084925-a882066a44e0/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
-golang.org/x/net v0.0.0-20191209160850-c0dbc17a3553 h1:efeOvDhwQ29Dj3SdAV/MJf8oukgn+8D8WgaCaRMchF8=
-golang.org/x/net v0.0.0-20191209160850-c0dbc17a3553/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.17.0 h1:pVaXccu2ozPjCXewfr1S7xza/zcXTity9cCdXQYSjIM=
+golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE=
+golang.org/x/sys v0.0.0-20181205085412-a5c9d58dba9a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190204203706-41f3e6584952/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
-golang.org/x/sys v0.0.0-20191105142833-ac3223d80179 h1:IqVhUQp5B9ARnZUcfqXy6zP+A+YuPpP7IFo8gFeCOzU=
-golang.org/x/sys v0.0.0-20191105142833-ac3223d80179/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190626221950-04f50cda93cb/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200202164722-d101bd2416d5/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
+golang.org/x/text v0.13.0 h1:ablQoSUd0tRdKxZewP80B+BaqeKJuVhuRxj/dkrun3k=
+golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 google.golang.org/appengine v1.6.5 h1:tycE03LOZYQNhDpS27tcQdAzLCVMaj7QT2SXxebnpCM=
 google.golang.org/appengine v1.6.5/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCIDZVag1xfc=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
+google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI=
+google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v2 v2.2.2 h1:ZCJp+EgiOT7lHqUV2J862kp8Qj64Jo6az82+3Td9dZw=
+gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ=
+gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

hooks.go

@@ -0,0 +1,861 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co, thedevop, dgduncan
+
+package mqtt
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"sync"
+	"sync/atomic"
+
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+)
+
+const (
+	SetOptions byte = iota
+	OnSysInfoTick
+	OnStarted
+	OnStopped
+	OnConnectAuthenticate
+	OnACLCheck
+	OnConnect
+	OnSessionEstablish
+	OnSessionEstablished
+	OnDisconnect
+	OnAuthPacket
+	OnPacketRead
+	OnPacketEncode
+	OnPacketSent
+	OnPacketProcessed
+	OnSubscribe
+	OnSubscribed
+	OnSelectSubscribers
+	OnUnsubscribe
+	OnUnsubscribed
+	OnPublish
+	OnPublished
+	OnPublishDropped
+	OnRetainMessage
+	OnRetainPublished
+	OnQosPublish
+	OnQosComplete
+	OnQosDropped
+	OnPacketIDExhausted
+	OnWill
+	OnWillSent
+	OnClientExpired
+	OnRetainedExpired
+	StoredClients
+	StoredSubscriptions
+	StoredInflightMessages
+	StoredRetainedMessages
+	StoredSysInfo
+)
+
+var (
+	// ErrInvalidConfigType indicates a different Type of config value was expected to what was received.
+	ErrInvalidConfigType = errors.New("invalid config type provided")
+)
+
+// HookLoadConfig contains the hook and configuration as loaded from a configuration (usually file).
+type HookLoadConfig struct {
+	Hook   Hook
+	Config any
+}
+
+// Hook provides an interface of handlers for different events which occur
+// during the lifecycle of the broker.
+type Hook interface {
+	ID() string
+	Provides(b byte) bool
+	Init(config any) error
+	Stop() error
+	SetOpts(l *slog.Logger, o *HookOptions)
+
+	OnStarted()
+	OnStopped()
+	OnConnectAuthenticate(cl *Client, pk packets.Packet) bool
+	OnACLCheck(cl *Client, topic string, write bool) bool
+	OnSysInfoTick(*system.Info)
+	OnConnect(cl *Client, pk packets.Packet) error
+	OnSessionEstablish(cl *Client, pk packets.Packet)
+	OnSessionEstablished(cl *Client, pk packets.Packet)
+	OnDisconnect(cl *Client, err error, expire bool)
+	OnAuthPacket(cl *Client, pk packets.Packet) (packets.Packet, error)
+	OnPacketRead(cl *Client, pk packets.Packet) (packets.Packet, error) // triggers when a new packet is received by a client, but before packet validation
+	OnPacketEncode(cl *Client, pk packets.Packet) packets.Packet        // modify a packet before it is byte-encoded and written to the client
+	OnPacketSent(cl *Client, pk packets.Packet, b []byte)               // triggers when packet bytes have been written to the client
+	OnPacketProcessed(cl *Client, pk packets.Packet, err error)         // triggers after a packet from the client been processed (handled)
+	OnSubscribe(cl *Client, pk packets.Packet) packets.Packet
+	OnSubscribed(cl *Client, pk packets.Packet, reasonCodes []byte)
+	OnSelectSubscribers(subs *Subscribers, pk packets.Packet) *Subscribers
+	OnUnsubscribe(cl *Client, pk packets.Packet) packets.Packet
+	OnUnsubscribed(cl *Client, pk packets.Packet)
+	OnPublish(cl *Client, pk packets.Packet) (packets.Packet, error)
+	OnPublished(cl *Client, pk packets.Packet)
+	OnPublishDropped(cl *Client, pk packets.Packet)
+	OnRetainMessage(cl *Client, pk packets.Packet, r int64)
+	OnRetainPublished(cl *Client, pk packets.Packet)
+	OnQosPublish(cl *Client, pk packets.Packet, sent int64, resends int)
+	OnQosComplete(cl *Client, pk packets.Packet)
+	OnQosDropped(cl *Client, pk packets.Packet)
+	OnPacketIDExhausted(cl *Client, pk packets.Packet)
+	OnWill(cl *Client, will Will) (Will, error)
+	OnWillSent(cl *Client, pk packets.Packet)
+	OnClientExpired(cl *Client)
+	OnRetainedExpired(filter string)
+	StoredClients() ([]storage.Client, error)
+	StoredSubscriptions() ([]storage.Subscription, error)
+	StoredInflightMessages() ([]storage.Message, error)
+	StoredRetainedMessages() ([]storage.Message, error)
+	StoredSysInfo() (storage.SystemInfo, error)
+}
+
+// HookOptions contains values which are inherited from the server on initialisation.
+type HookOptions struct {
+	Capabilities *Capabilities
+}
+
+// Hooks is a slice of Hook interfaces to be called in sequence.
+type Hooks struct {
+	Log        *slog.Logger   // a logger for the hook (from the server)
+	internal   atomic.Value   // a slice of []Hook
+	wg         sync.WaitGroup // a waitgroup for syncing hook shutdown
+	qty        int64          // the number of hooks in use
+	sync.Mutex                // a mutex for locking when adding hooks
+}
+
+// Len returns the number of hooks added.
+func (h *Hooks) Len() int64 {
+	return atomic.LoadInt64(&h.qty)
+}
+
+// Provides returns true if any one hook provides any of the requested hook methods.
+func (h *Hooks) Provides(b ...byte) bool {
+	for _, hook := range h.GetAll() {
+		for _, hb := range b {
+			if hook.Provides(hb) {
+				return true
+			}
+		}
+	}
+
+	return false
+}
+
+// Add adds and initializes a new hook.
+func (h *Hooks) Add(hook Hook, config any) error {
+	h.Lock()
+	defer h.Unlock()
+
+	err := hook.Init(config)
+	if err != nil {
+		return fmt.Errorf("failed initialising %s hook: %w", hook.ID(), err)
+	}
+
+	i, ok := h.internal.Load().([]Hook)
+	if !ok {
+		i = []Hook{}
+	}
+
+	i = append(i, hook)
+	h.internal.Store(i)
+	atomic.AddInt64(&h.qty, 1)
+	h.wg.Add(1)
+
+	return nil
+}
+
+// GetAll returns a slice of all the hooks.
+func (h *Hooks) GetAll() []Hook {
+	i, ok := h.internal.Load().([]Hook)
+	if !ok {
+		return []Hook{}
+	}
+
+	return i
+}
+
+// Stop indicates all attached hooks to gracefully end.
+func (h *Hooks) Stop() {
+	go func() {
+		for _, hook := range h.GetAll() {
+			h.Log.Info("stopping hook", "hook", hook.ID())
+			if err := hook.Stop(); err != nil {
+				h.Log.Debug("problem stopping hook", "error", err, "hook", hook.ID())
+			}
+
+			h.wg.Done()
+		}
+	}()
+
+	h.wg.Wait()
+}
+
+// OnSysInfoTick is called when the $SYS topic values are published out.
+func (h *Hooks) OnSysInfoTick(sys *system.Info) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnSysInfoTick) {
+			hook.OnSysInfoTick(sys)
+		}
+	}
+}
+
+// OnStarted is called when the server has successfully started.
+func (h *Hooks) OnStarted() {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnStarted) {
+			hook.OnStarted()
+		}
+	}
+}
+
+// OnStopped is called when the server has successfully stopped.
+func (h *Hooks) OnStopped() {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnStopped) {
+			hook.OnStopped()
+		}
+	}
+}
+
+// OnConnect is called when a new client connects, and may return a packets.Code as an error to halt the connection.
+func (h *Hooks) OnConnect(cl *Client, pk packets.Packet) error {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnConnect) {
+			err := hook.OnConnect(cl, pk)
+			if err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// OnSessionEstablish is called right after a new client connects and authenticates and right before
+// the session is established and CONNACK is sent.
+func (h *Hooks) OnSessionEstablish(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnSessionEstablish) {
+			hook.OnSessionEstablish(cl, pk)
+		}
+	}
+}
+
+// OnSessionEstablished is called when a new client establishes a session (after OnConnect).
+func (h *Hooks) OnSessionEstablished(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnSessionEstablished) {
+			hook.OnSessionEstablished(cl, pk)
+		}
+	}
+}
+
+// OnDisconnect is called when a client is disconnected for any reason.
+func (h *Hooks) OnDisconnect(cl *Client, err error, expire bool) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnDisconnect) {
+			hook.OnDisconnect(cl, err, expire)
+		}
+	}
+}
+
+// OnPacketRead is called when a packet is received from a client.
+func (h *Hooks) OnPacketRead(cl *Client, pk packets.Packet) (pkx packets.Packet, err error) {
+	pkx = pk
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnPacketRead) {
+			npk, err := hook.OnPacketRead(cl, pkx)
+			if err != nil && errors.Is(err, packets.ErrRejectPacket) {
+				h.Log.Debug("packet rejected", "hook", hook.ID(), "packet", pkx)
+				return pk, err
+			} else if err != nil {
+				continue
+			}
+
+			pkx = npk
+		}
+	}
+
+	return
+}
+
+// OnAuthPacket is called when an auth packet is received. It is intended to allow developers
+// to create their own auth packet handling mechanisms.
+func (h *Hooks) OnAuthPacket(cl *Client, pk packets.Packet) (pkx packets.Packet, err error) {
+	pkx = pk
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnAuthPacket) {
+			npk, err := hook.OnAuthPacket(cl, pkx)
+			if err != nil {
+				return pk, err
+			}
+
+			pkx = npk
+		}
+	}
+
+	return
+}
+
+// OnPacketEncode is called immediately before a packet is encoded to be sent to a client.
+func (h *Hooks) OnPacketEncode(cl *Client, pk packets.Packet) packets.Packet {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnPacketEncode) {
+			pk = hook.OnPacketEncode(cl, pk)
+		}
+	}
+
+	return pk
+}
+
+// OnPacketProcessed is called when a packet has been received and successfully handled by the broker.
+func (h *Hooks) OnPacketProcessed(cl *Client, pk packets.Packet, err error) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnPacketProcessed) {
+			hook.OnPacketProcessed(cl, pk, err)
+		}
+	}
+}
+
+// OnPacketSent is called when a packet has been sent to a client. It takes a bytes parameter
+// containing the bytes sent.
+func (h *Hooks) OnPacketSent(cl *Client, pk packets.Packet, b []byte) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnPacketSent) {
+			hook.OnPacketSent(cl, pk, b)
+		}
+	}
+}
+
+// OnSubscribe is called when a client subscribes to one or more filters. This method
+// differs from OnSubscribed in that it allows you to modify the subscription values
+// before the packet is processed. The return values of the hook methods are passed-through
+// in the order the hooks were attached.
+func (h *Hooks) OnSubscribe(cl *Client, pk packets.Packet) packets.Packet {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnSubscribe) {
+			pk = hook.OnSubscribe(cl, pk)
+		}
+	}
+	return pk
+}
+
+// OnSubscribed is called when a client subscribes to one or more filters.
+func (h *Hooks) OnSubscribed(cl *Client, pk packets.Packet, reasonCodes []byte) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnSubscribed) {
+			hook.OnSubscribed(cl, pk, reasonCodes)
+		}
+	}
+}
+
+// OnSelectSubscribers is called when subscribers have been collected for a topic, but before
+// shared subscription subscribers have been selected. This hook can be used to programmatically
+// remove or add clients to a publish to subscribers process, or to select the subscriber for a shared
+// group in a custom manner (such as based on client id, ip, etc).
+func (h *Hooks) OnSelectSubscribers(subs *Subscribers, pk packets.Packet) *Subscribers {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnSelectSubscribers) {
+			subs = hook.OnSelectSubscribers(subs, pk)
+		}
+	}
+	return subs
+}
+
+// OnUnsubscribe is called when a client unsubscribes from one or more filters. This method
+// differs from OnUnsubscribed in that it allows you to modify the unsubscription values
+// before the packet is processed. The return values of the hook methods are passed-through
+// in the order the hooks were attached.
+func (h *Hooks) OnUnsubscribe(cl *Client, pk packets.Packet) packets.Packet {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnUnsubscribe) {
+			pk = hook.OnUnsubscribe(cl, pk)
+		}
+	}
+	return pk
+}
+
+// OnUnsubscribed is called when a client unsubscribes from one or more filters.
+func (h *Hooks) OnUnsubscribed(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnUnsubscribed) {
+			hook.OnUnsubscribed(cl, pk)
+		}
+	}
+}
+
+// OnPublish is called when a client publishes a message. This method differs from OnPublished
+// in that it allows you to modify you to modify the incoming packet before it is processed.
+// The return values of the hook methods are passed-through in the order the hooks were attached.
+func (h *Hooks) OnPublish(cl *Client, pk packets.Packet) (pkx packets.Packet, err error) {
+	pkx = pk
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnPublish) {
+			npk, err := hook.OnPublish(cl, pkx)
+			if err != nil {
+				if errors.Is(err, packets.ErrRejectPacket) {
+					h.Log.Debug("publish packet rejected",
+						"error", err,
+						"hook", hook.ID(),
+						"packet", pkx)
+					return pk, err
+				}
+				h.Log.Error("publish packet error",
+					"error", err,
+					"hook", hook.ID(),
+					"packet", pkx)
+				return pk, err
+			}
+			pkx = npk
+		}
+	}
+
+	return
+}
+
+// OnPublished is called when a client has published a message to subscribers.
+func (h *Hooks) OnPublished(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnPublished) {
+			hook.OnPublished(cl, pk)
+		}
+	}
+}
+
+// OnPublishDropped is called when a message to a client was dropped instead of delivered
+// such as when a client is too slow to respond.
+func (h *Hooks) OnPublishDropped(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnPublishDropped) {
+			hook.OnPublishDropped(cl, pk)
+		}
+	}
+}
+
+// OnRetainMessage is called then a published message is retained.
+func (h *Hooks) OnRetainMessage(cl *Client, pk packets.Packet, r int64) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnRetainMessage) {
+			hook.OnRetainMessage(cl, pk, r)
+		}
+	}
+}
+
+// OnRetainPublished is called when a retained message is published.
+func (h *Hooks) OnRetainPublished(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnRetainPublished) {
+			hook.OnRetainPublished(cl, pk)
+		}
+	}
+}
+
+// OnQosPublish is called when a publish packet with Qos >= 1 is issued to a subscriber.
+// In other words, this method is called when a new inflight message is created or resent.
+// It is typically used to store a new inflight message.
+func (h *Hooks) OnQosPublish(cl *Client, pk packets.Packet, sent int64, resends int) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnQosPublish) {
+			hook.OnQosPublish(cl, pk, sent, resends)
+		}
+	}
+}
+
+// OnQosComplete is called when the Qos flow for a message has been completed.
+// In other words, when an inflight message is resolved.
+// It is typically used to delete an inflight message from a store.
+func (h *Hooks) OnQosComplete(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnQosComplete) {
+			hook.OnQosComplete(cl, pk)
+		}
+	}
+}
+
+// OnQosDropped is called the Qos flow for a message expires. In other words, when
+// an inflight message expires or is abandoned. It is typically used to delete an
+// inflight message from a store.
+func (h *Hooks) OnQosDropped(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnQosDropped) {
+			hook.OnQosDropped(cl, pk)
+		}
+	}
+}
+
+// OnPacketIDExhausted is called when the client runs out of unused packet ids to
+// assign to a packet.
+func (h *Hooks) OnPacketIDExhausted(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnPacketIDExhausted) {
+			hook.OnPacketIDExhausted(cl, pk)
+		}
+	}
+}
+
+// OnWill is called when a client disconnects and publishes an LWT message. This method
+// differs from OnWillSent in that it allows you to modify the LWT message before it is
+// published. The return values of the hook methods are passed-through in the order
+// the hooks were attached.
+func (h *Hooks) OnWill(cl *Client, will Will) Will {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnWill) {
+			mlwt, err := hook.OnWill(cl, will)
+			if err != nil {
+				h.Log.Error("parse will error",
+					"error", err,
+					"hook", hook.ID(),
+					"will", will)
+				continue
+			}
+			will = mlwt
+		}
+	}
+
+	return will
+}
+
+// OnWillSent is called when an LWT message has been issued from a disconnecting client.
+func (h *Hooks) OnWillSent(cl *Client, pk packets.Packet) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnWillSent) {
+			hook.OnWillSent(cl, pk)
+		}
+	}
+}
+
+// OnClientExpired is called when a client session has expired and should be deleted.
+func (h *Hooks) OnClientExpired(cl *Client) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnClientExpired) {
+			hook.OnClientExpired(cl)
+		}
+	}
+}
+
+// OnRetainedExpired is called when a retained message has expired and should be deleted.
+func (h *Hooks) OnRetainedExpired(filter string) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnRetainedExpired) {
+			hook.OnRetainedExpired(filter)
+		}
+	}
+}
+
+// StoredClients returns all clients, e.g. from a persistent store, is used to
+// populate the server clients list before start.
+func (h *Hooks) StoredClients() (v []storage.Client, err error) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(StoredClients) {
+			v, err := hook.StoredClients()
+			if err != nil {
+				h.Log.Error("failed to load clients", "error", err, "hook", hook.ID())
+				return v, err
+			}
+
+			if len(v) > 0 {
+				return v, nil
+			}
+		}
+	}
+
+	return
+}
+
+// StoredSubscriptions returns all subcriptions, e.g. from a persistent store, and is
+// used to populate the server subscriptions list before start.
+func (h *Hooks) StoredSubscriptions() (v []storage.Subscription, err error) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(StoredSubscriptions) {
+			v, err := hook.StoredSubscriptions()
+			if err != nil {
+				h.Log.Error("failed to load subscriptions", "error", err, "hook", hook.ID())
+				return v, err
+			}
+
+			if len(v) > 0 {
+				return v, nil
+			}
+		}
+	}
+
+	return
+}
+
+// StoredInflightMessages returns all inflight messages, e.g. from a persistent store,
+// and is used to populate the restored clients with inflight messages before start.
+func (h *Hooks) StoredInflightMessages() (v []storage.Message, err error) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(StoredInflightMessages) {
+			v, err := hook.StoredInflightMessages()
+			if err != nil {
+				h.Log.Error("failed to load inflight messages", "error", err, "hook", hook.ID())
+				return v, err
+			}
+
+			if len(v) > 0 {
+				return v, nil
+			}
+		}
+	}
+
+	return
+}
+
+// StoredRetainedMessages returns all retained messages, e.g. from a persistent store,
+// and is used to populate the server topics with retained messages before start.
+func (h *Hooks) StoredRetainedMessages() (v []storage.Message, err error) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(StoredRetainedMessages) {
+			v, err := hook.StoredRetainedMessages()
+			if err != nil {
+				h.Log.Error("failed to load retained messages", "error", err, "hook", hook.ID())
+				return v, err
+			}
+
+			if len(v) > 0 {
+				return v, nil
+			}
+		}
+	}
+
+	return
+}
+
+// StoredSysInfo returns a set of system info values.
+func (h *Hooks) StoredSysInfo() (v storage.SystemInfo, err error) {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(StoredSysInfo) {
+			v, err := hook.StoredSysInfo()
+			if err != nil {
+				h.Log.Error("failed to load $SYS info", "error", err, "hook", hook.ID())
+				return v, err
+			}
+
+			if v.Version != "" {
+				return v, nil
+			}
+		}
+	}
+
+	return
+}
+
+// OnConnectAuthenticate is called when a user attempts to authenticate with the server.
+// An implementation of this method MUST be used to allow or deny access to the
+// server (see hooks/auth/allow_all or basic). It can be used in custom hooks to
+// check connecting users against an existing user database.
+func (h *Hooks) OnConnectAuthenticate(cl *Client, pk packets.Packet) bool {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnConnectAuthenticate) {
+			if ok := hook.OnConnectAuthenticate(cl, pk); ok {
+				return true
+			}
+		}
+	}
+
+	return false
+}
+
+// OnACLCheck is called when a user attempts to publish or subscribe to a topic filter.
+// An implementation of this method MUST be used to allow or deny access to the
+// (see hooks/auth/allow_all or basic). It can be used in custom hooks to
+// check publishing and subscribing users against an existing permissions or roles database.
+func (h *Hooks) OnACLCheck(cl *Client, topic string, write bool) bool {
+	for _, hook := range h.GetAll() {
+		if hook.Provides(OnACLCheck) {
+			if ok := hook.OnACLCheck(cl, topic, write); ok {
+				return true
+			}
+		}
+	}
+
+	return false
+}
+
+// HookBase provides a set of default methods for each hook. It should be embedded in
+// all hooks.
+type HookBase struct {
+	Hook
+	Log  *slog.Logger
+	Opts *HookOptions
+}
+
+// ID returns the ID of the hook.
+func (h *HookBase) ID() string {
+	return "base"
+}
+
+// Provides indicates which methods a hook provides. The default is none - this method
+// should be overridden by the embedding hook.
+func (h *HookBase) Provides(b byte) bool {
+	return false
+}
+
+// Init performs any pre-start initializations for the hook, such as connecting to databases
+// or opening files.
+func (h *HookBase) Init(config any) error {
+	return nil
+}
+
+// SetOpts is called by the server to propagate internal values and generally should
+// not be called manually.
+func (h *HookBase) SetOpts(l *slog.Logger, opts *HookOptions) {
+	h.Log = l
+	h.Opts = opts
+}
+
+// Stop is called to gracefully shut down the hook.
+func (h *HookBase) Stop() error {
+	return nil
+}
+
+// OnStarted is called when the server starts.
+func (h *HookBase) OnStarted() {}
+
+// OnStopped is called when the server stops.
+func (h *HookBase) OnStopped() {}
+
+// OnSysInfoTick is called when the server publishes system info.
+func (h *HookBase) OnSysInfoTick(*system.Info) {}
+
+// OnConnectAuthenticate is called when a user attempts to authenticate with the server.
+func (h *HookBase) OnConnectAuthenticate(cl *Client, pk packets.Packet) bool {
+	return false
+}
+
+// OnACLCheck is called when a user attempts to subscribe or publish to a topic.
+func (h *HookBase) OnACLCheck(cl *Client, topic string, write bool) bool {
+	return false
+}
+
+// OnConnect is called when a new client connects.
+func (h *HookBase) OnConnect(cl *Client, pk packets.Packet) error {
+	return nil
+}
+
+// OnSessionEstablish is called right after a new client connects and authenticates and right before
+// the session is established and CONNACK is sent.
+func (h *HookBase) OnSessionEstablish(cl *Client, pk packets.Packet) {}
+
+// OnSessionEstablished is called when a new client establishes a session (after OnConnect).
+func (h *HookBase) OnSessionEstablished(cl *Client, pk packets.Packet) {}
+
+// OnDisconnect is called when a client is disconnected for any reason.
+func (h *HookBase) OnDisconnect(cl *Client, err error, expire bool) {}
+
+// OnAuthPacket is called when an auth packet is received from the client.
+func (h *HookBase) OnAuthPacket(cl *Client, pk packets.Packet) (packets.Packet, error) {
+	return pk, nil
+}
+
+// OnPacketRead is called when a packet is received.
+func (h *HookBase) OnPacketRead(cl *Client, pk packets.Packet) (packets.Packet, error) {
+	return pk, nil
+}
+
+// OnPacketEncode is called before a packet is byte-encoded and written to the client.
+func (h *HookBase) OnPacketEncode(cl *Client, pk packets.Packet) packets.Packet {
+	return pk
+}
+
+// OnPacketSent is called immediately after a packet is written to a client.
+func (h *HookBase) OnPacketSent(cl *Client, pk packets.Packet, b []byte) {}
+
+// OnPacketProcessed is called immediately after a packet from a client is processed.
+func (h *HookBase) OnPacketProcessed(cl *Client, pk packets.Packet, err error) {}
+
+// OnSubscribe is called when a client subscribes to one or more filters.
+func (h *HookBase) OnSubscribe(cl *Client, pk packets.Packet) packets.Packet {
+	return pk
+}
+
+// OnSubscribed is called when a client subscribes to one or more filters.
+func (h *HookBase) OnSubscribed(cl *Client, pk packets.Packet, reasonCodes []byte) {}
+
+// OnSelectSubscribers is called when selecting subscribers to receive a message.
+func (h *HookBase) OnSelectSubscribers(subs *Subscribers, pk packets.Packet) *Subscribers {
+	return subs
+}
+
+// OnUnsubscribe is called when a client unsubscribes from one or more filters.
+func (h *HookBase) OnUnsubscribe(cl *Client, pk packets.Packet) packets.Packet {
+	return pk
+}
+
+// OnUnsubscribed is called when a client unsubscribes from one or more filters.
+func (h *HookBase) OnUnsubscribed(cl *Client, pk packets.Packet) {}
+
+// OnPublish is called when a client publishes a message.
+func (h *HookBase) OnPublish(cl *Client, pk packets.Packet) (packets.Packet, error) {
+	return pk, nil
+}
+
+// OnPublished is called when a client has published a message to subscribers.
+func (h *HookBase) OnPublished(cl *Client, pk packets.Packet) {}
+
+// OnPublishDropped is called when a message to a client is dropped instead of being delivered.
+func (h *HookBase) OnPublishDropped(cl *Client, pk packets.Packet) {}
+
+// OnRetainMessage is called then a published message is retained.
+func (h *HookBase) OnRetainMessage(cl *Client, pk packets.Packet, r int64) {}
+
+// OnRetainPublished is called when a retained message is published.
+func (h *HookBase) OnRetainPublished(cl *Client, pk packets.Packet) {}
+
+// OnQosPublish is called when a publish packet with Qos > 1 is issued to a subscriber.
+func (h *HookBase) OnQosPublish(cl *Client, pk packets.Packet, sent int64, resends int) {}
+
+// OnQosComplete is called when the Qos flow for a message has been completed.
+func (h *HookBase) OnQosComplete(cl *Client, pk packets.Packet) {}
+
+// OnQosDropped is called the Qos flow for a message expires.
+func (h *HookBase) OnQosDropped(cl *Client, pk packets.Packet) {}
+
+// OnPacketIDExhausted is called when the client runs out of unused packet ids to assign to a packet.
+func (h *HookBase) OnPacketIDExhausted(cl *Client, pk packets.Packet) {}
+
+// OnWill is called when a client disconnects and publishes an LWT message.
+func (h *HookBase) OnWill(cl *Client, will Will) (Will, error) {
+	return will, nil
+}
+
+// OnWillSent is called when an LWT message has been issued from a disconnecting client.
+func (h *HookBase) OnWillSent(cl *Client, pk packets.Packet) {}
+
+// OnClientExpired is called when a client session has expired.
+func (h *HookBase) OnClientExpired(cl *Client) {}
+
+// OnRetainedExpired is called when a retained message for a topic has expired.
+func (h *HookBase) OnRetainedExpired(topic string) {}
+
+// StoredClients returns all clients from a store.
+func (h *HookBase) StoredClients() (v []storage.Client, err error) {
+	return
+}
+
+// StoredSubscriptions returns all subcriptions from a store.
+func (h *HookBase) StoredSubscriptions() (v []storage.Subscription, err error) {
+	return
+}
+
+// StoredInflightMessages returns all inflight messages from a store.
+func (h *HookBase) StoredInflightMessages() (v []storage.Message, err error) {
+	return
+}
+
+// StoredRetainedMessages returns all retained messages from a store.
+func (h *HookBase) StoredRetainedMessages() (v []storage.Message, err error) {
+	return
+}
+
+// StoredSysInfo returns a set of system info values.
+func (h *HookBase) StoredSysInfo() (v storage.SystemInfo, err error) {
+	return
+}

hooks/auth/allow_all.go

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package auth
+
+import (
+	"bytes"
+
+	"github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/packets"
+)
+
+// AllowHook is an authentication hook which allows connection access
+// for all users and read and write access to all topics.
+type AllowHook struct {
+	mqtt.HookBase
+}
+
+// ID returns the ID of the hook.
+func (h *AllowHook) ID() string {
+	return "allow-all-auth"
+}
+
+// Provides indicates which hook methods this hook provides.
+func (h *AllowHook) Provides(b byte) bool {
+	return bytes.Contains([]byte{
+		mqtt.OnConnectAuthenticate,
+		mqtt.OnACLCheck,
+	}, []byte{b})
+}
+
+// OnConnectAuthenticate returns true/allowed for all requests.
+func (h *AllowHook) OnConnectAuthenticate(cl *mqtt.Client, pk packets.Packet) bool {
+	return true
+}
+
+// OnACLCheck returns true/allowed for all checks.
+func (h *AllowHook) OnACLCheck(cl *mqtt.Client, topic string, write bool) bool {
+	return true
+}

hooks/auth/allow_all_test.go

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package auth
+
+import (
+	"testing"
+
+	"github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAllowAllID(t *testing.T) {
+	h := new(AllowHook)
+	require.Equal(t, "allow-all-auth", h.ID())
+}
+
+func TestAllowAllProvides(t *testing.T) {
+	h := new(AllowHook)
+	require.True(t, h.Provides(mqtt.OnACLCheck))
+	require.True(t, h.Provides(mqtt.OnConnectAuthenticate))
+	require.False(t, h.Provides(mqtt.OnPublished))
+}
+
+func TestAllowAllOnConnectAuthenticate(t *testing.T) {
+	h := new(AllowHook)
+	require.True(t, h.OnConnectAuthenticate(new(mqtt.Client), packets.Packet{}))
+}
+
+func TestAllowAllOnACLCheck(t *testing.T) {
+	h := new(AllowHook)
+	require.True(t, h.OnACLCheck(new(mqtt.Client), "any", true))
+}

hooks/auth/auth.go

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package auth
+
+import (
+	"bytes"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/packets"
+)
+
+// Options contains the configuration/rules data for the auth ledger.
+type Options struct {
+	Data   []byte
+	Ledger *Ledger
+}
+
+// Hook is an authentication hook which implements an auth ledger.
+type Hook struct {
+	mqtt.HookBase
+	config *Options
+	ledger *Ledger
+}
+
+// ID returns the ID of the hook.
+func (h *Hook) ID() string {
+	return "auth-ledger"
+}
+
+// Provides indicates which hook methods this hook provides.
+func (h *Hook) Provides(b byte) bool {
+	return bytes.Contains([]byte{
+		mqtt.OnConnectAuthenticate,
+		mqtt.OnACLCheck,
+	}, []byte{b})
+}
+
+// Init configures the hook with the auth ledger to be used for checking.
+func (h *Hook) Init(config any) error {
+	if _, ok := config.(*Options); !ok && config != nil {
+		return mqtt.ErrInvalidConfigType
+	}
+
+	if config == nil {
+		config = new(Options)
+	}
+
+	h.config = config.(*Options)
+
+	var err error
+	if h.config.Ledger != nil {
+		h.ledger = h.config.Ledger
+	} else if len(h.config.Data) > 0 {
+		h.ledger = new(Ledger)
+		err = h.ledger.Unmarshal(h.config.Data)
+	}
+	if err != nil {
+		return err
+	}
+
+	if h.ledger == nil {
+		h.ledger = &Ledger{
+			Auth: AuthRules{},
+			ACL:  ACLRules{},
+		}
+	}
+
+	h.Log.Info("loaded auth rules",
+		"authentication", len(h.ledger.Auth),
+		"acl", len(h.ledger.ACL))
+
+	return nil
+}
+
+// OnConnectAuthenticate returns true if the connecting client has rules which provide access
+// in the auth ledger.
+func (h *Hook) OnConnectAuthenticate(cl *mqtt.Client, pk packets.Packet) bool {
+	if _, ok := h.ledger.AuthOk(cl, pk); ok {
+		return true
+	}
+
+	h.Log.Info("client failed authentication check",
+		"username", string(pk.Connect.Username),
+		"remote", cl.Net.Remote)
+	return false
+}
+
+// OnACLCheck returns true if the connecting client has matching read or write access to subscribe
+// or publish to a given topic.
+func (h *Hook) OnACLCheck(cl *mqtt.Client, topic string, write bool) bool {
+	if _, ok := h.ledger.ACLOk(cl, topic, write); ok {
+		return true
+	}
+
+	h.Log.Debug("client failed allowed ACL check",
+		"client", cl.ID,
+		"username", string(cl.Properties.Username),
+		"topic", topic)
+
+	return false
+}

hooks/auth/auth_test.go

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package auth
+
+import (
+	"log/slog"
+	"os"
+	"testing"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/stretchr/testify/require"
+)
+
+var logger = slog.New(slog.NewTextHandler(os.Stdout, nil))
+
+// func teardown(t *testing.T, path string, h *Hook) {
+// 	h.Stop()
+// }
+
+func TestBasicID(t *testing.T) {
+	h := new(Hook)
+	require.Equal(t, "auth-ledger", h.ID())
+}
+
+func TestBasicProvides(t *testing.T) {
+	h := new(Hook)
+	require.True(t, h.Provides(mqtt.OnACLCheck))
+	require.True(t, h.Provides(mqtt.OnConnectAuthenticate))
+	require.False(t, h.Provides(mqtt.OnPublish))
+}
+
+func TestBasicInitBadConfig(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	err := h.Init(map[string]any{})
+	require.Error(t, err)
+}
+
+func TestBasicInitDefaultConfig(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	err := h.Init(nil)
+	require.NoError(t, err)
+}
+
+func TestBasicInitWithLedgerPointer(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	ln := &Ledger{
+		Auth: []AuthRule{
+			{
+				Remote: "127.0.0.1",
+				Allow:  true,
+			},
+		},
+		ACL: []ACLRule{
+			{
+				Remote: "127.0.0.1",
+				Filters: Filters{
+					"#": ReadWrite,
+				},
+			},
+		},
+	}
+
+	err := h.Init(&Options{
+		Ledger: ln,
+	})
+
+	require.NoError(t, err)
+	require.Same(t, ln, h.ledger)
+}
+
+func TestBasicInitWithLedgerJSON(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	require.Nil(t, h.ledger)
+	err := h.Init(&Options{
+		Data: ledgerJSON,
+	})
+
+	require.NoError(t, err)
+	require.Equal(t, ledgerStruct.Auth[0].Username, h.ledger.Auth[0].Username)
+	require.Equal(t, ledgerStruct.ACL[0].Client, h.ledger.ACL[0].Client)
+}
+
+func TestBasicInitWithLedgerYAML(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	require.Nil(t, h.ledger)
+	err := h.Init(&Options{
+		Data: ledgerYAML,
+	})
+
+	require.NoError(t, err)
+	require.Equal(t, ledgerStruct.Auth[0].Username, h.ledger.Auth[0].Username)
+	require.Equal(t, ledgerStruct.ACL[0].Client, h.ledger.ACL[0].Client)
+}
+
+func TestBasicInitWithLedgerBadDAta(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	require.Nil(t, h.ledger)
+	err := h.Init(&Options{
+		Data: []byte("fdsfdsafasd"),
+	})
+
+	require.Error(t, err)
+}
+
+func TestOnConnectAuthenticate(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	ln := new(Ledger)
+	ln.Auth = checkLedger.Auth
+	ln.ACL = checkLedger.ACL
+	err := h.Init(
+		&Options{
+			Ledger: ln,
+		},
+	)
+
+	require.NoError(t, err)
+
+	require.True(t, h.OnConnectAuthenticate(
+		&mqtt.Client{
+			Properties: mqtt.ClientProperties{
+				Username: []byte("mochi"),
+			},
+		},
+		packets.Packet{Connect: packets.ConnectParams{Password: []byte("melon")}},
+	))
+
+	require.False(t, h.OnConnectAuthenticate(
+		&mqtt.Client{
+			Properties: mqtt.ClientProperties{
+				Username: []byte("mochi"),
+			},
+		},
+		packets.Packet{Connect: packets.ConnectParams{Password: []byte("bad-pass")}},
+	))
+
+	require.False(t, h.OnConnectAuthenticate(
+		&mqtt.Client{},
+		packets.Packet{},
+	))
+}
+
+func TestOnACL(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	ln := new(Ledger)
+	ln.Auth = checkLedger.Auth
+	ln.ACL = checkLedger.ACL
+	err := h.Init(
+		&Options{
+			Ledger: ln,
+		},
+	)
+
+	require.NoError(t, err)
+
+	require.True(t, h.OnACLCheck(
+		&mqtt.Client{
+			Properties: mqtt.ClientProperties{
+				Username: []byte("mochi"),
+			},
+		},
+		"mochi/info",
+		true,
+	))
+
+	require.False(t, h.OnACLCheck(
+		&mqtt.Client{
+			Properties: mqtt.ClientProperties{
+				Username: []byte("mochi"),
+			},
+		},
+		"d/j/f",
+		true,
+	))
+
+	require.True(t, h.OnACLCheck(
+		&mqtt.Client{
+			Properties: mqtt.ClientProperties{
+				Username: []byte("mochi"),
+			},
+		},
+		"readonly",
+		false,
+	))
+
+	require.False(t, h.OnACLCheck(
+		&mqtt.Client{
+			Properties: mqtt.ClientProperties{
+				Username: []byte("mochi"),
+			},
+		},
+		"readonly",
+		true,
+	))
+}

hooks/auth/ledger.go

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package auth
+
+import (
+	"encoding/json"
+	"strings"
+	"sync"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/packets"
+)
+
+const (
+	Deny      Access = iota // user cannot access the topic
+	ReadOnly                // user can only subscribe to the topic
+	WriteOnly               // user can only publish to the topic
+	ReadWrite               // user can both publish and subscribe to the topic
+)
+
+// Access determines the read/write privileges for an ACL rule.
+type Access byte
+
+// Users contains a map of access rules for specific users, keyed on username.
+type Users map[string]UserRule
+
+// UserRule defines a set of access rules for a specific user.
+type UserRule struct {
+	Username RString `json:"username,omitempty" yaml:"username,omitempty"` // the username of a user
+	Password RString `json:"password,omitempty" yaml:"password,omitempty"` // the password of a user
+	ACL      Filters `json:"acl,omitempty" yaml:"acl,omitempty"`           // filters to match, if desired
+	Disallow bool    `json:"disallow,omitempty" yaml:"disallow,omitempty"` // allow or disallow the user
+}
+
+// AuthRules defines generic access rules applicable to all users.
+type AuthRules []AuthRule
+
+type AuthRule struct {
+	Client   RString `json:"client,omitempty" yaml:"client,omitempty"`     // the id of a connecting client
+	Username RString `json:"username,omitempty" yaml:"username,omitempty"` // the username of a user
+	Remote   RString `json:"remote,omitempty" yaml:"remote,omitempty"`     // remote address or
+	Password RString `json:"password,omitempty" yaml:"password,omitempty"` // the password of a user
+	Allow    bool    `json:"allow,omitempty" yaml:"allow,omitempty"`       // allow or disallow the users
+}
+
+// ACLRules defines generic topic or filter access rules applicable to all users.
+type ACLRules []ACLRule
+
+// ACLRule defines access rules for a specific topic or filter.
+type ACLRule struct {
+	Client   RString `json:"client,omitempty" yaml:"client,omitempty"`     // the id of a connecting client
+	Username RString `json:"username,omitempty" yaml:"username,omitempty"` // the username of a user
+	Remote   RString `json:"remote,omitempty" yaml:"remote,omitempty"`     // remote address or
+	Filters  Filters `json:"filters,omitempty" yaml:"filters,omitempty"`   // filters to match
+}
+
+// Filters is a map of Access rules keyed on filter.
+type Filters map[RString]Access
+
+// RString is a rule value string.
+type RString string
+
+// Matches returns true if the rule matches a given string.
+func (r RString) Matches(a string) bool {
+	rr := string(r)
+	if r == "" || r == "*" || a == rr {
+		return true
+	}
+
+	i := strings.Index(rr, "*")
+	if i > 0 && len(a) > i && strings.Compare(rr[:i], a[:i]) == 0 {
+		return true
+	}
+
+	return false
+}
+
+// FilterMatches returns true if a filter matches a topic rule.
+func (r RString) FilterMatches(a string) bool {
+	_, ok := MatchTopic(string(r), a)
+	return ok
+}
+
+// MatchTopic checks if a given topic matches a filter, accounting for filter
+// wildcards. Eg. filter /a/b/+/c == topic a/b/d/c.
+func MatchTopic(filter string, topic string) (elements []string, matched bool) {
+	filterParts := strings.Split(filter, "/")
+	topicParts := strings.Split(topic, "/")
+
+	elements = make([]string, 0)
+	for i := 0; i < len(filterParts); i++ {
+		if i >= len(topicParts) {
+			matched = false
+			return
+		}
+
+		if filterParts[i] == "+" {
+			elements = append(elements, topicParts[i])
+			continue
+		}
+
+		if filterParts[i] == "#" {
+			matched = true
+			elements = append(elements, strings.Join(topicParts[i:], "/"))
+			return
+		}
+
+		if filterParts[i] != topicParts[i] {
+			matched = false
+			return
+		}
+	}
+
+	return elements, true
+}
+
+// Ledger is an auth ledger containing access rules for users and topics.
+type Ledger struct {
+	sync.Mutex `json:"-" yaml:"-"`
+	Users      Users     `json:"users" yaml:"users"`
+	Auth       AuthRules `json:"auth" yaml:"auth"`
+	ACL        ACLRules  `json:"acl" yaml:"acl"`
+}
+
+// Update updates the internal values of the ledger.
+func (l *Ledger) Update(ln *Ledger) {
+	l.Lock()
+	defer l.Unlock()
+	l.Auth = ln.Auth
+	l.ACL = ln.ACL
+}
+
+// AuthOk returns true if the rules indicate the user is allowed to authenticate.
+func (l *Ledger) AuthOk(cl *mqtt.Client, pk packets.Packet) (n int, ok bool) {
+	// If the users map is set, always check for a predefined user first instead
+	// of iterating through global rules.
+	if l.Users != nil {
+		if u, ok := l.Users[string(cl.Properties.Username)]; ok &&
+			u.Password != "" &&
+			u.Password == RString(pk.Connect.Password) {
+			return 0, !u.Disallow
+		}
+	}
+
+	// If there's no users map, or no user was found, attempt to find a matching
+	// rule (which may also contain a user).
+	for n, rule := range l.Auth {
+		if rule.Client.Matches(cl.ID) &&
+			rule.Username.Matches(string(cl.Properties.Username)) &&
+			rule.Password.Matches(string(pk.Connect.Password)) &&
+			rule.Remote.Matches(cl.Net.Remote) {
+			return n, rule.Allow
+		}
+	}
+
+	return 0, false
+}
+
+// ACLOk returns true if the rules indicate the user is allowed to read or write to
+// a specific filter or topic respectively, based on the `write` bool.
+func (l *Ledger) ACLOk(cl *mqtt.Client, topic string, write bool) (n int, ok bool) {
+	// If the users map is set, always check for a predefined user first instead
+	// of iterating through global rules.
+	if l.Users != nil {
+		if u, ok := l.Users[string(cl.Properties.Username)]; ok && len(u.ACL) > 0 {
+			for filter, access := range u.ACL {
+				if filter.FilterMatches(topic) {
+					if !write && (access == ReadOnly || access == ReadWrite) {
+						return n, true
+					} else if write && (access == WriteOnly || access == ReadWrite) {
+						return n, true
+					} else {
+						return n, false
+					}
+				}
+			}
+		}
+	}
+
+	for n, rule := range l.ACL {
+		if rule.Client.Matches(cl.ID) &&
+			rule.Username.Matches(string(cl.Properties.Username)) &&
+			rule.Remote.Matches(cl.Net.Remote) {
+			if len(rule.Filters) == 0 {
+				return n, true
+			}
+
+			if write {
+				for filter, access := range rule.Filters {
+					if access == WriteOnly || access == ReadWrite {
+						if filter.FilterMatches(topic) {
+							return n, true
+						}
+					}
+				}
+			}
+
+			if !write {
+				for filter, access := range rule.Filters {
+					if access == ReadOnly || access == ReadWrite {
+						if filter.FilterMatches(topic) {
+							return n, true
+						}
+					}
+				}
+			}
+
+			for filter := range rule.Filters {
+				if filter.FilterMatches(topic) {
+					return n, false
+				}
+			}
+		}
+	}
+
+	return 0, true
+}
+
+// ToJSON encodes the values into a JSON string.
+func (l *Ledger) ToJSON() (data []byte, err error) {
+	return json.Marshal(l)
+}
+
+// ToYAML encodes the values into a YAML string.
+func (l *Ledger) ToYAML() (data []byte, err error) {
+	return yaml.Marshal(l)
+}
+
+// Unmarshal decodes a JSON or YAML string (such as a rule config from a file) into a struct.
+func (l *Ledger) Unmarshal(data []byte) error {
+	l.Lock()
+	defer l.Unlock()
+	if len(data) == 0 {
+		return nil
+	}
+
+	if data[0] == '{' {
+		return json.Unmarshal(data, l)
+	}
+
+	return yaml.Unmarshal(data, &l)
+}

hooks/auth/ledger_test.go

@@ -0,0 +1,610 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package auth
+
+import (
+	"testing"
+
+	"github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/stretchr/testify/require"
+)
+
+var (
+	checkLedger = Ledger{
+		Users: Users{ // users are allowed by default
+			"mochi-co": {
+				Password: "melon",
+				ACL: Filters{
+					"d/+/f":      Deny,
+					"mochi-co/#": ReadWrite,
+					"readonly":   ReadOnly,
+				},
+			},
+			"suspended-username": {
+				Password: "any",
+				Disallow: true,
+			},
+			"mochi": { // ACL only, will defer to AuthRules for authentication
+				ACL: Filters{
+					"special/mochi": ReadOnly,
+					"secret/mochi":  Deny,
+					"ignored":       ReadWrite,
+				},
+			},
+		},
+		Auth: AuthRules{
+			{Username: "banned-user"},                               // never allow specific username
+			{Remote: "127.0.0.1", Allow: true},                      // always allow localhost
+			{Remote: "123.123.123.123"},                             // disallow any from specific address
+			{Username: "not-mochi", Remote: "111.144.155.166"},      // disallow specific username and address
+			{Remote: "111.*", Allow: true},                          // allow any in wildcard (that isn't the above username)
+			{Username: "mochi", Password: "melon", Allow: true},     // allow matching user/pass
+			{Username: "mochi-co", Password: "melon", Allow: false}, // allow matching user/pass (should never trigger due to Users map)
+		},
+		ACL: ACLRules{
+			{
+				Username: "mochi", // allow matching user/pass
+				Filters: Filters{
+					"a/b/c":     Deny,
+					"d/+/f":     Deny,
+					"mochi/#":   ReadWrite,
+					"updates/#": WriteOnly,
+					"readonly":  ReadOnly,
+					"ignored":   Deny,
+				},
+			},
+			{Remote: "localhost", Filters: Filters{"$SYS/#": ReadOnly}}, // allow $SYS access to localhost
+			{Username: "admin", Filters: Filters{"$SYS/#": ReadOnly}},   // allow $SYS access to admin
+			{Remote: "001.002.003.004"},                                 // Allow all with no filter
+			{Filters: Filters{"$SYS/#": Deny}},                          // Deny $SYS access to all others
+		},
+	}
+)
+
+func TestRStringMatches(t *testing.T) {
+	require.True(t, RString("*").Matches("any"))
+	require.True(t, RString("*").Matches(""))
+	require.True(t, RString("").Matches("any"))
+	require.True(t, RString("").Matches(""))
+	require.False(t, RString("no").Matches("any"))
+	require.False(t, RString("no").Matches(""))
+}
+
+func TestCanAuthenticate(t *testing.T) {
+	tt := []struct {
+		desc   string
+		client *mqtt.Client
+		pk     packets.Packet
+		n      int
+		ok     bool
+	}{
+		{
+			desc: "allow all local 127.0.0.1",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+				Net: mqtt.ClientConnection{
+					Remote: "127.0.0.1",
+				},
+			},
+			pk: packets.Packet{Connect: packets.ConnectParams{}},
+			ok: true,
+			n:  1,
+		},
+		{
+			desc: "allow username/password",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			pk: packets.Packet{Connect: packets.ConnectParams{Password: []byte("melon")}},
+			ok: true,
+			n:  5,
+		},
+		{
+			desc: "deny username/password",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			pk: packets.Packet{Connect: packets.ConnectParams{Password: []byte("bad-pass")}},
+			ok: false,
+			n:  0,
+		},
+		{
+			desc: "allow all local 127.0.0.1",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+				Net: mqtt.ClientConnection{
+					Remote: "127.0.0.1",
+				},
+			},
+			pk: packets.Packet{Connect: packets.ConnectParams{Password: []byte("bad-pass")}},
+			ok: true,
+			n:  1,
+		},
+		{
+			desc: "allow username/password",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			pk: packets.Packet{Connect: packets.ConnectParams{Password: []byte("melon")}},
+			ok: true,
+			n:  5,
+		},
+		{
+			desc: "deny username/password",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			pk: packets.Packet{Connect: packets.ConnectParams{Password: []byte("bad-pass")}},
+			ok: false,
+			n:  0,
+		},
+		{
+			desc: "deny client from address",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("not-mochi"),
+				},
+				Net: mqtt.ClientConnection{
+					Remote: "111.144.155.166",
+				},
+			},
+			pk: packets.Packet{},
+			ok: false,
+			n:  3,
+		},
+		{
+			desc: "allow remote wildcard",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+				Net: mqtt.ClientConnection{
+					Remote: "111.0.0.1",
+				},
+			},
+			pk: packets.Packet{},
+			ok: true,
+			n:  4,
+		},
+		{
+			desc: "never allow username",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("banned-user"),
+				},
+				Net: mqtt.ClientConnection{
+					Remote: "127.0.0.1",
+				},
+			},
+			pk: packets.Packet{},
+			ok: false,
+			n:  0,
+		},
+		{
+			desc: "matching user in users",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi-co"),
+				},
+			},
+			pk: packets.Packet{Connect: packets.ConnectParams{Password: []byte("melon")}},
+			ok: true,
+			n:  0,
+		},
+		{
+			desc: "never user in users",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("suspended-user"),
+				},
+			},
+			pk: packets.Packet{Connect: packets.ConnectParams{Password: []byte("any")}},
+			ok: false,
+			n:  0,
+		},
+	}
+
+	for _, d := range tt {
+		t.Run(d.desc, func(t *testing.T) {
+			n, ok := checkLedger.AuthOk(d.client, d.pk)
+			require.Equal(t, d.n, n)
+			require.Equal(t, d.ok, ok)
+		})
+	}
+}
+
+func TestCanACL(t *testing.T) {
+	tt := []struct {
+		client *mqtt.Client
+		desc   string
+		topic  string
+		n      int
+		write  bool
+		ok     bool
+	}{
+		{
+			desc:   "allow normal write on any other filter",
+			client: &mqtt.Client{},
+			topic:  "default/acl/write/access",
+			write:  true,
+			ok:     true,
+		},
+		{
+			desc:   "allow normal read on any other filter",
+			client: &mqtt.Client{},
+			topic:  "default/acl/read/access",
+			write:  false,
+			ok:     true,
+		},
+		{
+			desc: "deny user on literal filter",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "a/b/c",
+		},
+		{
+			desc: "deny user on partial filter",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "d/j/f",
+		},
+		{
+			desc: "allow read/write to user path",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "mochi/read/write",
+			write: true,
+			ok:    true,
+		},
+		{
+			desc: "deny read on write-only path",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "updates/no/reading",
+			write: false,
+			ok:    false,
+		},
+		{
+			desc: "deny read on write-only path ext",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "updates/mochi",
+			write: false,
+			ok:    false,
+		},
+		{
+			desc: "allow read on not-acl path (no #)",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "updates",
+			write: false,
+			ok:    true,
+		},
+		{
+			desc: "allow write on write-only path",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "updates/mochi",
+			write: true,
+			ok:    true,
+		},
+		{
+			desc: "deny write on read-only path",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "readonly",
+			write: true,
+			ok:    false,
+		},
+		{
+			desc: "allow read on read-only path",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "readonly",
+			write: false,
+			ok:    true,
+		},
+		{
+			desc: "allow $sys access to localhost",
+			client: &mqtt.Client{
+				Net: mqtt.ClientConnection{
+					Remote: "localhost",
+				},
+			},
+			topic: "$SYS/test",
+			write: false,
+			ok:    true,
+			n:     1,
+		},
+		{
+			desc: "allow $sys access to admin",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("admin"),
+				},
+			},
+			topic: "$SYS/test",
+			write: false,
+			ok:    true,
+			n:     2,
+		},
+		{
+			desc: "deny $sys access to all others",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "$SYS/test",
+			write: false,
+			ok:    false,
+			n:     4,
+		},
+		{
+			desc: "allow all with no filter",
+			client: &mqtt.Client{
+				Net: mqtt.ClientConnection{
+					Remote: "001.002.003.004",
+				},
+			},
+			topic: "any/path",
+			write: true,
+			ok:    true,
+			n:     3,
+		},
+		{
+			desc: "use users embedded acl deny",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "secret/mochi",
+			write: true,
+			ok:    false,
+		},
+		{
+			desc: "use users embedded acl any",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "any/mochi",
+			write: true,
+			ok:    true,
+		},
+		{
+			desc: "use users embedded acl write on read-only",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "special/mochi",
+			write: true,
+			ok:    false,
+		},
+		{
+			desc: "use users embedded acl read on read-only",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "special/mochi",
+			write: false,
+			ok:    true,
+		},
+		{
+			desc: "preference users embedded acl",
+			client: &mqtt.Client{
+				Properties: mqtt.ClientProperties{
+					Username: []byte("mochi"),
+				},
+			},
+			topic: "ignored",
+			write: true,
+			ok:    true,
+		},
+	}
+
+	for _, d := range tt {
+		t.Run(d.desc, func(t *testing.T) {
+			n, ok := checkLedger.ACLOk(d.client, d.topic, d.write)
+			require.Equal(t, d.n, n)
+			require.Equal(t, d.ok, ok)
+		})
+	}
+}
+
+func TestMatchTopic(t *testing.T) {
+	el, matched := MatchTopic("a/+/c/+", "a/b/c/d")
+	require.True(t, matched)
+	require.Equal(t, []string{"b", "d"}, el)
+
+	el, matched = MatchTopic("a/+/+/+", "a/b/c/d")
+	require.True(t, matched)
+	require.Equal(t, []string{"b", "c", "d"}, el)
+
+	el, matched = MatchTopic("stuff/#", "stuff/things/yeah")
+	require.True(t, matched)
+	require.Equal(t, []string{"things/yeah"}, el)
+
+	el, matched = MatchTopic("a/+/#/+", "a/b/c/d/as/dds")
+	require.True(t, matched)
+	require.Equal(t, []string{"b", "c/d/as/dds"}, el)
+
+	el, matched = MatchTopic("test", "test")
+	require.True(t, matched)
+	require.Equal(t, make([]string, 0), el)
+
+	el, matched = MatchTopic("things/stuff//", "things/stuff/")
+	require.False(t, matched)
+	require.Equal(t, make([]string, 0), el)
+
+	el, matched = MatchTopic("t", "t2")
+	require.False(t, matched)
+	require.Equal(t, make([]string, 0), el)
+
+	el, matched = MatchTopic(" ", "  ")
+	require.False(t, matched)
+	require.Equal(t, make([]string, 0), el)
+}
+
+var (
+	ledgerStruct = Ledger{
+		Users: Users{
+			"mochi": {
+				Password: "peach",
+				ACL: Filters{
+					"readonly": ReadOnly,
+					"deny":     Deny,
+				},
+			},
+		},
+		Auth: AuthRules{
+			{
+				Client:   "*",
+				Username: "mochi-co",
+				Password: "melon",
+				Remote:   "192.168.1.*",
+				Allow:    true,
+			},
+		},
+		ACL: ACLRules{
+			{
+				Client:   "*",
+				Username: "mochi-co",
+				Remote:   "127.*",
+				Filters: Filters{
+					"readonly":  ReadOnly,
+					"writeonly": WriteOnly,
+					"readwrite": ReadWrite,
+					"deny":      Deny,
+				},
+			},
+		},
+	}
+
+	ledgerJSON = []byte(`{"users":{"mochi":{"password":"peach","acl":{"deny":0,"readonly":1}}},"auth":[{"client":"*","username":"mochi-co","remote":"192.168.1.*","password":"melon","allow":true}],"acl":[{"client":"*","username":"mochi-co","remote":"127.*","filters":{"deny":0,"readonly":1,"readwrite":3,"writeonly":2}}]}`)
+	ledgerYAML = []byte(`users:
+    mochi:
+        password: peach
+        acl:
+            deny: 0
+            readonly: 1
+auth:
+    - client: '*'
+      username: mochi-co
+      remote: 192.168.1.*
+      password: melon
+      allow: true
+acl:
+    - client: '*'
+      username: mochi-co
+      remote: 127.*
+      filters:
+        deny: 0
+        readonly: 1
+        readwrite: 3
+        writeonly: 2
+`)
+)
+
+func TestLedgerUpdate(t *testing.T) {
+	old := &Ledger{
+		Auth: AuthRules{
+			{Remote: "127.0.0.1", Allow: true},
+		},
+	}
+
+	n := &Ledger{
+		Auth: AuthRules{
+			{Remote: "127.0.0.1", Allow: true},
+			{Remote: "192.168.*", Allow: true},
+		},
+	}
+
+	old.Update(n)
+	require.Len(t, old.Auth, 2)
+	require.Equal(t, RString("192.168.*"), old.Auth[1].Remote)
+	require.NotSame(t, n, old)
+}
+
+func TestLedgerToJSON(t *testing.T) {
+	data, err := ledgerStruct.ToJSON()
+	require.NoError(t, err)
+	require.Equal(t, ledgerJSON, data)
+}
+
+func TestLedgerToYAML(t *testing.T) {
+	data, err := ledgerStruct.ToYAML()
+	require.NoError(t, err)
+	require.Equal(t, ledgerYAML, data)
+}
+
+func TestLedgerUnmarshalFromYAML(t *testing.T) {
+	l := new(Ledger)
+	err := l.Unmarshal(ledgerYAML)
+	require.NoError(t, err)
+	require.Equal(t, &ledgerStruct, l)
+	require.NotSame(t, l, &ledgerStruct)
+}
+
+func TestLedgerUnmarshalFromJSON(t *testing.T) {
+	l := new(Ledger)
+	err := l.Unmarshal(ledgerJSON)
+	require.NoError(t, err)
+	require.Equal(t, &ledgerStruct, l)
+	require.NotSame(t, l, &ledgerStruct)
+}
+
+func TestLedgerUnmarshalNil(t *testing.T) {
+	l := new(Ledger)
+	err := l.Unmarshal([]byte{})
+	require.NoError(t, err)
+	require.Equal(t, new(Ledger), l)
+}

hooks/debug/debug.go

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package debug
+
+import (
+	"fmt"
+	"log/slog"
+	"strings"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+)
+
+// Options contains configuration settings for the debug output.
+type Options struct {
+	Enable         bool `yaml:"enable" json:"enable"`                     // non-zero field for enabling hook using file-based config
+	ShowPacketData bool `yaml:"show_packet_data" json:"show_packet_data"` // include decoded packet data (default false)
+	ShowPings      bool `yaml:"show_pings" json:"show_pings"`             // show ping requests and responses (default false)
+	ShowPasswords  bool `yaml:"show_passwords" json:"show_passwords"`     // show connecting user passwords (default false)
+}
+
+// Hook is a debugging hook which logs additional low-level information from the server.
+type Hook struct {
+	mqtt.HookBase
+	config *Options
+	Log    *slog.Logger
+}
+
+// ID returns the ID of the hook.
+func (h *Hook) ID() string {
+	return "debug"
+}
+
+// Provides indicates that this hook provides all methods.
+func (h *Hook) Provides(b byte) bool {
+	return true
+}
+
+// Init is called when the hook is initialized.
+func (h *Hook) Init(config any) error {
+	if _, ok := config.(*Options); !ok && config != nil {
+		return mqtt.ErrInvalidConfigType
+	}
+
+	if config == nil {
+		config = new(Options)
+	}
+
+	h.config = config.(*Options)
+
+	return nil
+}
+
+// SetOpts is called when the hook receives inheritable server parameters.
+func (h *Hook) SetOpts(l *slog.Logger, opts *mqtt.HookOptions) {
+	h.Log = l
+	h.Log.Debug("", "method", "SetOpts")
+}
+
+// Stop is called when the hook is stopped.
+func (h *Hook) Stop() error {
+	h.Log.Debug("", "method", "Stop")
+	return nil
+}
+
+// OnStarted is called when the server starts.
+func (h *Hook) OnStarted() {
+	h.Log.Debug("", "method", "OnStarted")
+}
+
+// OnStopped is called when the server stops.
+func (h *Hook) OnStopped() {
+	h.Log.Debug("", "method", "OnStopped")
+}
+
+// OnPacketRead is called when a new packet is received from a client.
+func (h *Hook) OnPacketRead(cl *mqtt.Client, pk packets.Packet) (packets.Packet, error) {
+	if (pk.FixedHeader.Type == packets.Pingresp || pk.FixedHeader.Type == packets.Pingreq) && !h.config.ShowPings {
+		return pk, nil
+	}
+
+	h.Log.Debug(fmt.Sprintf("%s << %s", strings.ToUpper(packets.PacketNames[pk.FixedHeader.Type]), cl.ID), "m", h.packetMeta(pk))
+	return pk, nil
+}
+
+// OnPacketSent is called when a packet is sent to a client.
+func (h *Hook) OnPacketSent(cl *mqtt.Client, pk packets.Packet, b []byte) {
+	if (pk.FixedHeader.Type == packets.Pingresp || pk.FixedHeader.Type == packets.Pingreq) && !h.config.ShowPings {
+		return
+	}
+
+	h.Log.Debug(fmt.Sprintf("%s >> %s", strings.ToUpper(packets.PacketNames[pk.FixedHeader.Type]), cl.ID), "m", h.packetMeta(pk))
+}
+
+// OnRetainMessage is called when a published message is retained (or retain deleted/modified).
+func (h *Hook) OnRetainMessage(cl *mqtt.Client, pk packets.Packet, r int64) {
+	h.Log.Debug("retained message on topic", "m", h.packetMeta(pk))
+}
+
+// OnQosPublish is called when a publish packet with Qos is issued to a subscriber.
+func (h *Hook) OnQosPublish(cl *mqtt.Client, pk packets.Packet, sent int64, resends int) {
+	h.Log.Debug("inflight out", "m", h.packetMeta(pk))
+}
+
+// OnQosComplete is called when the Qos flow for a message has been completed.
+func (h *Hook) OnQosComplete(cl *mqtt.Client, pk packets.Packet) {
+	h.Log.Debug("inflight complete", "m", h.packetMeta(pk))
+}
+
+// OnQosDropped is called the Qos flow for a message expires.
+func (h *Hook) OnQosDropped(cl *mqtt.Client, pk packets.Packet) {
+	h.Log.Debug("inflight dropped", "m", h.packetMeta(pk))
+}
+
+// OnLWTSent is called when a Will Message has been issued from a disconnecting client.
+func (h *Hook) OnLWTSent(cl *mqtt.Client, pk packets.Packet) {
+	h.Log.Debug("sent lwt for client", "method", "OnLWTSent", "client", cl.ID)
+}
+
+// OnRetainedExpired is called when the server clears expired retained messages.
+func (h *Hook) OnRetainedExpired(filter string) {
+	h.Log.Debug("retained message expired", "method", "OnRetainedExpired", "topic", filter)
+}
+
+// OnClientExpired is called when the server clears an expired client.
+func (h *Hook) OnClientExpired(cl *mqtt.Client) {
+	h.Log.Debug("client session expired", "method", "OnClientExpired", "client", cl.ID)
+}
+
+// StoredClients is called when the server restores clients from a store.
+func (h *Hook) StoredClients() (v []storage.Client, err error) {
+	h.Log.Debug("", "method", "StoredClients")
+
+	return v, nil
+}
+
+// StoredSubscriptions is called when the server restores subscriptions from a store.
+func (h *Hook) StoredSubscriptions() (v []storage.Subscription, err error) {
+	h.Log.Debug("", "method", "StoredSubscriptions")
+	return v, nil
+}
+
+// StoredRetainedMessages is called when the server restores retained messages from a store.
+func (h *Hook) StoredRetainedMessages() (v []storage.Message, err error) {
+	h.Log.Debug("", "method", "StoredRetainedMessages")
+	return v, nil
+}
+
+// StoredInflightMessages is called when the server restores inflight messages from a store.
+func (h *Hook) StoredInflightMessages() (v []storage.Message, err error) {
+	h.Log.Debug("", "method", "StoredInflightMessages")
+	return v, nil
+}
+
+// StoredSysInfo is called when the server restores system info from a store.
+func (h *Hook) StoredSysInfo() (v storage.SystemInfo, err error) {
+	h.Log.Debug("", "method", "StoredSysInfo")
+
+	return v, nil
+}
+
+// packetMeta adds additional type-specific metadata to the debug logs.
+func (h *Hook) packetMeta(pk packets.Packet) map[string]any {
+	m := map[string]any{}
+	switch pk.FixedHeader.Type {
+	case packets.Connect:
+		m["id"] = pk.Connect.ClientIdentifier
+		m["clean"] = pk.Connect.Clean
+		m["keepalive"] = pk.Connect.Keepalive
+		m["version"] = pk.ProtocolVersion
+		m["username"] = string(pk.Connect.Username)
+		if h.config.ShowPasswords {
+			m["password"] = string(pk.Connect.Password)
+		}
+		if pk.Connect.WillFlag {
+			m["will_topic"] = pk.Connect.WillTopic
+			m["will_payload"] = string(pk.Connect.WillPayload)
+		}
+	case packets.Publish:
+		m["topic"] = pk.TopicName
+		m["payload"] = string(pk.Payload)
+		m["raw"] = pk.Payload
+		m["qos"] = pk.FixedHeader.Qos
+		m["id"] = pk.PacketID
+	case packets.Connack:
+		fallthrough
+	case packets.Disconnect:
+		fallthrough
+	case packets.Puback:
+		fallthrough
+	case packets.Pubrec:
+		fallthrough
+	case packets.Pubrel:
+		fallthrough
+	case packets.Pubcomp:
+		m["id"] = pk.PacketID
+		m["reason"] = int(pk.ReasonCode)
+		if pk.ReasonCode > packets.CodeSuccess.Code && pk.ProtocolVersion == 5 {
+			m["reason_string"] = pk.Properties.ReasonString
+		}
+	case packets.Subscribe:
+		f := map[string]int{}
+		ids := map[string]int{}
+		for _, v := range pk.Filters {
+			f[v.Filter] = int(v.Qos)
+			ids[v.Filter] = v.Identifier
+		}
+		m["filters"] = f
+		m["subids"] = f
+
+	case packets.Unsubscribe:
+		f := []string{}
+		for _, v := range pk.Filters {
+			f = append(f, v.Filter)
+		}
+		m["filters"] = f
+	case packets.Suback:
+		fallthrough
+	case packets.Unsuback:
+		r := []int{}
+		for _, v := range pk.ReasonCodes {
+			r = append(r, int(v))
+		}
+		m["reasons"] = r
+	case packets.Auth:
+		// tbd
+	}
+
+	if h.config.ShowPacketData {
+		m["packet"] = pk
+	}
+
+	return m
+}

hooks/storage/badger/badger.go

@@ -0,0 +1,517 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co, gsagula
+
+package badger
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+
+	"github.com/timshannon/badgerhold"
+)
+
+const (
+	// defaultDbFile is the default file path for the badger db file.
+	defaultDbFile         = ".badger"
+	defaultGcInterval     = 5 * 60 // gc interval in seconds
+	defaultGcDiscardRatio = 0.5
+)
+
+// clientKey returns a primary key for a client.
+func clientKey(cl *mqtt.Client) string {
+	return cl.ID
+}
+
+// subscriptionKey returns a primary key for a subscription.
+func subscriptionKey(cl *mqtt.Client, filter string) string {
+	return storage.SubscriptionKey + "_" + cl.ID + ":" + filter
+}
+
+// retainedKey returns a primary key for a retained message.
+func retainedKey(topic string) string {
+	return storage.RetainedKey + "_" + topic
+}
+
+// inflightKey returns a primary key for an inflight message.
+func inflightKey(cl *mqtt.Client, pk packets.Packet) string {
+	return storage.InflightKey + "_" + cl.ID + ":" + pk.FormatID()
+}
+
+// sysInfoKey returns a primary key for system info.
+func sysInfoKey() string {
+	return storage.SysInfoKey
+}
+
+// Options contains configuration settings for the BadgerDB instance.
+type Options struct {
+	Options *badgerhold.Options
+	Path    string `yaml:"path" json:"path"`
+	// GcDiscardRatio specifies the ratio of log discard compared to the maximum possible log discard.
+	// Setting it to a higher value would result in fewer space reclaims, while setting it to a lower value
+	// would result in more space reclaims at the cost of increased activity on the LSM tree.
+	// discardRatio must be in the range (0.0, 1.0), both endpoints excluded, otherwise, it will be set to the default value of 0.5.
+	GcDiscardRatio float64 `yaml:"gc_discard_ratio" json:"gc_discard_ratio"`
+	GcInterval     int64   `yaml:"gc_interval" json:"gc_interval"`
+}
+
+// Hook is a persistent storage hook based using BadgerDB file store as a backend.
+type Hook struct {
+	mqtt.HookBase
+	config   *Options          // options for configuring the BadgerDB instance.
+	gcTicker *time.Ticker      // Ticker for BadgerDB garbage collection.
+	db       *badgerhold.Store // the BadgerDB instance.
+}
+
+// ID returns the id of the hook.
+func (h *Hook) ID() string {
+	return "badger-db"
+}
+
+// Provides indicates which hook methods this hook provides.
+func (h *Hook) Provides(b byte) bool {
+	return bytes.Contains([]byte{
+		mqtt.OnSessionEstablished,
+		mqtt.OnDisconnect,
+		mqtt.OnSubscribed,
+		mqtt.OnUnsubscribed,
+		mqtt.OnRetainMessage,
+		mqtt.OnWillSent,
+		mqtt.OnQosPublish,
+		mqtt.OnQosComplete,
+		mqtt.OnQosDropped,
+		mqtt.OnSysInfoTick,
+		mqtt.OnClientExpired,
+		mqtt.OnRetainedExpired,
+		mqtt.StoredClients,
+		mqtt.StoredInflightMessages,
+		mqtt.StoredRetainedMessages,
+		mqtt.StoredSubscriptions,
+		mqtt.StoredSysInfo,
+	}, []byte{b})
+}
+
+// GcLoop periodically runs the garbage collection process to reclaim space in the value log files.
+// It uses a ticker to trigger the garbage collection at regular intervals specified by the configuration.
+// Refer to: https://dgraph.io/docs/badger/get-started/#garbage-collection
+func (h *Hook) GcLoop() {
+	for range h.gcTicker.C {
+	again:
+		// Run the garbage collection process with a threshold.
+		// If the process returns nil (success), repeat the process.
+		err := h.db.Badger().RunValueLogGC(h.config.GcDiscardRatio)
+		if err == nil {
+			goto again // Retry garbage collection if successful.
+		}
+	}
+}
+
+// Init initializes and connects to the badger instance.
+func (h *Hook) Init(config any) error {
+	if _, ok := config.(*Options); !ok && config != nil {
+		return mqtt.ErrInvalidConfigType
+	}
+
+	if config == nil {
+		config = new(Options)
+	}
+
+	h.config = config.(*Options)
+	if h.config.Path == "" {
+		h.config.Path = defaultDbFile
+	}
+
+	if h.config.GcInterval == 0 {
+		h.config.GcInterval = defaultGcInterval
+	}
+
+	if h.config.GcDiscardRatio <= 0.0 || h.config.GcDiscardRatio >= 1.0 {
+		h.config.GcDiscardRatio = defaultGcDiscardRatio
+	}
+
+	options := badgerhold.DefaultOptions
+	options.Dir = h.config.Path
+	options.ValueDir = h.config.Path
+	options.Logger = h
+
+	var err error
+	h.db, err = badgerhold.Open(options)
+	if err != nil {
+		return err
+	}
+
+	h.gcTicker = time.NewTicker(time.Duration(h.config.GcInterval) * time.Second)
+	go h.GcLoop()
+
+	return nil
+}
+
+// Stop closes the badger instance.
+func (h *Hook) Stop() error {
+	if h.gcTicker != nil {
+		h.gcTicker.Stop()
+	}
+	return h.db.Close()
+}
+
+// OnSessionEstablished adds a client to the store when their session is established.
+func (h *Hook) OnSessionEstablished(cl *mqtt.Client, pk packets.Packet) {
+	h.updateClient(cl)
+}
+
+// OnWillSent is called when a client sends a Will Message and the Will Message is removed from the client record.
+func (h *Hook) OnWillSent(cl *mqtt.Client, pk packets.Packet) {
+	h.updateClient(cl)
+}
+
+// updateClient writes the client data to the store.
+func (h *Hook) updateClient(cl *mqtt.Client) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	props := cl.Properties.Props.Copy(false)
+	in := &storage.Client{
+		ID:              clientKey(cl),
+		T:               storage.ClientKey,
+		Remote:          cl.Net.Remote,
+		Listener:        cl.Net.Listener,
+		Username:        cl.Properties.Username,
+		Clean:           cl.Properties.Clean,
+		ProtocolVersion: cl.Properties.ProtocolVersion,
+		Properties: storage.ClientProperties{
+			SessionExpiryInterval: props.SessionExpiryInterval,
+			AuthenticationMethod:  props.AuthenticationMethod,
+			AuthenticationData:    props.AuthenticationData,
+			RequestProblemInfo:    props.RequestProblemInfo,
+			RequestResponseInfo:   props.RequestResponseInfo,
+			ReceiveMaximum:        props.ReceiveMaximum,
+			TopicAliasMaximum:     props.TopicAliasMaximum,
+			User:                  props.User,
+			MaximumPacketSize:     props.MaximumPacketSize,
+		},
+		Will: storage.ClientWill(cl.Properties.Will),
+	}
+
+	err := h.db.Upsert(in.ID, in)
+	if err != nil {
+		h.Log.Error("failed to upsert client data", "error", err, "data", in)
+	}
+}
+
+// OnDisconnect removes a client from the store if their session has expired.
+func (h *Hook) OnDisconnect(cl *mqtt.Client, _ error, expire bool) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	h.updateClient(cl)
+
+	if !expire {
+		return
+	}
+
+	if errors.Is(cl.StopCause(), packets.ErrSessionTakenOver) {
+		return
+	}
+
+	err := h.db.Delete(clientKey(cl), new(storage.Client))
+	if err != nil {
+		h.Log.Error("failed to delete client data", "error", err, "data", clientKey(cl))
+	}
+}
+
+// OnSubscribed adds one or more client subscriptions to the store.
+func (h *Hook) OnSubscribed(cl *mqtt.Client, pk packets.Packet, reasonCodes []byte) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	var in *storage.Subscription
+	for i := 0; i < len(pk.Filters); i++ {
+		in = &storage.Subscription{
+			ID:                subscriptionKey(cl, pk.Filters[i].Filter),
+			T:                 storage.SubscriptionKey,
+			Client:            cl.ID,
+			Qos:               reasonCodes[i],
+			Filter:            pk.Filters[i].Filter,
+			Identifier:        pk.Filters[i].Identifier,
+			NoLocal:           pk.Filters[i].NoLocal,
+			RetainHandling:    pk.Filters[i].RetainHandling,
+			RetainAsPublished: pk.Filters[i].RetainAsPublished,
+		}
+
+		err := h.db.Upsert(in.ID, in)
+		if err != nil {
+			h.Log.Error("failed to upsert subscription data", "error", err, "data", in)
+		}
+	}
+}
+
+// OnUnsubscribed removes one or more client subscriptions from the store.
+func (h *Hook) OnUnsubscribed(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	for i := 0; i < len(pk.Filters); i++ {
+		err := h.db.Delete(subscriptionKey(cl, pk.Filters[i].Filter), new(storage.Subscription))
+		if err != nil {
+			h.Log.Error("failed to delete subscription data", "error", err, "data", subscriptionKey(cl, pk.Filters[i].Filter))
+		}
+	}
+}
+
+// OnRetainMessage adds a retained message for a topic to the store.
+func (h *Hook) OnRetainMessage(cl *mqtt.Client, pk packets.Packet, r int64) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	if r == -1 {
+		err := h.db.Delete(retainedKey(pk.TopicName), new(storage.Message))
+		if err != nil {
+			h.Log.Error("failed to delete retained message data", "error", err, "data", retainedKey(pk.TopicName))
+		}
+
+		return
+	}
+
+	props := pk.Properties.Copy(false)
+	in := &storage.Message{
+		ID:          retainedKey(pk.TopicName),
+		T:           storage.RetainedKey,
+		FixedHeader: pk.FixedHeader,
+		TopicName:   pk.TopicName,
+		Payload:     pk.Payload,
+		Created:     pk.Created,
+		Origin:      pk.Origin,
+		Properties: storage.MessageProperties{
+			PayloadFormat:          props.PayloadFormat,
+			MessageExpiryInterval:  props.MessageExpiryInterval,
+			ContentType:            props.ContentType,
+			ResponseTopic:          props.ResponseTopic,
+			CorrelationData:        props.CorrelationData,
+			SubscriptionIdentifier: props.SubscriptionIdentifier,
+			TopicAlias:             props.TopicAlias,
+			User:                   props.User,
+		},
+	}
+
+	err := h.db.Upsert(in.ID, in)
+	if err != nil {
+		h.Log.Error("failed to upsert retained message data", "error", err, "data", in)
+	}
+}
+
+// OnQosPublish adds or updates an inflight message in the store.
+func (h *Hook) OnQosPublish(cl *mqtt.Client, pk packets.Packet, sent int64, resends int) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	props := pk.Properties.Copy(false)
+	in := &storage.Message{
+		ID:          inflightKey(cl, pk),
+		T:           storage.InflightKey,
+		Origin:      pk.Origin,
+		PacketID:    pk.PacketID,
+		FixedHeader: pk.FixedHeader,
+		TopicName:   pk.TopicName,
+		Payload:     pk.Payload,
+		Sent:        sent,
+		Created:     pk.Created,
+		Properties: storage.MessageProperties{
+			PayloadFormat:          props.PayloadFormat,
+			MessageExpiryInterval:  props.MessageExpiryInterval,
+			ContentType:            props.ContentType,
+			ResponseTopic:          props.ResponseTopic,
+			CorrelationData:        props.CorrelationData,
+			SubscriptionIdentifier: props.SubscriptionIdentifier,
+			TopicAlias:             props.TopicAlias,
+			User:                   props.User,
+		},
+	}
+
+	err := h.db.Upsert(in.ID, in)
+	if err != nil {
+		h.Log.Error("failed to upsert qos inflight data", "error", err, "data", in)
+	}
+}
+
+// OnQosComplete removes a resolved inflight message from the store.
+func (h *Hook) OnQosComplete(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err := h.db.Delete(inflightKey(cl, pk), new(storage.Message))
+	if err != nil {
+		h.Log.Error("failed to delete inflight message data", "error", err, "data", inflightKey(cl, pk))
+	}
+}
+
+// OnQosDropped removes a dropped inflight message from the store.
+func (h *Hook) OnQosDropped(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+	}
+
+	h.OnQosComplete(cl, pk)
+}
+
+// OnSysInfoTick stores the latest system info in the store.
+func (h *Hook) OnSysInfoTick(sys *system.Info) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	in := &storage.SystemInfo{
+		ID:   sysInfoKey(),
+		T:    storage.SysInfoKey,
+		Info: *sys.Clone(),
+	}
+
+	err := h.db.Upsert(in.ID, in)
+	if err != nil {
+		h.Log.Error("failed to upsert $SYS data", "error", err, "data", in)
+	}
+}
+
+// OnRetainedExpired deletes expired retained messages from the store.
+func (h *Hook) OnRetainedExpired(filter string) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err := h.db.Delete(retainedKey(filter), new(storage.Message))
+	if err != nil {
+		h.Log.Error("failed to delete expired retained message data", "error", err, "id", retainedKey(filter))
+	}
+}
+
+// OnClientExpired deleted expired clients from the store.
+func (h *Hook) OnClientExpired(cl *mqtt.Client) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err := h.db.Delete(clientKey(cl), new(storage.Client))
+	if err != nil {
+		h.Log.Error("failed to delete expired client data", "error", err, "id", clientKey(cl))
+	}
+}
+
+// StoredClients returns all stored clients from the store.
+func (h *Hook) StoredClients() (v []storage.Client, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Find(&v, badgerhold.Where("T").Eq(storage.ClientKey))
+	if err != nil && !errors.Is(err, badgerhold.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// StoredSubscriptions returns all stored subscriptions from the store.
+func (h *Hook) StoredSubscriptions() (v []storage.Subscription, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Find(&v, badgerhold.Where("T").Eq(storage.SubscriptionKey))
+	if err != nil && !errors.Is(err, badgerhold.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// StoredRetainedMessages returns all stored retained messages from the store.
+func (h *Hook) StoredRetainedMessages() (v []storage.Message, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Find(&v, badgerhold.Where("T").Eq(storage.RetainedKey))
+	if err != nil && !errors.Is(err, badgerhold.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// StoredInflightMessages returns all stored inflight messages from the store.
+func (h *Hook) StoredInflightMessages() (v []storage.Message, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Find(&v, badgerhold.Where("T").Eq(storage.InflightKey))
+	if err != nil && !errors.Is(err, badgerhold.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// StoredSysInfo returns the system info from the store.
+func (h *Hook) StoredSysInfo() (v storage.SystemInfo, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Get(storage.SysInfoKey, &v)
+	if err != nil && !errors.Is(err, badgerhold.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// Errorf satisfies the badger interface for an error logger.
+func (h *Hook) Errorf(m string, v ...interface{}) {
+	h.Log.Error(fmt.Sprintf(strings.ToLower(strings.Trim(m, "\n")), v...), "v", v)
+
+}
+
+// Warningf satisfies the badger interface for a warning logger.
+func (h *Hook) Warningf(m string, v ...interface{}) {
+	h.Log.Warn(fmt.Sprintf(strings.ToLower(strings.Trim(m, "\n")), v...), "v", v)
+}
+
+// Infof satisfies the badger interface for an info logger.
+func (h *Hook) Infof(m string, v ...interface{}) {
+	h.Log.Info(fmt.Sprintf(strings.ToLower(strings.Trim(m, "\n")), v...), "v", v)
+}
+
+// Debugf satisfies the badger interface for a debug logger.
+func (h *Hook) Debugf(m string, v ...interface{}) {
+	h.Log.Debug(fmt.Sprintf(strings.ToLower(strings.Trim(m, "\n")), v...), "v", v)
+}

hooks/storage/badger/badger_test.go

@@ -0,0 +1,723 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package badger
+
+import (
+	"log/slog"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	badgerdb "github.com/dgraph-io/badger"
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+	"github.com/stretchr/testify/require"
+	"github.com/timshannon/badgerhold"
+)
+
+var (
+	logger = slog.New(slog.NewTextHandler(os.Stdout, nil))
+
+	client = &mqtt.Client{
+		ID: "test",
+		Net: mqtt.ClientConnection{
+			Remote:   "test.addr",
+			Listener: "listener",
+		},
+		Properties: mqtt.ClientProperties{
+			Username: []byte("username"),
+			Clean:    false,
+		},
+	}
+
+	pkf = packets.Packet{Filters: packets.Subscriptions{{Filter: "a/b/c"}}}
+)
+
+func teardown(t *testing.T, path string, h *Hook) {
+	_ = h.Stop()
+	_ = h.db.Badger().Close()
+	err := os.RemoveAll("./" + strings.Replace(path, "..", "", -1))
+	require.NoError(t, err)
+}
+
+func TestClientKey(t *testing.T) {
+	k := clientKey(&mqtt.Client{ID: "cl1"})
+	require.Equal(t, "cl1", k)
+}
+
+func TestSubscriptionKey(t *testing.T) {
+	k := subscriptionKey(&mqtt.Client{ID: "cl1"}, "a/b/c")
+	require.Equal(t, storage.SubscriptionKey+"_cl1:a/b/c", k)
+}
+
+func TestRetainedKey(t *testing.T) {
+	k := retainedKey("a/b/c")
+	require.Equal(t, storage.RetainedKey+"_a/b/c", k)
+}
+
+func TestInflightKey(t *testing.T) {
+	k := inflightKey(&mqtt.Client{ID: "cl1"}, packets.Packet{PacketID: 1})
+	require.Equal(t, storage.InflightKey+"_cl1:1", k)
+}
+
+func TestSysInfoKey(t *testing.T) {
+	require.Equal(t, storage.SysInfoKey, sysInfoKey())
+}
+
+func TestID(t *testing.T) {
+	h := new(Hook)
+	require.Equal(t, "badger-db", h.ID())
+}
+
+func TestProvides(t *testing.T) {
+	h := new(Hook)
+	require.True(t, h.Provides(mqtt.OnSessionEstablished))
+	require.True(t, h.Provides(mqtt.OnDisconnect))
+	require.True(t, h.Provides(mqtt.OnSubscribed))
+	require.True(t, h.Provides(mqtt.OnUnsubscribed))
+	require.True(t, h.Provides(mqtt.OnRetainMessage))
+	require.True(t, h.Provides(mqtt.OnQosPublish))
+	require.True(t, h.Provides(mqtt.OnQosComplete))
+	require.True(t, h.Provides(mqtt.OnQosDropped))
+	require.True(t, h.Provides(mqtt.OnSysInfoTick))
+	require.True(t, h.Provides(mqtt.StoredClients))
+	require.True(t, h.Provides(mqtt.StoredInflightMessages))
+	require.True(t, h.Provides(mqtt.StoredRetainedMessages))
+	require.True(t, h.Provides(mqtt.StoredSubscriptions))
+	require.True(t, h.Provides(mqtt.StoredSysInfo))
+	require.False(t, h.Provides(mqtt.OnACLCheck))
+	require.False(t, h.Provides(mqtt.OnConnectAuthenticate))
+}
+
+func TestInitBadConfig(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	err := h.Init(map[string]any{})
+	require.Error(t, err)
+}
+
+func TestInitUseDefaults(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	require.Equal(t, defaultDbFile, h.config.Path)
+}
+
+func TestOnSessionEstablishedThenOnDisconnect(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	h.OnSessionEstablished(client, packets.Packet{})
+
+	r := new(storage.Client)
+	err = h.db.Get(clientKey(client), r)
+	require.NoError(t, err)
+	require.Equal(t, client.ID, r.ID)
+	require.Equal(t, client.Properties.Username, r.Username)
+	require.Equal(t, client.Properties.Clean, r.Clean)
+	require.Equal(t, client.Net.Remote, r.Remote)
+	require.Equal(t, client.Net.Listener, r.Listener)
+	require.NotSame(t, client, r)
+
+	h.OnDisconnect(client, nil, false)
+	r2 := new(storage.Client)
+	err = h.db.Get(clientKey(client), r2)
+	require.NoError(t, err)
+	require.Equal(t, client.ID, r.ID)
+
+	h.OnDisconnect(client, nil, true)
+	r3 := new(storage.Client)
+	err = h.db.Get(clientKey(client), r3)
+	require.Error(t, err)
+	require.ErrorIs(t, badgerhold.ErrNotFound, err)
+	require.Empty(t, r3.ID)
+}
+
+func TestOnClientExpired(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	cl := &mqtt.Client{ID: "cl1"}
+	clientKey := clientKey(cl)
+
+	err = h.db.Upsert(clientKey, &storage.Client{ID: cl.ID})
+	require.NoError(t, err)
+
+	r := new(storage.Client)
+	err = h.db.Get(clientKey, r)
+	require.NoError(t, err)
+	require.Equal(t, cl.ID, r.ID)
+
+	h.OnClientExpired(cl)
+	err = h.db.Get(clientKey, r)
+	require.Error(t, err)
+	require.ErrorIs(t, badgerhold.ErrNotFound, err)
+}
+
+func TestOnClientExpiredNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnClientExpired(client)
+}
+
+func TestOnClientExpiredClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnClientExpired(client)
+}
+
+func TestOnSessionEstablishedNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnSessionEstablished(client, packets.Packet{})
+}
+
+func TestOnSessionEstablishedClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnSessionEstablished(client, packets.Packet{})
+}
+
+func TestOnWillSent(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	c1 := client
+	c1.Properties.Will.Flag = 1
+	h.OnWillSent(c1, packets.Packet{})
+
+	r := new(storage.Client)
+	err = h.db.Get(clientKey(client), r)
+	require.NoError(t, err)
+
+	require.Equal(t, uint32(1), r.Will.Flag)
+	require.NotSame(t, client, r)
+}
+
+func TestOnDisconnectNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnDisconnect(client, nil, false)
+}
+
+func TestOnDisconnectClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnDisconnect(client, nil, false)
+}
+
+func TestOnDisconnectSessionTakenOver(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+
+	testClient := &mqtt.Client{
+		ID: "test",
+		Net: mqtt.ClientConnection{
+			Remote:   "test.addr",
+			Listener: "listener",
+		},
+		Properties: mqtt.ClientProperties{
+			Username: []byte("username"),
+			Clean:    false,
+		},
+	}
+
+	testClient.Stop(packets.ErrSessionTakenOver)
+	teardown(t, h.config.Path, h)
+	h.OnDisconnect(testClient, nil, true)
+}
+
+func TestOnSubscribedThenOnUnsubscribed(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	h.OnSubscribed(client, pkf, []byte{0})
+	r := new(storage.Subscription)
+
+	err = h.db.Get(subscriptionKey(client, pkf.Filters[0].Filter), r)
+	require.NoError(t, err)
+	require.Equal(t, client.ID, r.Client)
+	require.Equal(t, pkf.Filters[0].Filter, r.Filter)
+	require.Equal(t, byte(0), r.Qos)
+
+	h.OnUnsubscribed(client, pkf)
+	err = h.db.Get(subscriptionKey(client, pkf.Filters[0].Filter), r)
+	require.Error(t, err)
+	require.Equal(t, badgerhold.ErrNotFound, err)
+}
+
+func TestOnSubscribedNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnSubscribed(client, pkf, []byte{0})
+}
+
+func TestOnSubscribedClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnSubscribed(client, pkf, []byte{0})
+}
+
+func TestOnUnsubscribedNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnUnsubscribed(client, pkf)
+}
+
+func TestOnUnsubscribedClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnUnsubscribed(client, pkf)
+}
+
+func TestOnRetainMessageThenUnset(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	pk := packets.Packet{
+		FixedHeader: packets.FixedHeader{
+			Retain: true,
+		},
+		Payload:   []byte("hello"),
+		TopicName: "a/b/c",
+	}
+
+	h.OnRetainMessage(client, pk, 1)
+
+	r := new(storage.Message)
+	err = h.db.Get(retainedKey(pk.TopicName), r)
+	require.NoError(t, err)
+	require.Equal(t, pk.TopicName, r.TopicName)
+	require.Equal(t, pk.Payload, r.Payload)
+
+	h.OnRetainMessage(client, pk, -1)
+	err = h.db.Get(retainedKey(pk.TopicName), r)
+	require.Error(t, err)
+	require.ErrorIs(t, err, badgerhold.ErrNotFound)
+
+	// coverage: delete deleted
+	h.OnRetainMessage(client, pk, -1)
+	err = h.db.Get(retainedKey(pk.TopicName), r)
+	require.Error(t, err)
+	require.ErrorIs(t, err, badgerhold.ErrNotFound)
+}
+
+func TestOnRetainedExpired(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	m := &storage.Message{
+		ID:        retainedKey("a/b/c"),
+		T:         storage.RetainedKey,
+		TopicName: "a/b/c",
+	}
+
+	err = h.db.Upsert(m.ID, m)
+	require.NoError(t, err)
+
+	r := new(storage.Message)
+	err = h.db.Get(m.ID, r)
+	require.NoError(t, err)
+	require.Equal(t, m.TopicName, r.TopicName)
+
+	h.OnRetainedExpired(m.TopicName)
+	err = h.db.Get(m.ID, r)
+	require.Error(t, err)
+	require.ErrorIs(t, err, badgerhold.ErrNotFound)
+}
+
+func TestOnRetainExpiredNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnRetainedExpired("a/b/c")
+}
+
+func TestOnRetainExpiredClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnRetainedExpired("a/b/c")
+}
+
+func TestOnRetainMessageNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnRetainMessage(client, packets.Packet{}, 0)
+}
+
+func TestOnRetainMessageClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnRetainMessage(client, packets.Packet{}, 0)
+}
+
+func TestOnQosPublishThenQOSComplete(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	pk := packets.Packet{
+		FixedHeader: packets.FixedHeader{
+			Retain: true,
+			Qos:    2,
+		},
+		Payload:   []byte("hello"),
+		TopicName: "a/b/c",
+	}
+
+	h.OnQosPublish(client, pk, time.Now().Unix(), 0)
+
+	r := new(storage.Message)
+	err = h.db.Get(inflightKey(client, pk), r)
+	require.NoError(t, err)
+	require.Equal(t, pk.TopicName, r.TopicName)
+	require.Equal(t, pk.Payload, r.Payload)
+
+	// ensure dates are properly saved
+	require.True(t, r.Sent > 0)
+	require.True(t, time.Now().Unix()-1 < r.Sent)
+
+	// OnQosDropped is a passthrough to OnQosComplete here
+	h.OnQosDropped(client, pk)
+	err = h.db.Get(inflightKey(client, pk), r)
+	require.Error(t, err)
+	require.ErrorIs(t, err, badgerhold.ErrNotFound)
+}
+
+func TestOnQosPublishNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnQosPublish(client, packets.Packet{}, time.Now().Unix(), 0)
+}
+
+func TestOnQosPublishClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnQosPublish(client, packets.Packet{}, time.Now().Unix(), 0)
+}
+
+func TestOnQosCompleteNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnQosComplete(client, packets.Packet{})
+}
+
+func TestOnQosCompleteClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnQosComplete(client, packets.Packet{})
+}
+
+func TestOnQosDroppedNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnQosDropped(client, packets.Packet{})
+}
+
+func TestOnSysInfoTick(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	info := &system.Info{
+		Version:       "2.0.0",
+		BytesReceived: 100,
+	}
+
+	h.OnSysInfoTick(info)
+
+	r := new(storage.SystemInfo)
+	err = h.db.Get(storage.SysInfoKey, r)
+	require.NoError(t, err)
+	require.Equal(t, info.Version, r.Version)
+	require.Equal(t, info.BytesReceived, r.BytesReceived)
+	require.NotSame(t, info, r)
+}
+
+func TestOnSysInfoTickNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnSysInfoTick(new(system.Info))
+}
+
+func TestOnSysInfoTickClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnSysInfoTick(new(system.Info))
+}
+
+func TestStoredClients(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with clients
+	err = h.db.Upsert("cl1", &storage.Client{ID: "cl1", T: storage.ClientKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("cl2", &storage.Client{ID: "cl2", T: storage.ClientKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("cl3", &storage.Client{ID: "cl3", T: storage.ClientKey})
+	require.NoError(t, err)
+
+	r, err := h.StoredClients()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	require.Equal(t, "cl1", r[0].ID)
+	require.Equal(t, "cl2", r[1].ID)
+	require.Equal(t, "cl3", r[2].ID)
+}
+
+func TestStoredClientsNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredClients()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredSubscriptions(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with subscriptions
+	err = h.db.Upsert("sub1", &storage.Subscription{ID: "sub1", T: storage.SubscriptionKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("sub2", &storage.Subscription{ID: "sub2", T: storage.SubscriptionKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("sub3", &storage.Subscription{ID: "sub3", T: storage.SubscriptionKey})
+	require.NoError(t, err)
+
+	r, err := h.StoredSubscriptions()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	require.Equal(t, "sub1", r[0].ID)
+	require.Equal(t, "sub2", r[1].ID)
+	require.Equal(t, "sub3", r[2].ID)
+}
+
+func TestStoredSubscriptionsNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredSubscriptions()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredRetainedMessages(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with messages
+	err = h.db.Upsert("m1", &storage.Message{ID: "m1", T: storage.RetainedKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("m2", &storage.Message{ID: "m2", T: storage.RetainedKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("m3", &storage.Message{ID: "m3", T: storage.RetainedKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("i3", &storage.Message{ID: "i3", T: storage.InflightKey})
+	require.NoError(t, err)
+
+	r, err := h.StoredRetainedMessages()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	require.Equal(t, "m1", r[0].ID)
+	require.Equal(t, "m2", r[1].ID)
+	require.Equal(t, "m3", r[2].ID)
+}
+
+func TestStoredRetainedMessagesNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredRetainedMessages()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredInflightMessages(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with messages
+	err = h.db.Upsert("i1", &storage.Message{ID: "i1", T: storage.InflightKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("i2", &storage.Message{ID: "i2", T: storage.InflightKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("i3", &storage.Message{ID: "i3", T: storage.InflightKey})
+	require.NoError(t, err)
+
+	err = h.db.Upsert("m1", &storage.Message{ID: "m1", T: storage.RetainedKey})
+	require.NoError(t, err)
+
+	r, err := h.StoredInflightMessages()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	require.Equal(t, "i1", r[0].ID)
+	require.Equal(t, "i2", r[1].ID)
+	require.Equal(t, "i3", r[2].ID)
+}
+
+func TestStoredInflightMessagesNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredInflightMessages()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredSysInfo(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with messages
+	err = h.db.Upsert(storage.SysInfoKey, &storage.SystemInfo{
+		ID: storage.SysInfoKey,
+		Info: system.Info{
+			Version: "2.0.0",
+		},
+		T: storage.SysInfoKey,
+	})
+	require.NoError(t, err)
+
+	r, err := h.StoredSysInfo()
+	require.NoError(t, err)
+	require.Equal(t, "2.0.0", r.Info.Version)
+}
+
+func TestStoredSysInfoNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredSysInfo()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestErrorf(t *testing.T) {
+	// coverage: one day check log hook
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.Errorf("test", 1, 2, 3)
+}
+
+func TestWarningf(t *testing.T) {
+	// coverage: one day check log hook
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.Warningf("test", 1, 2, 3)
+}
+
+func TestInfof(t *testing.T) {
+	// coverage: one day check log hook
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.Infof("test", 1, 2, 3)
+}
+
+func TestDebugf(t *testing.T) {
+	// coverage: one day check log hook
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.Debugf("test", 1, 2, 3)
+}
+
+func TestGcLoop(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.Init(&Options{
+		GcInterval: 2, // Set the interval for garbage collection.
+		Options: &badgerhold.Options{
+			// BadgerDB options. Modify as needed.
+			Options: badgerdb.Options{
+				ValueLogFileSize: 1 << 20, // Set the default size of the log file to 1 MB.
+			},
+		},
+	})
+	defer teardown(t, h.config.Path, h)
+	h.OnSessionEstablished(client, packets.Packet{})
+	h.OnDisconnect(client, nil, true)
+	time.Sleep(3 * time.Second)
+}

hooks/storage/bolt/bolt.go

@@ -0,0 +1,461 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+// Package bolt is provided for historical compatibility and may not be actively updated, you should use the badger hook instead.
+package bolt
+
+import (
+	"bytes"
+	"errors"
+	"time"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+
+	sgob "github.com/asdine/storm/codec/gob"
+	"github.com/asdine/storm/v3"
+	"go.etcd.io/bbolt"
+)
+
+const (
+	// defaultDbFile is the default file path for the boltdb file.
+	defaultDbFile = "bolt.db"
+
+	// defaultTimeout is the default time to hold a connection to the file.
+	defaultTimeout = 250 * time.Millisecond
+)
+
+// clientKey returns a primary key for a client.
+func clientKey(cl *mqtt.Client) string {
+	return cl.ID
+}
+
+// subscriptionKey returns a primary key for a subscription.
+func subscriptionKey(cl *mqtt.Client, filter string) string {
+	return storage.SubscriptionKey + "_" + cl.ID + ":" + filter
+}
+
+// retainedKey returns a primary key for a retained message.
+func retainedKey(topic string) string {
+	return storage.RetainedKey + "_" + topic
+}
+
+// inflightKey returns a primary key for an inflight message.
+func inflightKey(cl *mqtt.Client, pk packets.Packet) string {
+	return storage.InflightKey + "_" + cl.ID + ":" + pk.FormatID()
+}
+
+// sysInfoKey returns a primary key for system info.
+func sysInfoKey() string {
+	return storage.SysInfoKey
+}
+
+// Options contains configuration settings for the bolt instance.
+type Options struct {
+	Options *bbolt.Options
+	Path    string `yaml:"path" json:"path"`
+}
+
+// Hook is a persistent storage hook based using boltdb file store as a backend.
+type Hook struct {
+	mqtt.HookBase
+	config *Options  // options for configuring the boltdb instance.
+	db     *storm.DB // the boltdb instance.
+}
+
+// ID returns the id of the hook.
+func (h *Hook) ID() string {
+	return "bolt-db"
+}
+
+// Provides indicates which hook methods this hook provides.
+func (h *Hook) Provides(b byte) bool {
+	return bytes.Contains([]byte{
+		mqtt.OnSessionEstablished,
+		mqtt.OnDisconnect,
+		mqtt.OnSubscribed,
+		mqtt.OnUnsubscribed,
+		mqtt.OnRetainMessage,
+		mqtt.OnWillSent,
+		mqtt.OnQosPublish,
+		mqtt.OnQosComplete,
+		mqtt.OnQosDropped,
+		mqtt.OnSysInfoTick,
+		mqtt.OnClientExpired,
+		mqtt.OnRetainedExpired,
+		mqtt.StoredClients,
+		mqtt.StoredInflightMessages,
+		mqtt.StoredRetainedMessages,
+		mqtt.StoredSubscriptions,
+		mqtt.StoredSysInfo,
+	}, []byte{b})
+}
+
+// Init initializes and connects to the boltdb instance.
+func (h *Hook) Init(config any) error {
+	if _, ok := config.(*Options); !ok && config != nil {
+		return mqtt.ErrInvalidConfigType
+	}
+
+	if config == nil {
+		config = new(Options)
+	}
+
+	h.config = config.(*Options)
+	if h.config.Options == nil {
+		h.config.Options = &bbolt.Options{
+			Timeout: defaultTimeout,
+		}
+	}
+	if h.config.Path == "" {
+		h.config.Path = defaultDbFile
+	}
+
+	var err error
+	h.db, err = storm.Open(h.config.Path, storm.BoltOptions(0600, h.config.Options), storm.Codec(sgob.Codec))
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// Stop closes the boltdb instance.
+func (h *Hook) Stop() error {
+	return h.db.Close()
+}
+
+// OnSessionEstablished adds a client to the store when their session is established.
+func (h *Hook) OnSessionEstablished(cl *mqtt.Client, pk packets.Packet) {
+	h.updateClient(cl)
+}
+
+// OnWillSent is called when a client sends a Will Message and the Will Message is removed from the client record.
+func (h *Hook) OnWillSent(cl *mqtt.Client, pk packets.Packet) {
+	h.updateClient(cl)
+}
+
+// updateClient writes the client data to the store.
+func (h *Hook) updateClient(cl *mqtt.Client) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	props := cl.Properties.Props.Copy(false)
+	in := &storage.Client{
+		ID:              clientKey(cl),
+		T:               storage.ClientKey,
+		Remote:          cl.Net.Remote,
+		Listener:        cl.Net.Listener,
+		Username:        cl.Properties.Username,
+		Clean:           cl.Properties.Clean,
+		ProtocolVersion: cl.Properties.ProtocolVersion,
+		Properties: storage.ClientProperties{
+			SessionExpiryInterval: props.SessionExpiryInterval,
+			AuthenticationMethod:  props.AuthenticationMethod,
+			AuthenticationData:    props.AuthenticationData,
+			RequestProblemInfo:    props.RequestProblemInfo,
+			RequestResponseInfo:   props.RequestResponseInfo,
+			ReceiveMaximum:        props.ReceiveMaximum,
+			TopicAliasMaximum:     props.TopicAliasMaximum,
+			User:                  props.User,
+			MaximumPacketSize:     props.MaximumPacketSize,
+		},
+		Will: storage.ClientWill(cl.Properties.Will),
+	}
+	err := h.db.Save(in)
+	if err != nil {
+		h.Log.Error("failed to save client data", "error", err, "data", in)
+	}
+}
+
+// OnDisconnect removes a client from the store if they were using a clean session.
+func (h *Hook) OnDisconnect(cl *mqtt.Client, _ error, expire bool) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	if !expire {
+		return
+	}
+
+	if cl.StopCause() == packets.ErrSessionTakenOver {
+		return
+	}
+
+	err := h.db.DeleteStruct(&storage.Client{ID: clientKey(cl)})
+	if err != nil && !errors.Is(err, storm.ErrNotFound) {
+		h.Log.Error("failed to delete client", "error", err, "id", clientKey(cl))
+	}
+}
+
+// OnSubscribed adds one or more client subscriptions to the store.
+func (h *Hook) OnSubscribed(cl *mqtt.Client, pk packets.Packet, reasonCodes []byte) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	var in *storage.Subscription
+	for i := 0; i < len(pk.Filters); i++ {
+		in = &storage.Subscription{
+			ID:                subscriptionKey(cl, pk.Filters[i].Filter),
+			T:                 storage.SubscriptionKey,
+			Client:            cl.ID,
+			Qos:               reasonCodes[i],
+			Filter:            pk.Filters[i].Filter,
+			Identifier:        pk.Filters[i].Identifier,
+			NoLocal:           pk.Filters[i].NoLocal,
+			RetainHandling:    pk.Filters[i].RetainHandling,
+			RetainAsPublished: pk.Filters[i].RetainAsPublished,
+		}
+
+		err := h.db.Save(in)
+		if err != nil {
+			h.Log.Error("failed to save subscription data", "error", err, "client", cl.ID, "data", in)
+		}
+	}
+}
+
+// OnUnsubscribed removes one or more client subscriptions from the store.
+func (h *Hook) OnUnsubscribed(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	for i := 0; i < len(pk.Filters); i++ {
+		err := h.db.DeleteStruct(&storage.Subscription{
+			ID: subscriptionKey(cl, pk.Filters[i].Filter),
+		})
+		if err != nil {
+			h.Log.Error("failed to delete client", "error", err, "id", subscriptionKey(cl, pk.Filters[i].Filter))
+		}
+	}
+}
+
+// OnRetainMessage adds a retained message for a topic to the store.
+func (h *Hook) OnRetainMessage(cl *mqtt.Client, pk packets.Packet, r int64) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	if r == -1 {
+		err := h.db.DeleteStruct(&storage.Message{
+			ID: retainedKey(pk.TopicName),
+		})
+		if err != nil {
+			h.Log.Error("failed to delete retained publish", "error", err, "id", retainedKey(pk.TopicName))
+		}
+		return
+	}
+
+	props := pk.Properties.Copy(false)
+	in := &storage.Message{
+		ID:          retainedKey(pk.TopicName),
+		T:           storage.RetainedKey,
+		FixedHeader: pk.FixedHeader,
+		TopicName:   pk.TopicName,
+		Payload:     pk.Payload,
+		Created:     pk.Created,
+		Origin:      pk.Origin,
+		Properties: storage.MessageProperties{
+			PayloadFormat:          props.PayloadFormat,
+			MessageExpiryInterval:  props.MessageExpiryInterval,
+			ContentType:            props.ContentType,
+			ResponseTopic:          props.ResponseTopic,
+			CorrelationData:        props.CorrelationData,
+			SubscriptionIdentifier: props.SubscriptionIdentifier,
+			TopicAlias:             props.TopicAlias,
+			User:                   props.User,
+		},
+	}
+	err := h.db.Save(in)
+	if err != nil {
+		h.Log.Error("failed to save retained publish data", "error", err, "client", cl.ID, "data", in)
+	}
+}
+
+// OnQosPublish adds or updates an inflight message in the store.
+func (h *Hook) OnQosPublish(cl *mqtt.Client, pk packets.Packet, sent int64, resends int) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	props := pk.Properties.Copy(false)
+	in := &storage.Message{
+		ID:          inflightKey(cl, pk),
+		T:           storage.InflightKey,
+		Origin:      pk.Origin,
+		FixedHeader: pk.FixedHeader,
+		TopicName:   pk.TopicName,
+		Payload:     pk.Payload,
+		Sent:        sent,
+		Created:     pk.Created,
+		Properties: storage.MessageProperties{
+			PayloadFormat:          props.PayloadFormat,
+			MessageExpiryInterval:  props.MessageExpiryInterval,
+			ContentType:            props.ContentType,
+			ResponseTopic:          props.ResponseTopic,
+			CorrelationData:        props.CorrelationData,
+			SubscriptionIdentifier: props.SubscriptionIdentifier,
+			TopicAlias:             props.TopicAlias,
+			User:                   props.User,
+		},
+	}
+
+	err := h.db.Save(in)
+	if err != nil {
+		h.Log.Error("failed to save qos inflight data", "error", err, "client", cl.ID, "data", in)
+	}
+}
+
+// OnQosComplete removes a resolved inflight message from the store.
+func (h *Hook) OnQosComplete(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err := h.db.DeleteStruct(&storage.Message{
+		ID: inflightKey(cl, pk),
+	})
+	if err != nil {
+		h.Log.Error("failed to delete inflight data", "error", err, "id", inflightKey(cl, pk))
+	}
+}
+
+// OnQosDropped removes a dropped inflight message from the store.
+func (h *Hook) OnQosDropped(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+	}
+
+	h.OnQosComplete(cl, pk)
+}
+
+// OnSysInfoTick stores the latest system info in the store.
+func (h *Hook) OnSysInfoTick(sys *system.Info) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	in := &storage.SystemInfo{
+		ID:   sysInfoKey(),
+		T:    storage.SysInfoKey,
+		Info: *sys,
+	}
+
+	err := h.db.Save(in)
+	if err != nil {
+		h.Log.Error("failed to save $SYS data", "error", err, "data", in)
+	}
+}
+
+// OnRetainedExpired deletes expired retained messages from the store.
+func (h *Hook) OnRetainedExpired(filter string) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	if err := h.db.DeleteStruct(&storage.Message{ID: retainedKey(filter)}); err != nil {
+		h.Log.Error("failed to delete retained publish", "error", err, "id", retainedKey(filter))
+	}
+}
+
+// OnClientExpired deleted expired clients from the store.
+func (h *Hook) OnClientExpired(cl *mqtt.Client) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err := h.db.DeleteStruct(&storage.Client{ID: clientKey(cl)})
+	if err != nil && !errors.Is(err, storm.ErrNotFound) {
+		h.Log.Error("failed to delete expired client", "error", err, "id", clientKey(cl))
+	}
+}
+
+// StoredClients returns all stored clients from the store.
+func (h *Hook) StoredClients() (v []storage.Client, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Find("T", storage.ClientKey, &v)
+	if err != nil && !errors.Is(err, storm.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// StoredSubscriptions returns all stored subscriptions from the store.
+func (h *Hook) StoredSubscriptions() (v []storage.Subscription, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Find("T", storage.SubscriptionKey, &v)
+	if err != nil && !errors.Is(err, storm.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// StoredRetainedMessages returns all stored retained messages from the store.
+func (h *Hook) StoredRetainedMessages() (v []storage.Message, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Find("T", storage.RetainedKey, &v)
+	if err != nil && !errors.Is(err, storm.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// StoredInflightMessages returns all stored inflight messages from the store.
+func (h *Hook) StoredInflightMessages() (v []storage.Message, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.Find("T", storage.InflightKey, &v)
+	if err != nil && !errors.Is(err, storm.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}
+
+// StoredSysInfo returns the system info from the store.
+func (h *Hook) StoredSysInfo() (v storage.SystemInfo, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err = h.db.One("ID", storage.SysInfoKey, &v)
+	if err != nil && !errors.Is(err, storm.ErrNotFound) {
+		return
+	}
+
+	return v, nil
+}

hooks/storage/bolt/bolt_test.go

@@ -0,0 +1,740 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package bolt
+
+import (
+	"log/slog"
+	"os"
+	"testing"
+	"time"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+
+	"github.com/asdine/storm/v3"
+	"github.com/stretchr/testify/require"
+)
+
+var (
+	logger = slog.New(slog.NewTextHandler(os.Stdout, nil))
+
+	client = &mqtt.Client{
+		ID: "test",
+		Net: mqtt.ClientConnection{
+			Remote:   "test.addr",
+			Listener: "listener",
+		},
+		Properties: mqtt.ClientProperties{
+			Username: []byte("username"),
+			Clean:    false,
+		},
+	}
+
+	pkf = packets.Packet{Filters: packets.Subscriptions{{Filter: "a/b/c"}}}
+)
+
+func teardown(t *testing.T, path string, h *Hook) {
+	_ = h.Stop()
+	err := os.Remove(path)
+	require.NoError(t, err)
+}
+
+func TestClientKey(t *testing.T) {
+	k := clientKey(&mqtt.Client{ID: "cl1"})
+	require.Equal(t, "cl1", k)
+}
+
+func TestSubscriptionKey(t *testing.T) {
+	k := subscriptionKey(&mqtt.Client{ID: "cl1"}, "a/b/c")
+	require.Equal(t, storage.SubscriptionKey+"_cl1:a/b/c", k)
+}
+
+func TestRetainedKey(t *testing.T) {
+	k := retainedKey("a/b/c")
+	require.Equal(t, storage.RetainedKey+"_a/b/c", k)
+}
+
+func TestInflightKey(t *testing.T) {
+	k := inflightKey(&mqtt.Client{ID: "cl1"}, packets.Packet{PacketID: 1})
+	require.Equal(t, storage.InflightKey+"_cl1:1", k)
+}
+
+func TestSysInfoKey(t *testing.T) {
+	require.Equal(t, storage.SysInfoKey, sysInfoKey())
+}
+
+func TestID(t *testing.T) {
+	h := new(Hook)
+	require.Equal(t, "bolt-db", h.ID())
+}
+
+func TestProvides(t *testing.T) {
+	h := new(Hook)
+	require.True(t, h.Provides(mqtt.OnSessionEstablished))
+	require.True(t, h.Provides(mqtt.OnDisconnect))
+	require.True(t, h.Provides(mqtt.OnSubscribed))
+	require.True(t, h.Provides(mqtt.OnUnsubscribed))
+	require.True(t, h.Provides(mqtt.OnRetainMessage))
+	require.True(t, h.Provides(mqtt.OnQosPublish))
+	require.True(t, h.Provides(mqtt.OnQosComplete))
+	require.True(t, h.Provides(mqtt.OnQosDropped))
+	require.True(t, h.Provides(mqtt.OnSysInfoTick))
+	require.True(t, h.Provides(mqtt.StoredClients))
+	require.True(t, h.Provides(mqtt.StoredInflightMessages))
+	require.True(t, h.Provides(mqtt.StoredRetainedMessages))
+	require.True(t, h.Provides(mqtt.StoredSubscriptions))
+	require.True(t, h.Provides(mqtt.StoredSysInfo))
+	require.False(t, h.Provides(mqtt.OnACLCheck))
+	require.False(t, h.Provides(mqtt.OnConnectAuthenticate))
+}
+
+func TestInitBadConfig(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	err := h.Init(map[string]any{})
+	require.Error(t, err)
+}
+
+func TestInitUseDefaults(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	require.Equal(t, defaultTimeout, h.config.Options.Timeout)
+	require.Equal(t, defaultDbFile, h.config.Path)
+}
+
+func TestInitBadPath(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(&Options{
+		Path: "..",
+	})
+	require.Error(t, err)
+}
+
+func TestOnSessionEstablishedThenOnDisconnect(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	h.OnSessionEstablished(client, packets.Packet{})
+
+	r := new(storage.Client)
+	err = h.db.One("ID", clientKey(client), r)
+	require.NoError(t, err)
+	require.Equal(t, client.ID, r.ID)
+	require.Equal(t, client.Net.Remote, r.Remote)
+	require.Equal(t, client.Net.Listener, r.Listener)
+	require.Equal(t, client.Properties.Username, r.Username)
+	require.Equal(t, client.Properties.Clean, r.Clean)
+	require.NotSame(t, client, r)
+
+	h.OnDisconnect(client, nil, false)
+	r2 := new(storage.Client)
+	err = h.db.One("ID", clientKey(client), r2)
+	require.NoError(t, err)
+	require.Equal(t, client.ID, r.ID)
+
+	h.OnDisconnect(client, nil, true)
+	r3 := new(storage.Client)
+	err = h.db.One("ID", clientKey(client), r3)
+	require.Error(t, err)
+	require.ErrorIs(t, storm.ErrNotFound, err)
+	require.Empty(t, r3.ID)
+}
+
+func TestOnSessionEstablishedNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnSessionEstablished(client, packets.Packet{})
+}
+
+func TestOnSessionEstablishedClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnSessionEstablished(client, packets.Packet{})
+}
+
+func TestOnWillSent(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	c1 := client
+	c1.Properties.Will.Flag = 1
+	h.OnWillSent(c1, packets.Packet{})
+
+	r := new(storage.Client)
+	err = h.db.One("ID", clientKey(client), r)
+	require.NoError(t, err)
+
+	require.Equal(t, uint32(1), r.Will.Flag)
+	require.NotSame(t, client, r)
+}
+
+func TestOnClientExpired(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	cl := &mqtt.Client{ID: "cl1"}
+	clientKey := clientKey(cl)
+
+	err = h.db.Save(&storage.Client{ID: cl.ID})
+	require.NoError(t, err)
+
+	r := new(storage.Client)
+	err = h.db.One("ID", clientKey, r)
+	require.NoError(t, err)
+	require.Equal(t, cl.ID, r.ID)
+
+	h.OnClientExpired(cl)
+	err = h.db.One("ID", clientKey, r)
+	require.Error(t, err)
+	require.ErrorIs(t, storm.ErrNotFound, err)
+}
+
+func TestOnClientExpiredClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnClientExpired(client)
+}
+
+func TestOnClientExpiredNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnClientExpired(client)
+}
+
+func TestOnDisconnectNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnDisconnect(client, nil, false)
+}
+
+func TestOnDisconnectClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnDisconnect(client, nil, false)
+}
+
+func TestOnDisconnectSessionTakenOver(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+
+	testClient := &mqtt.Client{
+		ID: "test",
+		Net: mqtt.ClientConnection{
+			Remote:   "test.addr",
+			Listener: "listener",
+		},
+		Properties: mqtt.ClientProperties{
+			Username: []byte("username"),
+			Clean:    false,
+		},
+	}
+
+	testClient.Stop(packets.ErrSessionTakenOver)
+	teardown(t, h.config.Path, h)
+	h.OnDisconnect(testClient, nil, true)
+}
+
+func TestOnSubscribedThenOnUnsubscribed(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	h.OnSubscribed(client, pkf, []byte{0})
+	r := new(storage.Subscription)
+
+	err = h.db.One("ID", subscriptionKey(client, pkf.Filters[0].Filter), r)
+	require.NoError(t, err)
+	require.Equal(t, client.ID, r.Client)
+	require.Equal(t, pkf.Filters[0].Filter, r.Filter)
+	require.Equal(t, byte(0), r.Qos)
+
+	h.OnUnsubscribed(client, pkf)
+	err = h.db.One("ID", subscriptionKey(client, pkf.Filters[0].Filter), r)
+	require.Error(t, err)
+	require.Equal(t, storm.ErrNotFound, err)
+}
+
+func TestOnSubscribedNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnSubscribed(client, pkf, []byte{0})
+}
+
+func TestOnSubscribedClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnSubscribed(client, pkf, []byte{0})
+}
+
+func TestOnUnsubscribedNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnUnsubscribed(client, pkf)
+}
+
+func TestOnUnsubscribedClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnUnsubscribed(client, pkf)
+}
+
+func TestOnRetainMessageThenUnset(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	pk := packets.Packet{
+		FixedHeader: packets.FixedHeader{
+			Retain: true,
+		},
+		Payload:   []byte("hello"),
+		TopicName: "a/b/c",
+	}
+
+	h.OnRetainMessage(client, pk, 1)
+
+	r := new(storage.Message)
+	err = h.db.One("ID", retainedKey(pk.TopicName), r)
+	require.NoError(t, err)
+	require.Equal(t, pk.TopicName, r.TopicName)
+	require.Equal(t, pk.Payload, r.Payload)
+
+	h.OnRetainMessage(client, pk, -1)
+	err = h.db.One("ID", retainedKey(pk.TopicName), r)
+	require.Error(t, err)
+	require.Equal(t, storm.ErrNotFound, err)
+
+	// coverage: delete deleted
+	h.OnRetainMessage(client, pk, -1)
+	err = h.db.One("ID", retainedKey(pk.TopicName), r)
+	require.Error(t, err)
+	require.Equal(t, storm.ErrNotFound, err)
+}
+
+func TestOnRetainedExpired(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	m := &storage.Message{
+		ID:        retainedKey("a/b/c"),
+		T:         storage.RetainedKey,
+		TopicName: "a/b/c",
+	}
+
+	err = h.db.Save(m)
+	require.NoError(t, err)
+
+	r := new(storage.Message)
+	err = h.db.One("ID", m.ID, r)
+	require.NoError(t, err)
+	require.Equal(t, m.TopicName, r.TopicName)
+
+	h.OnRetainedExpired(m.TopicName)
+	err = h.db.One("ID", m.ID, r)
+	require.Error(t, err)
+	require.Equal(t, storm.ErrNotFound, err)
+}
+
+func TestOnRetainedExpiredClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnRetainedExpired("a/b/c")
+}
+
+func TestOnRetainedExpiredNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnRetainedExpired("a/b/c")
+}
+
+func TestOnRetainMessageNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnRetainMessage(client, packets.Packet{}, 0)
+}
+
+func TestOnRetainMessageClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnRetainMessage(client, packets.Packet{}, 0)
+}
+
+func TestOnQosPublishThenQOSComplete(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	pk := packets.Packet{
+		FixedHeader: packets.FixedHeader{
+			Retain: true,
+			Qos:    2,
+		},
+		Payload:   []byte("hello"),
+		TopicName: "a/b/c",
+	}
+
+	h.OnQosPublish(client, pk, time.Now().Unix(), 0)
+
+	r := new(storage.Message)
+	err = h.db.One("ID", inflightKey(client, pk), r)
+	require.NoError(t, err)
+	require.Equal(t, pk.TopicName, r.TopicName)
+	require.Equal(t, pk.Payload, r.Payload)
+
+	// ensure dates are properly saved to bolt
+	require.True(t, r.Sent > 0)
+	require.True(t, time.Now().Unix()-1 < r.Sent)
+
+	// OnQosDropped is a passthrough to OnQosComplete here
+	h.OnQosDropped(client, pk)
+	err = h.db.One("ID", inflightKey(client, pk), r)
+	require.Error(t, err)
+	require.Equal(t, storm.ErrNotFound, err)
+}
+
+func TestOnQosPublishNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnQosPublish(client, packets.Packet{}, time.Now().Unix(), 0)
+}
+
+func TestOnQosPublishClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnQosPublish(client, packets.Packet{}, time.Now().Unix(), 0)
+}
+
+func TestOnQosCompleteNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnQosComplete(client, packets.Packet{})
+}
+
+func TestOnQosCompleteClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnQosComplete(client, packets.Packet{})
+}
+
+func TestOnQosDroppedNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnQosDropped(client, packets.Packet{})
+}
+
+func TestOnSysInfoTick(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	info := &system.Info{
+		Version:       "2.0.0",
+		BytesReceived: 100,
+	}
+
+	h.OnSysInfoTick(info)
+
+	r := new(storage.SystemInfo)
+	err = h.db.One("ID", storage.SysInfoKey, r)
+	require.NoError(t, err)
+	require.Equal(t, info.Version, r.Version)
+	require.Equal(t, info.BytesReceived, r.BytesReceived)
+	require.NotSame(t, info, r)
+}
+
+func TestOnSysInfoTickNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	h.OnSysInfoTick(new(system.Info))
+}
+
+func TestOnSysInfoTickClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	h.OnSysInfoTick(new(system.Info))
+}
+
+func TestStoredClients(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with clients
+	err = h.db.Save(&storage.Client{ID: "cl1", T: storage.ClientKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Client{ID: "cl2", T: storage.ClientKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Client{ID: "cl3", T: storage.ClientKey})
+	require.NoError(t, err)
+
+	r, err := h.StoredClients()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	require.Equal(t, "cl1", r[0].ID)
+	require.Equal(t, "cl2", r[1].ID)
+	require.Equal(t, "cl3", r[2].ID)
+}
+
+func TestStoredClientsNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredClients()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredClientsClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	v, err := h.StoredClients()
+	require.Empty(t, v)
+	require.Error(t, err)
+}
+
+func TestStoredSubscriptions(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with subscriptions
+	err = h.db.Save(&storage.Subscription{ID: "sub1", T: storage.SubscriptionKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Subscription{ID: "sub2", T: storage.SubscriptionKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Subscription{ID: "sub3", T: storage.SubscriptionKey})
+	require.NoError(t, err)
+
+	r, err := h.StoredSubscriptions()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	require.Equal(t, "sub1", r[0].ID)
+	require.Equal(t, "sub2", r[1].ID)
+	require.Equal(t, "sub3", r[2].ID)
+}
+
+func TestStoredSubscriptionsNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredSubscriptions()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredSubscriptionsClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	v, err := h.StoredSubscriptions()
+	require.Empty(t, v)
+	require.Error(t, err)
+}
+
+func TestStoredRetainedMessages(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with messages
+	err = h.db.Save(&storage.Message{ID: "m1", T: storage.RetainedKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Message{ID: "m2", T: storage.RetainedKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Message{ID: "m3", T: storage.RetainedKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Message{ID: "i3", T: storage.InflightKey})
+	require.NoError(t, err)
+
+	r, err := h.StoredRetainedMessages()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	require.Equal(t, "m1", r[0].ID)
+	require.Equal(t, "m2", r[1].ID)
+	require.Equal(t, "m3", r[2].ID)
+}
+
+func TestStoredRetainedMessagesNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredRetainedMessages()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredRetainedMessagesClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	v, err := h.StoredRetainedMessages()
+	require.Empty(t, v)
+	require.Error(t, err)
+}
+
+func TestStoredInflightMessages(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with messages
+	err = h.db.Save(&storage.Message{ID: "i1", T: storage.InflightKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Message{ID: "i2", T: storage.InflightKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Message{ID: "i3", T: storage.InflightKey})
+	require.NoError(t, err)
+
+	err = h.db.Save(&storage.Message{ID: "m1", T: storage.RetainedKey})
+	require.NoError(t, err)
+
+	r, err := h.StoredInflightMessages()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	require.Equal(t, "i1", r[0].ID)
+	require.Equal(t, "i2", r[1].ID)
+	require.Equal(t, "i3", r[2].ID)
+}
+
+func TestStoredInflightMessagesNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredInflightMessages()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredInflightMessagesClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	v, err := h.StoredInflightMessages()
+	require.Empty(t, v)
+	require.Error(t, err)
+}
+
+func TestStoredSysInfo(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h.config.Path, h)
+
+	// populate with sys info
+	err = h.db.Save(&storage.SystemInfo{
+		ID: storage.SysInfoKey,
+		Info: system.Info{
+			Version: "2.0.0",
+		},
+		T: storage.SysInfoKey,
+	})
+	require.NoError(t, err)
+
+	r, err := h.StoredSysInfo()
+	require.NoError(t, err)
+	require.Equal(t, "2.0.0", r.Info.Version)
+}
+
+func TestStoredSysInfoNoDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	v, err := h.StoredSysInfo()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredSysInfoClosedDB(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	teardown(t, h.config.Path, h)
+	v, err := h.StoredSysInfo()
+	require.Empty(t, v)
+	require.Error(t, err)
+}

hooks/storage/redis/redis.go

@@ -0,0 +1,528 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package redis
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+
+	"github.com/go-redis/redis/v8"
+)
+
+// defaultAddr is the default address to the redis service.
+const defaultAddr = "localhost:6379"
+
+// defaultHPrefix is a prefix to better identify hsets created by mochi mqtt.
+const defaultHPrefix = "mochi-"
+
+// clientKey returns a primary key for a client.
+func clientKey(cl *mqtt.Client) string {
+	return cl.ID
+}
+
+// subscriptionKey returns a primary key for a subscription.
+func subscriptionKey(cl *mqtt.Client, filter string) string {
+	return cl.ID + ":" + filter
+}
+
+// retainedKey returns a primary key for a retained message.
+func retainedKey(topic string) string {
+	return topic
+}
+
+// inflightKey returns a primary key for an inflight message.
+func inflightKey(cl *mqtt.Client, pk packets.Packet) string {
+	return cl.ID + ":" + pk.FormatID()
+}
+
+// sysInfoKey returns a primary key for system info.
+func sysInfoKey() string {
+	return storage.SysInfoKey
+}
+
+// Options contains configuration settings for the bolt instance.
+type Options struct {
+	Address  string `yaml:"address" json:"address"`
+	Username string `yaml:"username" json:"username"`
+	Password string `yaml:"password" json:"password"`
+	Database int    `yaml:"database" json:"database"`
+	HPrefix  string `yaml:"h_prefix" json:"h_prefix"`
+	Options  *redis.Options
+}
+
+// Hook is a persistent storage hook based using Redis as a backend.
+type Hook struct {
+	mqtt.HookBase
+	config *Options        // options for connecting to the Redis instance.
+	db     *redis.Client   // the Redis instance
+	ctx    context.Context // a context for the connection
+}
+
+// ID returns the id of the hook.
+func (h *Hook) ID() string {
+	return "redis-db"
+}
+
+// Provides indicates which hook methods this hook provides.
+func (h *Hook) Provides(b byte) bool {
+	return bytes.Contains([]byte{
+		mqtt.OnSessionEstablished,
+		mqtt.OnDisconnect,
+		mqtt.OnSubscribed,
+		mqtt.OnUnsubscribed,
+		mqtt.OnRetainMessage,
+		mqtt.OnQosPublish,
+		mqtt.OnQosComplete,
+		mqtt.OnQosDropped,
+		mqtt.OnWillSent,
+		mqtt.OnSysInfoTick,
+		mqtt.OnClientExpired,
+		mqtt.OnRetainedExpired,
+		mqtt.StoredClients,
+		mqtt.StoredInflightMessages,
+		mqtt.StoredRetainedMessages,
+		mqtt.StoredSubscriptions,
+		mqtt.StoredSysInfo,
+	}, []byte{b})
+}
+
+// hKey returns a hash set key with a unique prefix.
+func (h *Hook) hKey(s string) string {
+	return h.config.HPrefix + s
+}
+
+// Init initializes and connects to the redis service.
+func (h *Hook) Init(config any) error {
+	if _, ok := config.(*Options); !ok && config != nil {
+		return mqtt.ErrInvalidConfigType
+	}
+
+	h.ctx = context.Background()
+
+	if config == nil {
+		config = new(Options)
+	}
+	h.config = config.(*Options)
+	if h.config.Options == nil {
+		h.config.Options = &redis.Options{
+			Addr: defaultAddr,
+		}
+		h.config.Options.Addr = h.config.Address
+		h.config.Options.DB = h.config.Database
+		h.config.Options.Username = h.config.Username
+		h.config.Options.Password = h.config.Password
+	}
+
+	if h.config.HPrefix == "" {
+		h.config.HPrefix = defaultHPrefix
+	}
+
+	h.Log.Info(
+		"connecting to redis service",
+		"prefix", h.config.HPrefix,
+		"address", h.config.Options.Addr,
+		"username", h.config.Options.Username,
+		"password-len", len(h.config.Options.Password),
+		"db", h.config.Options.DB,
+	)
+
+	h.db = redis.NewClient(h.config.Options)
+	_, err := h.db.Ping(context.Background()).Result()
+	if err != nil {
+		return fmt.Errorf("failed to ping service: %w", err)
+	}
+
+	h.Log.Info("connected to redis service")
+
+	return nil
+}
+
+// Stop closes the redis connection.
+func (h *Hook) Stop() error {
+	h.Log.Info("disconnecting from redis service")
+
+	return h.db.Close()
+}
+
+// OnSessionEstablished adds a client to the store when their session is established.
+func (h *Hook) OnSessionEstablished(cl *mqtt.Client, pk packets.Packet) {
+	h.updateClient(cl)
+}
+
+// OnWillSent is called when a client sends a Will Message and the Will Message is removed from the client record.
+func (h *Hook) OnWillSent(cl *mqtt.Client, pk packets.Packet) {
+	h.updateClient(cl)
+}
+
+// updateClient writes the client data to the store.
+func (h *Hook) updateClient(cl *mqtt.Client) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	props := cl.Properties.Props.Copy(false)
+	in := &storage.Client{
+		ID:              clientKey(cl),
+		T:               storage.ClientKey,
+		Remote:          cl.Net.Remote,
+		Listener:        cl.Net.Listener,
+		Username:        cl.Properties.Username,
+		Clean:           cl.Properties.Clean,
+		ProtocolVersion: cl.Properties.ProtocolVersion,
+		Properties: storage.ClientProperties{
+			SessionExpiryInterval: props.SessionExpiryInterval,
+			AuthenticationMethod:  props.AuthenticationMethod,
+			AuthenticationData:    props.AuthenticationData,
+			RequestProblemInfo:    props.RequestProblemInfo,
+			RequestResponseInfo:   props.RequestResponseInfo,
+			ReceiveMaximum:        props.ReceiveMaximum,
+			TopicAliasMaximum:     props.TopicAliasMaximum,
+			User:                  props.User,
+			MaximumPacketSize:     props.MaximumPacketSize,
+		},
+		Will: storage.ClientWill(cl.Properties.Will),
+	}
+
+	err := h.db.HSet(h.ctx, h.hKey(storage.ClientKey), clientKey(cl), in).Err()
+	if err != nil {
+		h.Log.Error("failed to hset client data", "error", err, "data", in)
+	}
+}
+
+// OnDisconnect removes a client from the store if they were using a clean session.
+func (h *Hook) OnDisconnect(cl *mqtt.Client, _ error, expire bool) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	if !expire {
+		return
+	}
+
+	if cl.StopCause() == packets.ErrSessionTakenOver {
+		return
+	}
+
+	err := h.db.HDel(h.ctx, h.hKey(storage.ClientKey), clientKey(cl)).Err()
+	if err != nil {
+		h.Log.Error("failed to delete client", "error", err, "id", clientKey(cl))
+	}
+}
+
+// OnSubscribed adds one or more client subscriptions to the store.
+func (h *Hook) OnSubscribed(cl *mqtt.Client, pk packets.Packet, reasonCodes []byte) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	var in *storage.Subscription
+	for i := 0; i < len(pk.Filters); i++ {
+		in = &storage.Subscription{
+			ID:                subscriptionKey(cl, pk.Filters[i].Filter),
+			T:                 storage.SubscriptionKey,
+			Client:            cl.ID,
+			Qos:               reasonCodes[i],
+			Filter:            pk.Filters[i].Filter,
+			Identifier:        pk.Filters[i].Identifier,
+			NoLocal:           pk.Filters[i].NoLocal,
+			RetainHandling:    pk.Filters[i].RetainHandling,
+			RetainAsPublished: pk.Filters[i].RetainAsPublished,
+		}
+
+		err := h.db.HSet(h.ctx, h.hKey(storage.SubscriptionKey), subscriptionKey(cl, pk.Filters[i].Filter), in).Err()
+		if err != nil {
+			h.Log.Error("failed to hset subscription data", "error", err, "data", in)
+		}
+	}
+}
+
+// OnUnsubscribed removes one or more client subscriptions from the store.
+func (h *Hook) OnUnsubscribed(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	for i := 0; i < len(pk.Filters); i++ {
+		err := h.db.HDel(h.ctx, h.hKey(storage.SubscriptionKey), subscriptionKey(cl, pk.Filters[i].Filter)).Err()
+		if err != nil {
+			h.Log.Error("failed to delete subscription data", "error", err, "id", clientKey(cl))
+		}
+	}
+}
+
+// OnRetainMessage adds a retained message for a topic to the store.
+func (h *Hook) OnRetainMessage(cl *mqtt.Client, pk packets.Packet, r int64) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	if r == -1 {
+		err := h.db.HDel(h.ctx, h.hKey(storage.RetainedKey), retainedKey(pk.TopicName)).Err()
+		if err != nil {
+			h.Log.Error("failed to delete retained message data", "error", err, "id", retainedKey(pk.TopicName))
+		}
+
+		return
+	}
+
+	props := pk.Properties.Copy(false)
+	in := &storage.Message{
+		ID:          retainedKey(pk.TopicName),
+		T:           storage.RetainedKey,
+		FixedHeader: pk.FixedHeader,
+		TopicName:   pk.TopicName,
+		Payload:     pk.Payload,
+		Created:     pk.Created,
+		Origin:      pk.Origin,
+		Properties: storage.MessageProperties{
+			PayloadFormat:          props.PayloadFormat,
+			MessageExpiryInterval:  props.MessageExpiryInterval,
+			ContentType:            props.ContentType,
+			ResponseTopic:          props.ResponseTopic,
+			CorrelationData:        props.CorrelationData,
+			SubscriptionIdentifier: props.SubscriptionIdentifier,
+			TopicAlias:             props.TopicAlias,
+			User:                   props.User,
+		},
+	}
+
+	err := h.db.HSet(h.ctx, h.hKey(storage.RetainedKey), retainedKey(pk.TopicName), in).Err()
+	if err != nil {
+		h.Log.Error("failed to hset retained message data", "error", err, "data", in)
+	}
+}
+
+// OnQosPublish adds or updates an inflight message in the store.
+func (h *Hook) OnQosPublish(cl *mqtt.Client, pk packets.Packet, sent int64, resends int) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	props := pk.Properties.Copy(false)
+	in := &storage.Message{
+		ID:          inflightKey(cl, pk),
+		T:           storage.InflightKey,
+		Origin:      pk.Origin,
+		FixedHeader: pk.FixedHeader,
+		TopicName:   pk.TopicName,
+		Payload:     pk.Payload,
+		Sent:        sent,
+		Created:     pk.Created,
+		Properties: storage.MessageProperties{
+			PayloadFormat:          props.PayloadFormat,
+			MessageExpiryInterval:  props.MessageExpiryInterval,
+			ContentType:            props.ContentType,
+			ResponseTopic:          props.ResponseTopic,
+			CorrelationData:        props.CorrelationData,
+			SubscriptionIdentifier: props.SubscriptionIdentifier,
+			TopicAlias:             props.TopicAlias,
+			User:                   props.User,
+		},
+	}
+
+	err := h.db.HSet(h.ctx, h.hKey(storage.InflightKey), inflightKey(cl, pk), in).Err()
+	if err != nil {
+		h.Log.Error("failed to hset qos inflight message data", "error", err, "data", in)
+	}
+}
+
+// OnQosComplete removes a resolved inflight message from the store.
+func (h *Hook) OnQosComplete(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err := h.db.HDel(h.ctx, h.hKey(storage.InflightKey), inflightKey(cl, pk)).Err()
+	if err != nil {
+		h.Log.Error("failed to delete qos inflight message data", "error", err, "id", inflightKey(cl, pk))
+	}
+}
+
+// OnQosDropped removes a dropped inflight message from the store.
+func (h *Hook) OnQosDropped(cl *mqtt.Client, pk packets.Packet) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+	}
+
+	h.OnQosComplete(cl, pk)
+}
+
+// OnSysInfoTick stores the latest system info in the store.
+func (h *Hook) OnSysInfoTick(sys *system.Info) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	in := &storage.SystemInfo{
+		ID:   sysInfoKey(),
+		T:    storage.SysInfoKey,
+		Info: *sys,
+	}
+
+	err := h.db.HSet(h.ctx, h.hKey(storage.SysInfoKey), sysInfoKey(), in).Err()
+	if err != nil {
+		h.Log.Error("failed to hset server info data", "error", err, "data", in)
+	}
+}
+
+// OnRetainedExpired deletes expired retained messages from the store.
+func (h *Hook) OnRetainedExpired(filter string) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err := h.db.HDel(h.ctx, h.hKey(storage.RetainedKey), retainedKey(filter)).Err()
+	if err != nil {
+		h.Log.Error("failed to delete expired retained message", "error", err, "id", retainedKey(filter))
+	}
+}
+
+// OnClientExpired deleted expired clients from the store.
+func (h *Hook) OnClientExpired(cl *mqtt.Client) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	err := h.db.HDel(h.ctx, h.hKey(storage.ClientKey), clientKey(cl)).Err()
+	if err != nil {
+		h.Log.Error("failed to delete expired client", "error", err, "id", clientKey(cl))
+	}
+}
+
+// StoredClients returns all stored clients from the store.
+func (h *Hook) StoredClients() (v []storage.Client, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	rows, err := h.db.HGetAll(h.ctx, h.hKey(storage.ClientKey)).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		h.Log.Error("failed to HGetAll client data", "error", err)
+		return
+	}
+
+	for _, row := range rows {
+		var d storage.Client
+		if err = d.UnmarshalBinary([]byte(row)); err != nil {
+			h.Log.Error("failed to unmarshal client data", "error", err, "data", row)
+		}
+
+		v = append(v, d)
+	}
+
+	return v, nil
+}
+
+// StoredSubscriptions returns all stored subscriptions from the store.
+func (h *Hook) StoredSubscriptions() (v []storage.Subscription, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	rows, err := h.db.HGetAll(h.ctx, h.hKey(storage.SubscriptionKey)).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		h.Log.Error("failed to HGetAll subscription data", "error", err)
+		return
+	}
+
+	for _, row := range rows {
+		var d storage.Subscription
+		if err = d.UnmarshalBinary([]byte(row)); err != nil {
+			h.Log.Error("failed to unmarshal subscription data", "error", err, "data", row)
+		}
+
+		v = append(v, d)
+	}
+
+	return v, nil
+}
+
+// StoredRetainedMessages returns all stored retained messages from the store.
+func (h *Hook) StoredRetainedMessages() (v []storage.Message, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	rows, err := h.db.HGetAll(h.ctx, h.hKey(storage.RetainedKey)).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		h.Log.Error("failed to HGetAll retained message data", "error", err)
+		return
+	}
+
+	for _, row := range rows {
+		var d storage.Message
+		if err = d.UnmarshalBinary([]byte(row)); err != nil {
+			h.Log.Error("failed to unmarshal retained message data", "error", err, "data", row)
+		}
+
+		v = append(v, d)
+	}
+
+	return v, nil
+}
+
+// StoredInflightMessages returns all stored inflight messages from the store.
+func (h *Hook) StoredInflightMessages() (v []storage.Message, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	rows, err := h.db.HGetAll(h.ctx, h.hKey(storage.InflightKey)).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		h.Log.Error("failed to HGetAll inflight message data", "error", err)
+		return
+	}
+
+	for _, row := range rows {
+		var d storage.Message
+		if err = d.UnmarshalBinary([]byte(row)); err != nil {
+			h.Log.Error("failed to unmarshal inflight message data", "error", err, "data", row)
+		}
+
+		v = append(v, d)
+	}
+
+	return v, nil
+}
+
+// StoredSysInfo returns the system info from the store.
+func (h *Hook) StoredSysInfo() (v storage.SystemInfo, err error) {
+	if h.db == nil {
+		h.Log.Error("", "error", storage.ErrDBFileNotOpen)
+		return
+	}
+
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.SysInfoKey), storage.SysInfoKey).Result()
+	if err != nil && !errors.Is(err, redis.Nil) {
+		return
+	}
+
+	if err = v.UnmarshalBinary([]byte(row)); err != nil {
+		h.Log.Error("failed to unmarshal sys info data", "error", err, "data", row)
+	}
+
+	return v, nil
+}

hooks/storage/redis/redis_test.go

@@ -0,0 +1,834 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package redis
+
+import (
+	"log/slog"
+	"os"
+	"sort"
+	"testing"
+	"time"
+
+	mqtt "github.com/mochi-mqtt/server/v2"
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+
+	miniredis "github.com/alicebob/miniredis/v2"
+	redis "github.com/go-redis/redis/v8"
+	"github.com/stretchr/testify/require"
+)
+
+var (
+	logger = slog.New(slog.NewTextHandler(os.Stdout, nil))
+
+	client = &mqtt.Client{
+		ID: "test",
+		Net: mqtt.ClientConnection{
+			Remote:   "test.addr",
+			Listener: "listener",
+		},
+		Properties: mqtt.ClientProperties{
+			Username: []byte("username"),
+			Clean:    false,
+		},
+	}
+
+	pkf = packets.Packet{Filters: packets.Subscriptions{{Filter: "a/b/c"}}}
+)
+
+func newHook(t *testing.T, addr string) *Hook {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	err := h.Init(&Options{
+		Options: &redis.Options{
+			Addr: addr,
+		},
+	})
+	require.NoError(t, err)
+
+	return h
+}
+
+func teardown(t *testing.T, h *Hook) {
+	if h.db != nil {
+		err := h.db.FlushAll(h.ctx).Err()
+		require.NoError(t, err)
+		h.Stop()
+	}
+}
+
+func TestClientKey(t *testing.T) {
+	k := clientKey(&mqtt.Client{ID: "cl1"})
+	require.Equal(t, "cl1", k)
+}
+
+func TestSubscriptionKey(t *testing.T) {
+	k := subscriptionKey(&mqtt.Client{ID: "cl1"}, "a/b/c")
+	require.Equal(t, "cl1:a/b/c", k)
+}
+
+func TestRetainedKey(t *testing.T) {
+	k := retainedKey("a/b/c")
+	require.Equal(t, "a/b/c", k)
+}
+
+func TestInflightKey(t *testing.T) {
+	k := inflightKey(&mqtt.Client{ID: "cl1"}, packets.Packet{PacketID: 1})
+	require.Equal(t, "cl1:1", k)
+}
+
+func TestSysInfoKey(t *testing.T) {
+	require.Equal(t, storage.SysInfoKey, sysInfoKey())
+}
+
+func TestID(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	require.Equal(t, "redis-db", h.ID())
+}
+
+func TestProvides(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	require.True(t, h.Provides(mqtt.OnSessionEstablished))
+	require.True(t, h.Provides(mqtt.OnDisconnect))
+	require.True(t, h.Provides(mqtt.OnSubscribed))
+	require.True(t, h.Provides(mqtt.OnUnsubscribed))
+	require.True(t, h.Provides(mqtt.OnRetainMessage))
+	require.True(t, h.Provides(mqtt.OnQosPublish))
+	require.True(t, h.Provides(mqtt.OnQosComplete))
+	require.True(t, h.Provides(mqtt.OnQosDropped))
+	require.True(t, h.Provides(mqtt.OnSysInfoTick))
+	require.True(t, h.Provides(mqtt.StoredClients))
+	require.True(t, h.Provides(mqtt.StoredInflightMessages))
+	require.True(t, h.Provides(mqtt.StoredRetainedMessages))
+	require.True(t, h.Provides(mqtt.StoredSubscriptions))
+	require.True(t, h.Provides(mqtt.StoredSysInfo))
+	require.False(t, h.Provides(mqtt.OnACLCheck))
+	require.False(t, h.Provides(mqtt.OnConnectAuthenticate))
+}
+
+func TestHKey(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.SetOpts(logger, nil)
+	require.Equal(t, defaultHPrefix+"test", h.hKey("test"))
+}
+
+func TestInitUseDefaults(t *testing.T) {
+	s := miniredis.RunT(t)
+	s.StartAddr(defaultAddr)
+	defer s.Close()
+
+	h := newHook(t, defaultAddr)
+	h.SetOpts(logger, nil)
+	err := h.Init(nil)
+	require.NoError(t, err)
+	defer teardown(t, h)
+
+	require.Equal(t, defaultHPrefix, h.config.HPrefix)
+	require.Equal(t, defaultAddr, h.config.Options.Addr)
+}
+
+func TestInitUsePassConfig(t *testing.T) {
+	s := miniredis.RunT(t)
+	s.StartAddr(defaultAddr)
+	defer s.Close()
+
+	h := newHook(t, "")
+	h.SetOpts(logger, nil)
+
+	err := h.Init(&Options{
+		Address:  defaultAddr,
+		Username: "username",
+		Password: "password",
+		Database: 2,
+	})
+	require.Error(t, err)
+	h.db.FlushAll(h.ctx)
+
+	require.Equal(t, defaultAddr, h.config.Options.Addr)
+	require.Equal(t, "username", h.config.Options.Username)
+	require.Equal(t, "password", h.config.Options.Password)
+	require.Equal(t, 2, h.config.Options.DB)
+}
+
+func TestInitBadConfig(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+
+	err := h.Init(map[string]any{})
+	require.Error(t, err)
+}
+
+func TestInitBadAddr(t *testing.T) {
+	h := new(Hook)
+	h.SetOpts(logger, nil)
+	err := h.Init(&Options{
+		Options: &redis.Options{
+			Addr: "abc:123",
+		},
+	})
+	require.Error(t, err)
+}
+
+func TestOnSessionEstablishedThenOnDisconnect(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	h.OnSessionEstablished(client, packets.Packet{})
+
+	r := new(storage.Client)
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.ClientKey), clientKey(client)).Result()
+	require.NoError(t, err)
+	err = r.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+
+	require.Equal(t, client.ID, r.ID)
+	require.Equal(t, client.Net.Remote, r.Remote)
+	require.Equal(t, client.Net.Listener, r.Listener)
+	require.Equal(t, client.Properties.Username, r.Username)
+	require.Equal(t, client.Properties.Clean, r.Clean)
+	require.NotSame(t, client, r)
+
+	h.OnDisconnect(client, nil, false)
+	r2 := new(storage.Client)
+	row, err = h.db.HGet(h.ctx, h.hKey(storage.ClientKey), clientKey(client)).Result()
+	require.NoError(t, err)
+	err = r2.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+	require.Equal(t, client.ID, r.ID)
+
+	h.OnDisconnect(client, nil, true)
+	r3 := new(storage.Client)
+	_, err = h.db.HGet(h.ctx, h.hKey(storage.ClientKey), clientKey(client)).Result()
+	require.Error(t, err)
+	require.ErrorIs(t, err, redis.Nil)
+	require.Empty(t, r3.ID)
+}
+
+func TestOnSessionEstablishedNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+
+	h.db = nil
+	h.OnSessionEstablished(client, packets.Packet{})
+}
+
+func TestOnSessionEstablishedClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnSessionEstablished(client, packets.Packet{})
+}
+
+func TestOnWillSent(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	c1 := client
+	c1.Properties.Will.Flag = 1
+	h.OnWillSent(c1, packets.Packet{})
+
+	r := new(storage.Client)
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.ClientKey), clientKey(client)).Result()
+	require.NoError(t, err)
+	err = r.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+
+	require.Equal(t, uint32(1), r.Will.Flag)
+	require.NotSame(t, client, r)
+}
+
+func TestOnClientExpired(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	cl := &mqtt.Client{ID: "cl1"}
+	clientKey := clientKey(cl)
+
+	err := h.db.HSet(h.ctx, h.hKey(storage.ClientKey), clientKey, &storage.Client{ID: cl.ID}).Err()
+	require.NoError(t, err)
+
+	r := new(storage.Client)
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.ClientKey), clientKey).Result()
+	require.NoError(t, err)
+	err = r.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+	require.Equal(t, clientKey, r.ID)
+
+	h.OnClientExpired(cl)
+	_, err = h.db.HGet(h.ctx, h.hKey(storage.ClientKey), clientKey).Result()
+	require.Error(t, err)
+	require.ErrorIs(t, redis.Nil, err)
+}
+
+func TestOnClientExpiredClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnClientExpired(client)
+}
+
+func TestOnClientExpiredNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnClientExpired(client)
+}
+
+func TestOnDisconnectNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnDisconnect(client, nil, false)
+}
+
+func TestOnDisconnectClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnDisconnect(client, nil, false)
+}
+
+func TestOnDisconnectSessionTakenOver(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+
+	testClient := &mqtt.Client{
+		ID: "test",
+		Net: mqtt.ClientConnection{
+			Remote:   "test.addr",
+			Listener: "listener",
+		},
+		Properties: mqtt.ClientProperties{
+			Username: []byte("username"),
+			Clean:    false,
+		},
+	}
+
+	testClient.Stop(packets.ErrSessionTakenOver)
+	teardown(t, h)
+	h.OnDisconnect(testClient, nil, true)
+}
+
+func TestOnSubscribedThenOnUnsubscribed(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	h.OnSubscribed(client, pkf, []byte{0})
+
+	r := new(storage.Subscription)
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.SubscriptionKey), subscriptionKey(client, pkf.Filters[0].Filter)).Result()
+	require.NoError(t, err)
+	err = r.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+	require.Equal(t, client.ID, r.Client)
+	require.Equal(t, pkf.Filters[0].Filter, r.Filter)
+	require.Equal(t, byte(0), r.Qos)
+
+	h.OnUnsubscribed(client, pkf)
+	_, err = h.db.HGet(h.ctx, h.hKey(storage.SubscriptionKey), subscriptionKey(client, pkf.Filters[0].Filter)).Result()
+	require.Error(t, err)
+	require.ErrorIs(t, err, redis.Nil)
+}
+
+func TestOnSubscribedNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnSubscribed(client, pkf, []byte{0})
+}
+
+func TestOnSubscribedClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnSubscribed(client, pkf, []byte{0})
+}
+
+func TestOnUnsubscribedNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnUnsubscribed(client, pkf)
+}
+
+func TestOnUnsubscribedClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnUnsubscribed(client, pkf)
+}
+
+func TestOnRetainMessageThenUnset(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	pk := packets.Packet{
+		FixedHeader: packets.FixedHeader{
+			Retain: true,
+		},
+		Payload:   []byte("hello"),
+		TopicName: "a/b/c",
+	}
+
+	h.OnRetainMessage(client, pk, 1)
+
+	r := new(storage.Message)
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.RetainedKey), retainedKey(pk.TopicName)).Result()
+	require.NoError(t, err)
+	err = r.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+
+	require.NoError(t, err)
+	require.Equal(t, pk.TopicName, r.TopicName)
+	require.Equal(t, pk.Payload, r.Payload)
+
+	h.OnRetainMessage(client, pk, -1)
+	_, err = h.db.HGet(h.ctx, h.hKey(storage.RetainedKey), retainedKey(pk.TopicName)).Result()
+	require.Error(t, err)
+	require.ErrorIs(t, err, redis.Nil)
+
+	// coverage: delete deleted
+	h.OnRetainMessage(client, pk, -1)
+	_, err = h.db.HGet(h.ctx, h.hKey(storage.RetainedKey), retainedKey(pk.TopicName)).Result()
+	require.Error(t, err)
+	require.ErrorIs(t, err, redis.Nil)
+}
+
+func TestOnRetainedExpired(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	m := &storage.Message{
+		ID:        retainedKey("a/b/c"),
+		T:         storage.RetainedKey,
+		TopicName: "a/b/c",
+	}
+
+	err := h.db.HSet(h.ctx, h.hKey(storage.RetainedKey), m.ID, m).Err()
+	require.NoError(t, err)
+
+	r := new(storage.Message)
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.RetainedKey), m.ID).Result()
+	require.NoError(t, err)
+	err = r.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+	require.NoError(t, err)
+	require.Equal(t, m.TopicName, r.TopicName)
+
+	h.OnRetainedExpired(m.TopicName)
+
+	_, err = h.db.HGet(h.ctx, h.hKey(storage.RetainedKey), m.ID).Result()
+	require.Error(t, err)
+	require.ErrorIs(t, err, redis.Nil)
+}
+
+func TestOnRetainedExpiredClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnRetainedExpired("a/b/c")
+}
+
+func TestOnRetainedExpiredNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnRetainedExpired("a/b/c")
+}
+
+func TestOnRetainMessageNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnRetainMessage(client, packets.Packet{}, 0)
+}
+
+func TestOnRetainMessageClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnRetainMessage(client, packets.Packet{}, 0)
+}
+
+func TestOnQosPublishThenQOSComplete(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	pk := packets.Packet{
+		FixedHeader: packets.FixedHeader{
+			Retain: true,
+			Qos:    2,
+		},
+		Payload:   []byte("hello"),
+		TopicName: "a/b/c",
+	}
+
+	h.OnQosPublish(client, pk, time.Now().Unix(), 0)
+
+	r := new(storage.Message)
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.InflightKey), inflightKey(client, pk)).Result()
+	require.NoError(t, err)
+	err = r.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+	require.Equal(t, pk.TopicName, r.TopicName)
+	require.Equal(t, pk.Payload, r.Payload)
+
+	// ensure dates are properly saved to bolt
+	require.True(t, r.Sent > 0)
+	require.True(t, time.Now().Unix()-1 < r.Sent)
+
+	// OnQosDropped is a passthrough to OnQosComplete here
+	h.OnQosDropped(client, pk)
+	_, err = h.db.HGet(h.ctx, h.hKey(storage.InflightKey), inflightKey(client, pk)).Result()
+	require.Error(t, err)
+	require.ErrorIs(t, err, redis.Nil)
+}
+
+func TestOnQosPublishNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnQosPublish(client, packets.Packet{}, time.Now().Unix(), 0)
+}
+
+func TestOnQosPublishClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnQosPublish(client, packets.Packet{}, time.Now().Unix(), 0)
+}
+
+func TestOnQosCompleteNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnQosComplete(client, packets.Packet{})
+}
+
+func TestOnQosCompleteClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnQosComplete(client, packets.Packet{})
+}
+
+func TestOnQosDroppedNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnQosDropped(client, packets.Packet{})
+}
+
+func TestOnSysInfoTick(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	info := &system.Info{
+		Version:       "2.0.0",
+		BytesReceived: 100,
+	}
+
+	h.OnSysInfoTick(info)
+
+	r := new(storage.SystemInfo)
+	row, err := h.db.HGet(h.ctx, h.hKey(storage.SysInfoKey), storage.SysInfoKey).Result()
+	require.NoError(t, err)
+	err = r.UnmarshalBinary([]byte(row))
+	require.NoError(t, err)
+	require.Equal(t, info.Version, r.Version)
+	require.Equal(t, info.BytesReceived, r.BytesReceived)
+	require.NotSame(t, info, r)
+}
+
+func TestOnSysInfoTickClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+	h.OnSysInfoTick(new(system.Info))
+}
+func TestOnSysInfoTickNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	h.OnSysInfoTick(new(system.Info))
+}
+
+func TestStoredClients(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	// populate with clients
+	err := h.db.HSet(h.ctx, h.hKey(storage.ClientKey), "cl1", &storage.Client{ID: "cl1", T: storage.ClientKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.ClientKey), "cl2", &storage.Client{ID: "cl2", T: storage.ClientKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.ClientKey), "cl3", &storage.Client{ID: "cl3", T: storage.ClientKey}).Err()
+	require.NoError(t, err)
+
+	r, err := h.StoredClients()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+
+	sort.Slice(r[:], func(i, j int) bool { return r[i].ID < r[j].ID })
+	require.Equal(t, "cl1", r[0].ID)
+	require.Equal(t, "cl2", r[1].ID)
+	require.Equal(t, "cl3", r[2].ID)
+}
+
+func TestStoredClientsNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	v, err := h.StoredClients()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredClientsClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+
+	v, err := h.StoredClients()
+	require.Empty(t, v)
+	require.Error(t, err)
+}
+
+func TestStoredSubscriptions(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	// populate with subscriptions
+	err := h.db.HSet(h.ctx, h.hKey(storage.SubscriptionKey), "sub1", &storage.Subscription{ID: "sub1", T: storage.SubscriptionKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.SubscriptionKey), "sub2", &storage.Subscription{ID: "sub2", T: storage.SubscriptionKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.SubscriptionKey), "sub3", &storage.Subscription{ID: "sub3", T: storage.SubscriptionKey}).Err()
+	require.NoError(t, err)
+
+	r, err := h.StoredSubscriptions()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	sort.Slice(r[:], func(i, j int) bool { return r[i].ID < r[j].ID })
+	require.Equal(t, "sub1", r[0].ID)
+	require.Equal(t, "sub2", r[1].ID)
+	require.Equal(t, "sub3", r[2].ID)
+}
+
+func TestStoredSubscriptionsNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	v, err := h.StoredSubscriptions()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredSubscriptionsClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+
+	v, err := h.StoredSubscriptions()
+	require.Empty(t, v)
+	require.Error(t, err)
+}
+
+func TestStoredRetainedMessages(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	// populate with messages
+	err := h.db.HSet(h.ctx, h.hKey(storage.RetainedKey), "m1", &storage.Message{ID: "m1", T: storage.RetainedKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.RetainedKey), "m2", &storage.Message{ID: "m2", T: storage.RetainedKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.RetainedKey), "m3", &storage.Message{ID: "m3", T: storage.RetainedKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.InflightKey), "i3", &storage.Message{ID: "i3", T: storage.InflightKey}).Err()
+	require.NoError(t, err)
+
+	r, err := h.StoredRetainedMessages()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	sort.Slice(r[:], func(i, j int) bool { return r[i].ID < r[j].ID })
+	require.Equal(t, "m1", r[0].ID)
+	require.Equal(t, "m2", r[1].ID)
+	require.Equal(t, "m3", r[2].ID)
+}
+
+func TestStoredRetainedMessagesNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	v, err := h.StoredRetainedMessages()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredRetainedMessagesClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+
+	v, err := h.StoredRetainedMessages()
+	require.Empty(t, v)
+	require.Error(t, err)
+}
+
+func TestStoredInflightMessages(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	// populate with messages
+	err := h.db.HSet(h.ctx, h.hKey(storage.InflightKey), "i1", &storage.Message{ID: "i1", T: storage.InflightKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.InflightKey), "i2", &storage.Message{ID: "i2", T: storage.InflightKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.InflightKey), "i3", &storage.Message{ID: "i3", T: storage.InflightKey}).Err()
+	require.NoError(t, err)
+
+	err = h.db.HSet(h.ctx, h.hKey(storage.RetainedKey), "m3", &storage.Message{ID: "m3", T: storage.RetainedKey}).Err()
+	require.NoError(t, err)
+
+	r, err := h.StoredInflightMessages()
+	require.NoError(t, err)
+	require.Len(t, r, 3)
+	sort.Slice(r[:], func(i, j int) bool { return r[i].ID < r[j].ID })
+	require.Equal(t, "i1", r[0].ID)
+	require.Equal(t, "i2", r[1].ID)
+	require.Equal(t, "i3", r[2].ID)
+}
+
+func TestStoredInflightMessagesNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	v, err := h.StoredInflightMessages()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredInflightMessagesClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+
+	v, err := h.StoredInflightMessages()
+	require.Empty(t, v)
+	require.Error(t, err)
+}
+
+func TestStoredSysInfo(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	defer teardown(t, h)
+
+	// populate with sys info
+	err := h.db.HSet(h.ctx, h.hKey(storage.SysInfoKey), storage.SysInfoKey,
+		&storage.SystemInfo{
+			ID: storage.SysInfoKey,
+			Info: system.Info{
+				Version: "2.0.0",
+			},
+			T: storage.SysInfoKey,
+		}).Err()
+	require.NoError(t, err)
+
+	r, err := h.StoredSysInfo()
+	require.NoError(t, err)
+	require.Equal(t, "2.0.0", r.Info.Version)
+}
+
+func TestStoredSysInfoNoDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	h.db = nil
+	v, err := h.StoredSysInfo()
+	require.Empty(t, v)
+	require.NoError(t, err)
+}
+
+func TestStoredSysInfoClosedDB(t *testing.T) {
+	s := miniredis.RunT(t)
+	defer s.Close()
+	h := newHook(t, s.Addr())
+	teardown(t, h)
+
+	v, err := h.StoredSysInfo()
+	require.Empty(t, v)
+	require.Error(t, err)
+}

hooks/storage/storage.go

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package storage
+
+import (
+	"encoding/json"
+	"errors"
+
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+)
+
+const (
+	SubscriptionKey = "SUB" // unique key to denote Subscriptions in a store
+	SysInfoKey      = "SYS" // unique key to denote server system information in a store
+	RetainedKey     = "RET" // unique key to denote retained messages in a store
+	InflightKey     = "IFM" // unique key to denote inflight messages in a store
+	ClientKey       = "CL"  // unique key to denote clients in a store
+)
+
+var (
+	// ErrDBFileNotOpen indicates that the file database (e.g. bolt/badger) wasn't open for reading.
+	ErrDBFileNotOpen = errors.New("db file not open")
+)
+
+// Client is a storable representation of an MQTT client.
+type Client struct {
+	Will            ClientWill       `json:"will"`            // will topic and payload data if applicable
+	Properties      ClientProperties `json:"properties"`      // the connect properties for the client
+	Username        []byte           `json:"username"`        // the username of the client
+	ID              string           `json:"id" storm:"id"`   // the client id / storage key
+	T               string           `json:"t"`               // the data type (client)
+	Remote          string           `json:"remote"`          // the remote address of the client
+	Listener        string           `json:"listener"`        // the listener the client connected on
+	ProtocolVersion byte             `json:"protocolVersion"` // mqtt protocol version of the client
+	Clean           bool             `json:"clean"`           // if the client requested a clean start/session
+}
+
+// ClientProperties contains a limited set of the mqtt v5 properties specific to a client connection.
+type ClientProperties struct {
+	AuthenticationData        []byte                 `json:"authenticationData"`
+	User                      []packets.UserProperty `json:"user"`
+	AuthenticationMethod      string                 `json:"authenticationMethod"`
+	SessionExpiryInterval     uint32                 `json:"sessionExpiryInterval"`
+	MaximumPacketSize         uint32                 `json:"maximumPacketSize"`
+	ReceiveMaximum            uint16                 `json:"receiveMaximum"`
+	TopicAliasMaximum         uint16                 `json:"topicAliasMaximum"`
+	SessionExpiryIntervalFlag bool                   `json:"sessionExpiryIntervalFlag"`
+	RequestProblemInfo        byte                   `json:"requestProblemInfo"`
+	RequestProblemInfoFlag    bool                   `json:"requestProblemInfoFlag"`
+	RequestResponseInfo       byte                   `json:"requestResponseInfo"`
+}
+
+// ClientWill contains a will message for a client, and limited mqtt v5 properties.
+type ClientWill struct {
+	Payload           []byte                 `json:"payload"`
+	User              []packets.UserProperty `json:"user"`
+	TopicName         string                 `json:"topicName"`
+	Flag              uint32                 `json:"flag"`
+	WillDelayInterval uint32                 `json:"willDelayInterval"`
+	Qos               byte                   `json:"qos"`
+	Retain            bool                   `json:"retain"`
+}
+
+// MarshalBinary encodes the values into a json string.
+func (d Client) MarshalBinary() (data []byte, err error) {
+	return json.Marshal(d)
+}
+
+// UnmarshalBinary decodes a json string into a struct.
+func (d *Client) UnmarshalBinary(data []byte) error {
+	if len(data) == 0 {
+		return nil
+	}
+	return json.Unmarshal(data, d)
+}
+
+// Message is a storable representation of an MQTT message (specifically publish).
+type Message struct {
+	Properties  MessageProperties   `json:"properties"`    // -
+	Payload     []byte              `json:"payload"`       // the message payload (if retained)
+	T           string              `json:"t"`             // the data type
+	ID          string              `json:"id" storm:"id"` // the storage key
+	Origin      string              `json:"origin"`        // the id of the client who sent the message
+	TopicName   string              `json:"topic_name"`    // the topic the message was sent to (if retained)
+	FixedHeader packets.FixedHeader `json:"fixedheader"`   // the header properties of the message
+	Created     int64               `json:"created"`       // the time the message was created in unixtime
+	Sent        int64               `json:"sent"`          // the last time the message was sent (for retries) in unixtime (if inflight)
+	PacketID    uint16              `json:"packet_id"`     // the unique id of the packet (if inflight)
+}
+
+// MessageProperties contains a limited subset of mqtt v5 properties specific to publish messages.
+type MessageProperties struct {
+	CorrelationData        []byte                 `json:"correlationData"`
+	SubscriptionIdentifier []int                  `json:"subscriptionIdentifier"`
+	User                   []packets.UserProperty `json:"user"`
+	ContentType            string                 `json:"contentType"`
+	ResponseTopic          string                 `json:"responseTopic"`
+	MessageExpiryInterval  uint32                 `json:"messageExpiry"`
+	TopicAlias             uint16                 `json:"topicAlias"`
+	PayloadFormat          byte                   `json:"payloadFormat"`
+	PayloadFormatFlag      bool                   `json:"payloadFormatFlag"`
+}
+
+// MarshalBinary encodes the values into a json string.
+func (d Message) MarshalBinary() (data []byte, err error) {
+	return json.Marshal(d)
+}
+
+// UnmarshalBinary decodes a json string into a struct.
+func (d *Message) UnmarshalBinary(data []byte) error {
+	if len(data) == 0 {
+		return nil
+	}
+	return json.Unmarshal(data, d)
+}
+
+// ToPacket converts a storage.Message to a standard packet.
+func (d *Message) ToPacket() packets.Packet {
+	pk := packets.Packet{
+		FixedHeader: d.FixedHeader,
+		PacketID:    d.PacketID,
+		TopicName:   d.TopicName,
+		Payload:     d.Payload,
+		Origin:      d.Origin,
+		Created:     d.Created,
+		Properties: packets.Properties{
+			PayloadFormat:          d.Properties.PayloadFormat,
+			PayloadFormatFlag:      d.Properties.PayloadFormatFlag,
+			MessageExpiryInterval:  d.Properties.MessageExpiryInterval,
+			ContentType:            d.Properties.ContentType,
+			ResponseTopic:          d.Properties.ResponseTopic,
+			CorrelationData:        d.Properties.CorrelationData,
+			SubscriptionIdentifier: d.Properties.SubscriptionIdentifier,
+			TopicAlias:             d.Properties.TopicAlias,
+			User:                   d.Properties.User,
+		},
+	}
+
+	// Return a deep copy of the packet data otherwise the slices will
+	// continue pointing at the values from the storage packet.
+	pk = pk.Copy(true)
+	pk.FixedHeader.Dup = d.FixedHeader.Dup
+
+	return pk
+}
+
+// Subscription is a storable representation of an MQTT subscription.
+type Subscription struct {
+	T                 string `json:"t"`
+	ID                string `json:"id" storm:"id"`
+	Client            string `json:"client"`
+	Filter            string `json:"filter"`
+	Identifier        int    `json:"identifier"`
+	RetainHandling    byte   `json:"retain_handling"`
+	Qos               byte   `json:"qos"`
+	RetainAsPublished bool   `json:"retain_as_pub"`
+	NoLocal           bool   `json:"no_local"`
+}
+
+// MarshalBinary encodes the values into a json string.
+func (d Subscription) MarshalBinary() (data []byte, err error) {
+	return json.Marshal(d)
+}
+
+// UnmarshalBinary decodes a json string into a struct.
+func (d *Subscription) UnmarshalBinary(data []byte) error {
+	if len(data) == 0 {
+		return nil
+	}
+	return json.Unmarshal(data, d)
+}
+
+// SystemInfo is a storable representation of the system information values.
+type SystemInfo struct {
+	system.Info        // embed the system info struct
+	T           string `json:"t"`             // the data type
+	ID          string `json:"id" storm:"id"` // the storage key
+}
+
+// MarshalBinary encodes the values into a json string.
+func (d SystemInfo) MarshalBinary() (data []byte, err error) {
+	return json.Marshal(d)
+}
+
+// UnmarshalBinary decodes a json string into a struct.
+func (d *SystemInfo) UnmarshalBinary(data []byte) error {
+	if len(data) == 0 {
+		return nil
+	}
+	return json.Unmarshal(data, d)
+}

hooks/storage/storage_test.go

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package storage
+
+import (
+	"testing"
+	"time"
+
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+	"github.com/stretchr/testify/require"
+)
+
+var (
+	clientStruct = Client{
+		ID:       "test",
+		T:        "client",
+		Remote:   "remote",
+		Listener: "listener",
+		Username: []byte("mochi"),
+		Clean:    true,
+		Properties: ClientProperties{
+			SessionExpiryInterval:     2,
+			SessionExpiryIntervalFlag: true,
+			AuthenticationMethod:      "a",
+			AuthenticationData:        []byte("test"),
+			RequestProblemInfo:        1,
+			RequestProblemInfoFlag:    true,
+			RequestResponseInfo:       1,
+			ReceiveMaximum:            128,
+			TopicAliasMaximum:         256,
+			User: []packets.UserProperty{
+				{Key: "k", Val: "v"},
+			},
+			MaximumPacketSize: 120,
+		},
+		Will: ClientWill{
+			Qos:               1,
+			Payload:           []byte("abc"),
+			TopicName:         "a/b/c",
+			Flag:              1,
+			Retain:            true,
+			WillDelayInterval: 2,
+			User: []packets.UserProperty{
+				{Key: "k2", Val: "v2"},
+			},
+		},
+	}
+	clientJSON = []byte(`{"will":{"payload":"YWJj","user":[{"k":"k2","v":"v2"}],"topicName":"a/b/c","flag":1,"willDelayInterval":2,"qos":1,"retain":true},"properties":{"authenticationData":"dGVzdA==","user":[{"k":"k","v":"v"}],"authenticationMethod":"a","sessionExpiryInterval":2,"maximumPacketSize":120,"receiveMaximum":128,"topicAliasMaximum":256,"sessionExpiryIntervalFlag":true,"requestProblemInfo":1,"requestProblemInfoFlag":true,"requestResponseInfo":1},"username":"bW9jaGk=","id":"test","t":"client","remote":"remote","listener":"listener","protocolVersion":0,"clean":true}`)
+
+	messageStruct = Message{
+		T:       "message",
+		Payload: []byte("payload"),
+		FixedHeader: packets.FixedHeader{
+			Remaining: 2,
+			Type:      3,
+			Qos:       1,
+			Dup:       true,
+			Retain:    true,
+		},
+		ID:        "id",
+		Origin:    "mochi",
+		TopicName: "topic",
+		Properties: MessageProperties{
+			PayloadFormat:          1,
+			PayloadFormatFlag:      true,
+			MessageExpiryInterval:  20,
+			ContentType:            "type",
+			ResponseTopic:          "a/b/r",
+			CorrelationData:        []byte("r"),
+			SubscriptionIdentifier: []int{1},
+			TopicAlias:             2,
+			User: []packets.UserProperty{
+				{Key: "k2", Val: "v2"},
+			},
+		},
+		Created:  time.Date(2019, time.September, 21, 1, 2, 3, 4, time.UTC).Unix(),
+		Sent:     time.Date(2019, time.September, 21, 1, 2, 3, 4, time.UTC).Unix(),
+		PacketID: 100,
+	}
+	messageJSON = []byte(`{"properties":{"correlationData":"cg==","subscriptionIdentifier":[1],"user":[{"k":"k2","v":"v2"}],"contentType":"type","responseTopic":"a/b/r","messageExpiry":20,"topicAlias":2,"payloadFormat":1,"payloadFormatFlag":true},"payload":"cGF5bG9hZA==","t":"message","id":"id","origin":"mochi","topic_name":"topic","fixedheader":{"remaining":2,"type":3,"qos":1,"dup":true,"retain":true},"created":1569027723,"sent":1569027723,"packet_id":100}`)
+
+	subscriptionStruct = Subscription{
+		T:      "subscription",
+		ID:     "id",
+		Client: "mochi",
+		Filter: "a/b/c",
+		Qos:    1,
+	}
+	subscriptionJSON = []byte(`{"t":"subscription","id":"id","client":"mochi","filter":"a/b/c","identifier":0,"retain_handling":0,"qos":1,"retain_as_pub":false,"no_local":false}`)
+
+	sysInfoStruct = SystemInfo{
+		T:  "info",
+		ID: "id",
+		Info: system.Info{
+			Version:          "2.0.0",
+			Started:          1,
+			Uptime:           2,
+			BytesReceived:    3,
+			BytesSent:        4,
+			ClientsConnected: 5,
+			ClientsMaximum:   7,
+			MessagesReceived: 10,
+			MessagesSent:     11,
+			MessagesDropped:  20,
+			PacketsReceived:  12,
+			PacketsSent:      13,
+			Retained:         15,
+			Inflight:         16,
+			InflightDropped:  17,
+		},
+	}
+	sysInfoJSON = []byte(`{"version":"2.0.0","started":1,"time":0,"uptime":2,"bytes_received":3,"bytes_sent":4,"clients_connected":5,"clients_disconnected":0,"clients_maximum":7,"clients_total":0,"messages_received":10,"messages_sent":11,"messages_dropped":20,"retained":15,"inflight":16,"inflight_dropped":17,"subscriptions":0,"packets_received":12,"packets_sent":13,"memory_alloc":0,"threads":0,"t":"info","id":"id"}`)
+)
+
+func TestClientMarshalBinary(t *testing.T) {
+	data, err := clientStruct.MarshalBinary()
+	require.NoError(t, err)
+	require.JSONEq(t, string(clientJSON), string(data))
+}
+
+func TestClientUnmarshalBinary(t *testing.T) {
+	d := clientStruct
+	err := d.UnmarshalBinary(clientJSON)
+	require.NoError(t, err)
+	require.Equal(t, clientStruct, d)
+}
+
+func TestClientUnmarshalBinaryEmpty(t *testing.T) {
+	d := Client{}
+	err := d.UnmarshalBinary([]byte{})
+	require.NoError(t, err)
+	require.Equal(t, Client{}, d)
+}
+
+func TestMessageMarshalBinary(t *testing.T) {
+	data, err := messageStruct.MarshalBinary()
+	require.NoError(t, err)
+	require.JSONEq(t, string(messageJSON), string(data))
+}
+
+func TestMessageUnmarshalBinary(t *testing.T) {
+	d := messageStruct
+	err := d.UnmarshalBinary(messageJSON)
+	require.NoError(t, err)
+	require.Equal(t, messageStruct, d)
+}
+
+func TestMessageUnmarshalBinaryEmpty(t *testing.T) {
+	d := Message{}
+	err := d.UnmarshalBinary([]byte{})
+	require.NoError(t, err)
+	require.Equal(t, Message{}, d)
+}
+
+func TestSubscriptionMarshalBinary(t *testing.T) {
+	data, err := subscriptionStruct.MarshalBinary()
+	require.NoError(t, err)
+	require.JSONEq(t, string(subscriptionJSON), string(data))
+}
+
+func TestSubscriptionUnmarshalBinary(t *testing.T) {
+	d := subscriptionStruct
+	err := d.UnmarshalBinary(subscriptionJSON)
+	require.NoError(t, err)
+	require.Equal(t, subscriptionStruct, d)
+}
+
+func TestSubscriptionUnmarshalBinaryEmpty(t *testing.T) {
+	d := Subscription{}
+	err := d.UnmarshalBinary([]byte{})
+	require.NoError(t, err)
+	require.Equal(t, Subscription{}, d)
+}
+
+func TestSysInfoMarshalBinary(t *testing.T) {
+	data, err := sysInfoStruct.MarshalBinary()
+	require.NoError(t, err)
+	require.JSONEq(t, string(sysInfoJSON), string(data))
+}
+
+func TestSysInfoUnmarshalBinary(t *testing.T) {
+	d := sysInfoStruct
+	err := d.UnmarshalBinary(sysInfoJSON)
+	require.NoError(t, err)
+	require.Equal(t, sysInfoStruct, d)
+}
+
+func TestSysInfoUnmarshalBinaryEmpty(t *testing.T) {
+	d := SystemInfo{}
+	err := d.UnmarshalBinary([]byte{})
+	require.NoError(t, err)
+	require.Equal(t, SystemInfo{}, d)
+}
+
+func TestMessageToPacket(t *testing.T) {
+	d := messageStruct
+	pk := d.ToPacket()
+
+	require.Equal(t, packets.Packet{
+		Payload: []byte("payload"),
+		FixedHeader: packets.FixedHeader{
+			Remaining: d.FixedHeader.Remaining,
+			Type:      d.FixedHeader.Type,
+			Qos:       d.FixedHeader.Qos,
+			Dup:       d.FixedHeader.Dup,
+			Retain:    d.FixedHeader.Retain,
+		},
+		Origin:    d.Origin,
+		TopicName: d.TopicName,
+		Properties: packets.Properties{
+			PayloadFormat:          d.Properties.PayloadFormat,
+			PayloadFormatFlag:      d.Properties.PayloadFormatFlag,
+			MessageExpiryInterval:  d.Properties.MessageExpiryInterval,
+			ContentType:            d.Properties.ContentType,
+			ResponseTopic:          d.Properties.ResponseTopic,
+			CorrelationData:        d.Properties.CorrelationData,
+			SubscriptionIdentifier: d.Properties.SubscriptionIdentifier,
+			TopicAlias:             d.Properties.TopicAlias,
+			User:                   d.Properties.User,
+		},
+		PacketID: 100,
+		Created:  d.Created,
+	}, pk)
+
+}

hooks_test.go

@@ -0,0 +1,667 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package mqtt
+
+import (
+	"errors"
+	"strconv"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/mochi-mqtt/server/v2/hooks/storage"
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/mochi-mqtt/server/v2/system"
+
+	"github.com/stretchr/testify/require"
+)
+
+type modifiedHookBase struct {
+	HookBase
+	err    error
+	fail   bool
+	failAt int
+}
+
+var errTestHook = errors.New("error")
+
+func (h *modifiedHookBase) ID() string {
+	return "modified"
+}
+
+func (h *modifiedHookBase) Init(config any) error {
+	if config != nil {
+		return errTestHook
+	}
+	return nil
+}
+
+func (h *modifiedHookBase) Provides(b byte) bool {
+	return true
+}
+
+func (h *modifiedHookBase) Stop() error {
+	if h.fail {
+		return errTestHook
+	}
+
+	return nil
+}
+
+func (h *modifiedHookBase) OnConnect(cl *Client, pk packets.Packet) error {
+	if h.fail {
+		return errTestHook
+	}
+
+	return nil
+}
+
+func (h *modifiedHookBase) OnConnectAuthenticate(cl *Client, pk packets.Packet) bool {
+	return true
+}
+
+func (h *modifiedHookBase) OnACLCheck(cl *Client, topic string, write bool) bool {
+	return true
+}
+
+func (h *modifiedHookBase) OnPublish(cl *Client, pk packets.Packet) (packets.Packet, error) {
+	if h.fail {
+		if h.err != nil {
+			return pk, h.err
+		}
+
+		return pk, errTestHook
+	}
+
+	return pk, nil
+}
+
+func (h *modifiedHookBase) OnPacketRead(cl *Client, pk packets.Packet) (packets.Packet, error) {
+	if h.fail {
+		if h.err != nil {
+			return pk, h.err
+		}
+
+		return pk, errTestHook
+	}
+
+	return pk, nil
+}
+
+func (h *modifiedHookBase) OnAuthPacket(cl *Client, pk packets.Packet) (packets.Packet, error) {
+	if h.fail {
+		if h.err != nil {
+			return pk, h.err
+		}
+
+		return pk, errTestHook
+	}
+
+	return pk, nil
+}
+
+func (h *modifiedHookBase) OnWill(cl *Client, will Will) (Will, error) {
+	if h.fail {
+		return will, errTestHook
+	}
+
+	return will, nil
+}
+
+func (h *modifiedHookBase) StoredClients() (v []storage.Client, err error) {
+	if h.fail || h.failAt == 1 {
+		return v, errTestHook
+	}
+
+	return []storage.Client{
+		{ID: "cl1"},
+		{ID: "cl2"},
+		{ID: "cl3"},
+	}, nil
+}
+
+func (h *modifiedHookBase) StoredSubscriptions() (v []storage.Subscription, err error) {
+	if h.fail || h.failAt == 2 {
+		return v, errTestHook
+	}
+
+	return []storage.Subscription{
+		{ID: "sub1"},
+		{ID: "sub2"},
+		{ID: "sub3"},
+	}, nil
+}
+
+func (h *modifiedHookBase) StoredRetainedMessages() (v []storage.Message, err error) {
+	if h.fail || h.failAt == 3 {
+		return v, errTestHook
+	}
+
+	return []storage.Message{
+		{ID: "r1"},
+		{ID: "r2"},
+		{ID: "r3"},
+	}, nil
+}
+
+func (h *modifiedHookBase) StoredInflightMessages() (v []storage.Message, err error) {
+	if h.fail || h.failAt == 4 {
+		return v, errTestHook
+	}
+
+	return []storage.Message{
+		{ID: "i1"},
+		{ID: "i2"},
+		{ID: "i3"},
+	}, nil
+}
+
+func (h *modifiedHookBase) StoredSysInfo() (v storage.SystemInfo, err error) {
+	if h.fail || h.failAt == 5 {
+		return v, errTestHook
+	}
+
+	return storage.SystemInfo{
+		Info: system.Info{
+			Version: "2.0.0",
+		},
+	}, nil
+}
+
+type providesCheckHook struct {
+	HookBase
+}
+
+func (h *providesCheckHook) Provides(b byte) bool {
+	return b == OnConnect
+}
+
+func TestHooksProvides(t *testing.T) {
+	h := new(Hooks)
+	err := h.Add(new(providesCheckHook), nil)
+	require.NoError(t, err)
+
+	err = h.Add(new(HookBase), nil)
+	require.NoError(t, err)
+
+	require.True(t, h.Provides(OnConnect, OnDisconnect))
+	require.False(t, h.Provides(OnDisconnect))
+}
+
+func TestHooksAddLenGetAll(t *testing.T) {
+	h := new(Hooks)
+	err := h.Add(new(HookBase), nil)
+	require.NoError(t, err)
+
+	err = h.Add(new(modifiedHookBase), nil)
+	require.NoError(t, err)
+
+	require.Equal(t, int64(2), atomic.LoadInt64(&h.qty))
+	require.Equal(t, int64(2), h.Len())
+
+	all := h.GetAll()
+	require.Equal(t, "base", all[0].ID())
+	require.Equal(t, "modified", all[1].ID())
+}
+
+func TestHooksAddInitFailure(t *testing.T) {
+	h := new(Hooks)
+	err := h.Add(new(modifiedHookBase), map[string]any{})
+	require.Error(t, err)
+	require.Equal(t, int64(0), atomic.LoadInt64(&h.qty))
+}
+
+func TestHooksStop(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	err := h.Add(new(HookBase), nil)
+	require.NoError(t, err)
+	require.Equal(t, int64(1), atomic.LoadInt64(&h.qty))
+	require.Equal(t, int64(1), h.Len())
+
+	h.Stop()
+}
+
+// coverage: also cover some empty functions
+func TestHooksNonReturns(t *testing.T) {
+	h := new(Hooks)
+	cl := new(Client)
+
+	for i := 0; i < 2; i++ {
+		t.Run("step-"+strconv.Itoa(i), func(t *testing.T) {
+			// on first iteration, check without hook methods
+			h.OnStarted()
+			h.OnStopped()
+			h.OnSysInfoTick(new(system.Info))
+			h.OnSessionEstablish(cl, packets.Packet{})
+			h.OnSessionEstablished(cl, packets.Packet{})
+			h.OnDisconnect(cl, nil, false)
+			h.OnPacketSent(cl, packets.Packet{}, []byte{})
+			h.OnPacketProcessed(cl, packets.Packet{}, nil)
+			h.OnSubscribed(cl, packets.Packet{}, []byte{1})
+			h.OnUnsubscribed(cl, packets.Packet{})
+			h.OnPublished(cl, packets.Packet{})
+			h.OnPublishDropped(cl, packets.Packet{})
+			h.OnRetainMessage(cl, packets.Packet{}, 0)
+			h.OnRetainPublished(cl, packets.Packet{})
+			h.OnQosPublish(cl, packets.Packet{}, time.Now().Unix(), 0)
+			h.OnQosComplete(cl, packets.Packet{})
+			h.OnQosDropped(cl, packets.Packet{})
+			h.OnPacketIDExhausted(cl, packets.Packet{})
+			h.OnWillSent(cl, packets.Packet{})
+			h.OnClientExpired(cl)
+			h.OnRetainedExpired("a/b/c")
+
+			// on second iteration, check added hook methods
+			err := h.Add(new(modifiedHookBase), nil)
+			require.NoError(t, err)
+		})
+	}
+}
+
+func TestHooksOnConnectAuthenticate(t *testing.T) {
+	h := new(Hooks)
+
+	ok := h.OnConnectAuthenticate(new(Client), packets.Packet{})
+	require.False(t, ok)
+
+	err := h.Add(new(modifiedHookBase), nil)
+	require.NoError(t, err)
+
+	ok = h.OnConnectAuthenticate(new(Client), packets.Packet{})
+	require.True(t, ok)
+}
+
+func TestHooksOnACLCheck(t *testing.T) {
+	h := new(Hooks)
+
+	ok := h.OnACLCheck(new(Client), "a/b/c", true)
+	require.False(t, ok)
+
+	err := h.Add(new(modifiedHookBase), nil)
+	require.NoError(t, err)
+
+	ok = h.OnACLCheck(new(Client), "a/b/c", true)
+	require.True(t, ok)
+}
+
+func TestHooksOnSubscribe(t *testing.T) {
+	h := new(Hooks)
+	err := h.Add(new(modifiedHookBase), nil)
+	require.NoError(t, err)
+
+	pki := packets.Packet{
+		Filters: packets.Subscriptions{
+			{Filter: "a/b/c", Qos: 1},
+		},
+	}
+	pk := h.OnSubscribe(new(Client), pki)
+	require.EqualValues(t, pk, pki)
+}
+
+func TestHooksOnSelectSubscribers(t *testing.T) {
+	h := new(Hooks)
+	err := h.Add(new(modifiedHookBase), nil)
+	require.NoError(t, err)
+
+	subs := &Subscribers{
+		Subscriptions: map[string]packets.Subscription{
+			"cl1": {Filter: "a/b/c"},
+		},
+	}
+
+	subs2 := h.OnSelectSubscribers(subs, packets.Packet{})
+	require.EqualValues(t, subs, subs2)
+}
+
+func TestHooksOnUnsubscribe(t *testing.T) {
+	h := new(Hooks)
+	err := h.Add(new(modifiedHookBase), nil)
+	require.NoError(t, err)
+
+	pki := packets.Packet{
+		Filters: packets.Subscriptions{
+			{Filter: "a/b/c", Qos: 1},
+		},
+	}
+
+	pk := h.OnUnsubscribe(new(Client), pki)
+	require.EqualValues(t, pk, pki)
+}
+
+func TestHooksOnPublish(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	hook := new(modifiedHookBase)
+	err := h.Add(hook, nil)
+	require.NoError(t, err)
+
+	pk, err := h.OnPublish(new(Client), packets.Packet{PacketID: 10})
+	require.NoError(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+
+	// coverage: failure
+	hook.fail = true
+	pk, err = h.OnPublish(new(Client), packets.Packet{PacketID: 10})
+	require.Error(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+
+	// coverage: reject packet
+	hook.err = packets.ErrRejectPacket
+	pk, err = h.OnPublish(new(Client), packets.Packet{PacketID: 10})
+	require.Error(t, err)
+	require.ErrorIs(t, err, packets.ErrRejectPacket)
+	require.Equal(t, uint16(10), pk.PacketID)
+}
+
+func TestHooksOnPacketRead(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	hook := new(modifiedHookBase)
+	err := h.Add(hook, nil)
+	require.NoError(t, err)
+
+	pk, err := h.OnPacketRead(new(Client), packets.Packet{PacketID: 10})
+	require.NoError(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+
+	// coverage: failure
+	hook.fail = true
+	pk, err = h.OnPacketRead(new(Client), packets.Packet{PacketID: 10})
+	require.NoError(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+
+	// coverage: reject packet
+	hook.err = packets.ErrRejectPacket
+	pk, err = h.OnPacketRead(new(Client), packets.Packet{PacketID: 10})
+	require.Error(t, err)
+	require.ErrorIs(t, err, packets.ErrRejectPacket)
+	require.Equal(t, uint16(10), pk.PacketID)
+}
+
+func TestHooksOnAuthPacket(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	hook := new(modifiedHookBase)
+	err := h.Add(hook, nil)
+	require.NoError(t, err)
+
+	pk, err := h.OnAuthPacket(new(Client), packets.Packet{PacketID: 10})
+	require.NoError(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+
+	hook.fail = true
+	pk, err = h.OnAuthPacket(new(Client), packets.Packet{PacketID: 10})
+	require.Error(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+}
+
+func TestHooksOnConnect(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	hook := new(modifiedHookBase)
+	err := h.Add(hook, nil)
+	require.NoError(t, err)
+
+	err = h.OnConnect(new(Client), packets.Packet{PacketID: 10})
+	require.NoError(t, err)
+
+	hook.fail = true
+	err = h.OnConnect(new(Client), packets.Packet{PacketID: 10})
+	require.Error(t, err)
+}
+
+func TestHooksOnPacketEncode(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	hook := new(modifiedHookBase)
+	err := h.Add(hook, nil)
+	require.NoError(t, err)
+
+	pk := h.OnPacketEncode(new(Client), packets.Packet{PacketID: 10})
+	require.Equal(t, uint16(10), pk.PacketID)
+}
+
+func TestHooksOnLWT(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	hook := new(modifiedHookBase)
+	err := h.Add(hook, nil)
+	require.NoError(t, err)
+
+	lwt := h.OnWill(new(Client), Will{TopicName: "a/b/c"})
+	require.Equal(t, "a/b/c", lwt.TopicName)
+
+	// coverage: fail lwt
+	hook.fail = true
+	lwt = h.OnWill(new(Client), Will{TopicName: "a/b/c"})
+	require.Equal(t, "a/b/c", lwt.TopicName)
+}
+
+func TestHooksStoredClients(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	v, err := h.StoredClients()
+	require.NoError(t, err)
+	require.Len(t, v, 0)
+
+	hook := new(modifiedHookBase)
+	err = h.Add(hook, nil)
+	require.NoError(t, err)
+
+	v, err = h.StoredClients()
+	require.NoError(t, err)
+	require.Len(t, v, 3)
+
+	hook.fail = true
+	v, err = h.StoredClients()
+	require.Error(t, err)
+	require.Len(t, v, 0)
+}
+
+func TestHooksStoredSubscriptions(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	v, err := h.StoredSubscriptions()
+	require.NoError(t, err)
+	require.Len(t, v, 0)
+
+	hook := new(modifiedHookBase)
+	err = h.Add(hook, nil)
+	require.NoError(t, err)
+
+	v, err = h.StoredSubscriptions()
+	require.NoError(t, err)
+	require.Len(t, v, 3)
+
+	hook.fail = true
+	v, err = h.StoredSubscriptions()
+	require.Error(t, err)
+	require.Len(t, v, 0)
+}
+
+func TestHooksStoredRetainedMessages(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	v, err := h.StoredRetainedMessages()
+	require.NoError(t, err)
+	require.Len(t, v, 0)
+
+	hook := new(modifiedHookBase)
+	err = h.Add(hook, nil)
+	require.NoError(t, err)
+
+	v, err = h.StoredRetainedMessages()
+	require.NoError(t, err)
+	require.Len(t, v, 3)
+
+	hook.fail = true
+	v, err = h.StoredRetainedMessages()
+	require.Error(t, err)
+	require.Len(t, v, 0)
+}
+
+func TestHooksStoredInflightMessages(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	v, err := h.StoredInflightMessages()
+	require.NoError(t, err)
+	require.Len(t, v, 0)
+
+	hook := new(modifiedHookBase)
+	err = h.Add(hook, nil)
+	require.NoError(t, err)
+
+	v, err = h.StoredInflightMessages()
+	require.NoError(t, err)
+	require.Len(t, v, 3)
+
+	hook.fail = true
+	v, err = h.StoredInflightMessages()
+	require.Error(t, err)
+	require.Len(t, v, 0)
+}
+
+func TestHooksStoredSysInfo(t *testing.T) {
+	h := new(Hooks)
+	h.Log = logger
+
+	v, err := h.StoredSysInfo()
+	require.NoError(t, err)
+	require.Equal(t, "", v.Info.Version)
+
+	hook := new(modifiedHookBase)
+	err = h.Add(hook, nil)
+	require.NoError(t, err)
+
+	v, err = h.StoredSysInfo()
+	require.NoError(t, err)
+	require.Equal(t, "2.0.0", v.Info.Version)
+
+	hook.fail = true
+	v, err = h.StoredSysInfo()
+	require.Error(t, err)
+	require.Equal(t, "", v.Info.Version)
+}
+
+func TestHookBaseID(t *testing.T) {
+	h := new(HookBase)
+	require.Equal(t, "base", h.ID())
+}
+
+func TestHookBaseProvidesNone(t *testing.T) {
+	h := new(HookBase)
+	require.False(t, h.Provides(OnConnect))
+	require.False(t, h.Provides(OnDisconnect))
+}
+
+func TestHookBaseInit(t *testing.T) {
+	h := new(HookBase)
+	require.Nil(t, h.Init(nil))
+}
+
+func TestHookBaseSetOpts(t *testing.T) {
+	h := new(HookBase)
+	h.SetOpts(logger, new(HookOptions))
+	require.NotNil(t, h.Log)
+	require.NotNil(t, h.Opts)
+}
+
+func TestHookBaseClose(t *testing.T) {
+	h := new(HookBase)
+	require.Nil(t, h.Stop())
+}
+
+func TestHookBaseOnConnectAuthenticate(t *testing.T) {
+	h := new(HookBase)
+	v := h.OnConnectAuthenticate(new(Client), packets.Packet{})
+	require.False(t, v)
+}
+
+func TestHookBaseOnACLCheck(t *testing.T) {
+	h := new(HookBase)
+	v := h.OnACLCheck(new(Client), "topic", true)
+	require.False(t, v)
+}
+
+func TestHookBaseOnConnect(t *testing.T) {
+	h := new(HookBase)
+	err := h.OnConnect(new(Client), packets.Packet{})
+	require.NoError(t, err)
+}
+
+func TestHookBaseOnPublish(t *testing.T) {
+	h := new(HookBase)
+	pk, err := h.OnPublish(new(Client), packets.Packet{PacketID: 10})
+	require.NoError(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+}
+
+func TestHookBaseOnPacketRead(t *testing.T) {
+	h := new(HookBase)
+	pk, err := h.OnPacketRead(new(Client), packets.Packet{PacketID: 10})
+	require.NoError(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+}
+
+func TestHookBaseOnAuthPacket(t *testing.T) {
+	h := new(HookBase)
+	pk, err := h.OnAuthPacket(new(Client), packets.Packet{PacketID: 10})
+	require.NoError(t, err)
+	require.Equal(t, uint16(10), pk.PacketID)
+}
+
+func TestHookBaseOnLWT(t *testing.T) {
+	h := new(HookBase)
+	lwt, err := h.OnWill(new(Client), Will{TopicName: "a/b/c"})
+	require.NoError(t, err)
+	require.Equal(t, "a/b/c", lwt.TopicName)
+}
+
+func TestHookBaseStoredClients(t *testing.T) {
+	h := new(HookBase)
+	v, err := h.StoredClients()
+	require.NoError(t, err)
+	require.Empty(t, v)
+}
+
+func TestHookBaseStoredSubscriptions(t *testing.T) {
+	h := new(HookBase)
+	v, err := h.StoredSubscriptions()
+	require.NoError(t, err)
+	require.Empty(t, v)
+}
+
+func TestHookBaseStoredInflightMessages(t *testing.T) {
+	h := new(HookBase)
+	v, err := h.StoredInflightMessages()
+	require.NoError(t, err)
+	require.Empty(t, v)
+}
+
+func TestHookBaseStoredRetainedMessages(t *testing.T) {
+	h := new(HookBase)
+	v, err := h.StoredRetainedMessages()
+	require.NoError(t, err)
+	require.Empty(t, v)
+}
+
+func TestHookBaseStoreSysInfo(t *testing.T) {
+	h := new(HookBase)
+	v, err := h.StoredSysInfo()
+	require.NoError(t, err)
+	require.Equal(t, "", v.Version)
+}

inflight.go

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package mqtt
+
+import (
+	"sort"
+	"sync"
+	"sync/atomic"
+
+	"github.com/mochi-mqtt/server/v2/packets"
+)
+
+// Inflight is a map of InflightMessage keyed on packet id.
+type Inflight struct {
+	sync.RWMutex
+	internal            map[uint16]packets.Packet // internal contains the inflight packets
+	receiveQuota        int32                     // remaining inbound qos quota for flow control
+	sendQuota           int32                     // remaining outbound qos quota for flow control
+	maximumReceiveQuota int32                     // maximum allowed receive quota
+	maximumSendQuota    int32                     // maximum allowed send quota
+}
+
+// NewInflights returns a new instance of an Inflight packets map.
+func NewInflights() *Inflight {
+	return &Inflight{
+		internal: map[uint16]packets.Packet{},
+	}
+}
+
+// Set adds or updates an inflight packet by packet id.
+func (i *Inflight) Set(m packets.Packet) bool {
+	i.Lock()
+	defer i.Unlock()
+
+	_, ok := i.internal[m.PacketID]
+	i.internal[m.PacketID] = m
+	return !ok
+}
+
+// Get returns an inflight packet by packet id.
+func (i *Inflight) Get(id uint16) (packets.Packet, bool) {
+	i.RLock()
+	defer i.RUnlock()
+
+	if m, ok := i.internal[id]; ok {
+		return m, true
+	}
+
+	return packets.Packet{}, false
+}
+
+// Len returns the size of the inflight messages map.
+func (i *Inflight) Len() int {
+	i.RLock()
+	defer i.RUnlock()
+	return len(i.internal)
+}
+
+// Clone returns a new instance of Inflight with the same message data.
+// This is used when transferring inflights from a taken-over session.
+func (i *Inflight) Clone() *Inflight {
+	c := NewInflights()
+	i.RLock()
+	defer i.RUnlock()
+	for k, v := range i.internal {
+		c.internal[k] = v
+	}
+	return c
+}
+
+// GetAll returns all the inflight messages.
+func (i *Inflight) GetAll(immediate bool) []packets.Packet {
+	i.RLock()
+	defer i.RUnlock()
+
+	m := []packets.Packet{}
+	for _, v := range i.internal {
+		if !immediate || (immediate && v.Expiry < 0) {
+			m = append(m, v)
+		}
+	}
+
+	sort.Slice(m, func(i, j int) bool {
+		return uint16(m[i].Created) < uint16(m[j].Created)
+	})
+
+	return m
+}
+
+// NextImmediate returns the next inflight packet which is indicated to be sent immediately.
+// This typically occurs when the quota has been exhausted, and we need to wait until new quota
+// is free to continue sending.
+func (i *Inflight) NextImmediate() (packets.Packet, bool) {
+	i.RLock()
+	defer i.RUnlock()
+
+	m := i.GetAll(true)
+	if len(m) > 0 {
+		return m[0], true
+	}
+
+	return packets.Packet{}, false
+}
+
+// Delete removes an in-flight message from the map. Returns true if the message existed.
+func (i *Inflight) Delete(id uint16) bool {
+	i.Lock()
+	defer i.Unlock()
+
+	_, ok := i.internal[id]
+	delete(i.internal, id)
+
+	return ok
+}
+
+// TakeRecieveQuota reduces the receive quota by 1.
+func (i *Inflight) DecreaseReceiveQuota() {
+	if atomic.LoadInt32(&i.receiveQuota) > 0 {
+		atomic.AddInt32(&i.receiveQuota, -1)
+	}
+}
+
+// TakeRecieveQuota increases the receive quota by 1.
+func (i *Inflight) IncreaseReceiveQuota() {
+	if atomic.LoadInt32(&i.receiveQuota) < atomic.LoadInt32(&i.maximumReceiveQuota) {
+		atomic.AddInt32(&i.receiveQuota, 1)
+	}
+}
+
+// ResetReceiveQuota resets the receive quota to the maximum allowed value.
+func (i *Inflight) ResetReceiveQuota(n int32) {
+	atomic.StoreInt32(&i.receiveQuota, n)
+	atomic.StoreInt32(&i.maximumReceiveQuota, n)
+}
+
+// DecreaseSendQuota reduces the send quota by 1.
+func (i *Inflight) DecreaseSendQuota() {
+	if atomic.LoadInt32(&i.sendQuota) > 0 {
+		atomic.AddInt32(&i.sendQuota, -1)
+	}
+}
+
+// IncreaseSendQuota increases the send quota by 1.
+func (i *Inflight) IncreaseSendQuota() {
+	if atomic.LoadInt32(&i.sendQuota) < atomic.LoadInt32(&i.maximumSendQuota) {
+		atomic.AddInt32(&i.sendQuota, 1)
+	}
+}
+
+// ResetSendQuota resets the send quota to the maximum allowed value.
+func (i *Inflight) ResetSendQuota(n int32) {
+	atomic.StoreInt32(&i.sendQuota, n)
+	atomic.StoreInt32(&i.maximumSendQuota, n)
+}

inflight_test.go

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package mqtt
+
+import (
+	"sync/atomic"
+	"testing"
+
+	"github.com/mochi-mqtt/server/v2/packets"
+	"github.com/stretchr/testify/require"
+)
+
+func TestInflightSet(t *testing.T) {
+	cl, _, _ := newTestClient()
+
+	r := cl.State.Inflight.Set(packets.Packet{PacketID: 1})
+	require.True(t, r)
+	require.NotNil(t, cl.State.Inflight.internal[1])
+	require.NotEqual(t, 0, cl.State.Inflight.internal[1].PacketID)
+
+	r = cl.State.Inflight.Set(packets.Packet{PacketID: 1})
+	require.False(t, r)
+}
+
+func TestInflightGet(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.State.Inflight.Set(packets.Packet{PacketID: 2})
+
+	msg, ok := cl.State.Inflight.Get(2)
+	require.True(t, ok)
+	require.NotEqual(t, 0, msg.PacketID)
+}
+
+func TestInflightGetAllAndImmediate(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.State.Inflight.Set(packets.Packet{PacketID: 1, Created: 1})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 2, Created: 2})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 3, Created: 3, Expiry: -1})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 4, Created: 4, Expiry: -1})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 5, Created: 5})
+
+	require.Equal(t, []packets.Packet{
+		{PacketID: 1, Created: 1},
+		{PacketID: 2, Created: 2},
+		{PacketID: 3, Created: 3, Expiry: -1},
+		{PacketID: 4, Created: 4, Expiry: -1},
+		{PacketID: 5, Created: 5},
+	}, cl.State.Inflight.GetAll(false))
+
+	require.Equal(t, []packets.Packet{
+		{PacketID: 3, Created: 3, Expiry: -1},
+		{PacketID: 4, Created: 4, Expiry: -1},
+	}, cl.State.Inflight.GetAll(true))
+}
+
+func TestInflightLen(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.State.Inflight.Set(packets.Packet{PacketID: 2})
+	require.Equal(t, 1, cl.State.Inflight.Len())
+}
+
+func TestInflightClone(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.State.Inflight.Set(packets.Packet{PacketID: 2})
+	require.Equal(t, 1, cl.State.Inflight.Len())
+
+	cloned := cl.State.Inflight.Clone()
+	require.NotNil(t, cloned)
+	require.NotSame(t, cloned, cl.State.Inflight)
+}
+
+func TestInflightDelete(t *testing.T) {
+	cl, _, _ := newTestClient()
+
+	cl.State.Inflight.Set(packets.Packet{PacketID: 3})
+	require.NotNil(t, cl.State.Inflight.internal[3])
+
+	r := cl.State.Inflight.Delete(3)
+	require.True(t, r)
+	require.Equal(t, uint16(0), cl.State.Inflight.internal[3].PacketID)
+
+	_, ok := cl.State.Inflight.Get(3)
+	require.False(t, ok)
+
+	r = cl.State.Inflight.Delete(3)
+	require.False(t, r)
+}
+
+func TestResetReceiveQuota(t *testing.T) {
+	i := NewInflights()
+	require.Equal(t, int32(0), atomic.LoadInt32(&i.maximumReceiveQuota))
+	require.Equal(t, int32(0), atomic.LoadInt32(&i.receiveQuota))
+	i.ResetReceiveQuota(6)
+	require.Equal(t, int32(6), atomic.LoadInt32(&i.maximumReceiveQuota))
+	require.Equal(t, int32(6), atomic.LoadInt32(&i.receiveQuota))
+}
+
+func TestReceiveQuota(t *testing.T) {
+	i := NewInflights()
+	i.receiveQuota = 4
+	i.maximumReceiveQuota = 5
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.maximumReceiveQuota))
+	require.Equal(t, int32(4), atomic.LoadInt32(&i.receiveQuota))
+
+	// Return 1
+	i.IncreaseReceiveQuota()
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.maximumReceiveQuota))
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.receiveQuota))
+
+	// Try to go over max limit
+	i.IncreaseReceiveQuota()
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.maximumReceiveQuota))
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.receiveQuota))
+
+	// Reset to max 1
+	i.ResetReceiveQuota(1)
+	require.Equal(t, int32(1), atomic.LoadInt32(&i.maximumReceiveQuota))
+	require.Equal(t, int32(1), atomic.LoadInt32(&i.receiveQuota))
+
+	// Take 1
+	i.DecreaseReceiveQuota()
+	require.Equal(t, int32(1), atomic.LoadInt32(&i.maximumReceiveQuota))
+	require.Equal(t, int32(0), atomic.LoadInt32(&i.receiveQuota))
+
+	// Try to go below zero
+	i.DecreaseReceiveQuota()
+	require.Equal(t, int32(1), atomic.LoadInt32(&i.maximumReceiveQuota))
+	require.Equal(t, int32(0), atomic.LoadInt32(&i.receiveQuota))
+}
+
+func TestResetSendQuota(t *testing.T) {
+	i := NewInflights()
+	require.Equal(t, int32(0), atomic.LoadInt32(&i.maximumSendQuota))
+	require.Equal(t, int32(0), atomic.LoadInt32(&i.sendQuota))
+	i.ResetSendQuota(6)
+	require.Equal(t, int32(6), atomic.LoadInt32(&i.maximumSendQuota))
+	require.Equal(t, int32(6), atomic.LoadInt32(&i.sendQuota))
+}
+
+func TestSendQuota(t *testing.T) {
+	i := NewInflights()
+	i.sendQuota = 4
+	i.maximumSendQuota = 5
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.maximumSendQuota))
+	require.Equal(t, int32(4), atomic.LoadInt32(&i.sendQuota))
+
+	// Return 1
+	i.IncreaseSendQuota()
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.maximumSendQuota))
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.sendQuota))
+
+	// Try to go over max limit
+	i.IncreaseSendQuota()
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.maximumSendQuota))
+	require.Equal(t, int32(5), atomic.LoadInt32(&i.sendQuota))
+
+	// Reset to max 1
+	i.ResetSendQuota(1)
+	require.Equal(t, int32(1), atomic.LoadInt32(&i.maximumSendQuota))
+	require.Equal(t, int32(1), atomic.LoadInt32(&i.sendQuota))
+
+	// Take 1
+	i.DecreaseSendQuota()
+	require.Equal(t, int32(1), atomic.LoadInt32(&i.maximumSendQuota))
+	require.Equal(t, int32(0), atomic.LoadInt32(&i.sendQuota))
+
+	// Try to go below zero
+	i.DecreaseSendQuota()
+	require.Equal(t, int32(1), atomic.LoadInt32(&i.maximumSendQuota))
+	require.Equal(t, int32(0), atomic.LoadInt32(&i.sendQuota))
+}
+
+func TestNextImmediate(t *testing.T) {
+	cl, _, _ := newTestClient()
+	cl.State.Inflight.Set(packets.Packet{PacketID: 1, Created: 1})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 2, Created: 2})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 3, Created: 3, Expiry: -1})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 4, Created: 4, Expiry: -1})
+	cl.State.Inflight.Set(packets.Packet{PacketID: 5, Created: 5})
+
+	pk, ok := cl.State.Inflight.NextImmediate()
+	require.True(t, ok)
+	require.Equal(t, packets.Packet{PacketID: 3, Created: 3, Expiry: -1}, pk)
+
+	r := cl.State.Inflight.Delete(3)
+	require.True(t, r)
+
+	pk, ok = cl.State.Inflight.NextImmediate()
+	require.True(t, ok)
+	require.Equal(t, packets.Packet{PacketID: 4, Created: 4, Expiry: -1}, pk)
+
+	r = cl.State.Inflight.Delete(4)
+	require.True(t, r)
+
+	_, ok = cl.State.Inflight.NextImmediate()
+	require.False(t, ok)
+}

listeners/http_healthcheck.go

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: Derek Duncan
+
+package listeners
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+const TypeHealthCheck = "healthcheck"
+
+// HTTPHealthCheck is a listener for providing an HTTP healthcheck endpoint.
+type HTTPHealthCheck struct {
+	sync.RWMutex
+	id      string       // the internal id of the listener
+	address string       // the network address to bind to
+	config  Config       // configuration values for the listener
+	listen  *http.Server // the http server
+	end     uint32       // ensure the close methods are only called once
+}
+
+// NewHTTPHealthCheck initializes and returns a new HTTP listener, listening on an address.
+func NewHTTPHealthCheck(config Config) *HTTPHealthCheck {
+	return &HTTPHealthCheck{
+		id:      config.ID,
+		address: config.Address,
+		config:  config,
+	}
+}
+
+// ID returns the id of the listener.
+func (l *HTTPHealthCheck) ID() string {
+	return l.id
+}
+
+// Address returns the address of the listener.
+func (l *HTTPHealthCheck) Address() string {
+	return l.address
+}
+
+// Protocol returns the address of the listener.
+func (l *HTTPHealthCheck) Protocol() string {
+	if l.listen != nil && l.listen.TLSConfig != nil {
+		return "https"
+	}
+
+	return "http"
+}
+
+// Init initializes the listener.
+func (l *HTTPHealthCheck) Init(_ *slog.Logger) error {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/healthcheck", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			w.WriteHeader(http.StatusMethodNotAllowed)
+		}
+	})
+	l.listen = &http.Server{
+		ReadTimeout:  5 * time.Second,
+		WriteTimeout: 5 * time.Second,
+		Addr:         l.address,
+		Handler:      mux,
+	}
+
+	if l.config.TLSConfig != nil {
+		l.listen.TLSConfig = l.config.TLSConfig
+	}
+
+	return nil
+}
+
+// Serve starts listening for new connections and serving responses.
+func (l *HTTPHealthCheck) Serve(establish EstablishFn) {
+	if l.listen.TLSConfig != nil {
+		_ = l.listen.ListenAndServeTLS("", "")
+	} else {
+		_ = l.listen.ListenAndServe()
+	}
+}
+
+// Close closes the listener and any client connections.
+func (l *HTTPHealthCheck) Close(closeClients CloseFn) {
+	l.Lock()
+	defer l.Unlock()
+
+	if atomic.CompareAndSwapUint32(&l.end, 0, 1) {
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		_ = l.listen.Shutdown(ctx)
+	}
+
+	closeClients(l.id)
+}

listeners/http_healthcheck_test.go

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: Derek Duncan
+
+package listeners
+
+import (
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewHTTPHealthCheck(t *testing.T) {
+	l := NewHTTPHealthCheck(basicConfig)
+	require.Equal(t, basicConfig.ID, l.id)
+	require.Equal(t, basicConfig.Address, l.address)
+}
+
+func TestHTTPHealthCheckID(t *testing.T) {
+	l := NewHTTPHealthCheck(basicConfig)
+	require.Equal(t, basicConfig.ID, l.ID())
+}
+
+func TestHTTPHealthCheckAddress(t *testing.T) {
+	l := NewHTTPHealthCheck(basicConfig)
+	require.Equal(t, basicConfig.Address, l.Address())
+}
+
+func TestHTTPHealthCheckProtocol(t *testing.T) {
+	l := NewHTTPHealthCheck(basicConfig)
+	require.Equal(t, "http", l.Protocol())
+}
+
+func TestHTTPHealthCheckTLSProtocol(t *testing.T) {
+	l := NewHTTPHealthCheck(tlsConfig)
+	_ = l.Init(logger)
+	require.Equal(t, "https", l.Protocol())
+}
+
+func TestHTTPHealthCheckInit(t *testing.T) {
+	l := NewHTTPHealthCheck(basicConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	require.NotNil(t, l.listen)
+	require.Equal(t, basicConfig.Address, l.listen.Addr)
+}
+
+func TestHTTPHealthCheckServeAndClose(t *testing.T) {
+	// setup http stats listener
+	l := NewHTTPHealthCheck(basicConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+
+	// call healthcheck
+	resp, err := http.Get("http://localhost" + testAddr + "/healthcheck")
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+
+	defer resp.Body.Close()
+	_, err = io.ReadAll(resp.Body)
+	require.NoError(t, err)
+
+	// ensure listening is closed
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+
+	require.Equal(t, true, closed)
+
+	_, err = http.Get("http://localhost/healthcheck" + testAddr + "/healthcheck")
+	require.Error(t, err)
+	<-o
+}
+
+func TestHTTPHealthCheckServeAndCloseMethodNotAllowed(t *testing.T) {
+	// setup http stats listener
+	l := NewHTTPHealthCheck(basicConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+
+	// make disallowed method type http request
+	resp, err := http.Post("http://localhost"+testAddr+"/healthcheck", "application/json", http.NoBody)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+
+	defer resp.Body.Close()
+	_, err = io.ReadAll(resp.Body)
+	require.NoError(t, err)
+
+	// ensure listening is closed
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+
+	require.Equal(t, true, closed)
+
+	_, err = http.Post("http://localhost/healthcheck"+testAddr+"/healthcheck", "application/json", http.NoBody)
+	require.Error(t, err)
+	<-o
+}
+
+func TestHTTPHealthCheckServeTLSAndClose(t *testing.T) {
+	l := NewHTTPHealthCheck(tlsConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+	l.Close(MockCloser)
+}

listeners/http_sysinfo.go

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/mochi-mqtt/server/v2/system"
+)
+
+const TypeSysInfo = "sysinfo"
+
+// HTTPStats is a listener for presenting the server $SYS stats on a JSON http endpoint.
+type HTTPStats struct {
+	sync.RWMutex
+	id      string       // the internal id of the listener
+	address string       // the network address to bind to
+	config  Config       // configuration values for the listener
+	listen  *http.Server // the http server
+	sysInfo *system.Info // pointers to the server data
+	log     *slog.Logger // server logger
+	end     uint32       // ensure the close methods are only called once
+}
+
+// NewHTTPStats initializes and returns a new HTTP listener, listening on an address.
+func NewHTTPStats(config Config, sysInfo *system.Info) *HTTPStats {
+	return &HTTPStats{
+		sysInfo: sysInfo,
+		id:      config.ID,
+		address: config.Address,
+		config:  config,
+	}
+}
+
+// ID returns the id of the listener.
+func (l *HTTPStats) ID() string {
+	return l.id
+}
+
+// Address returns the address of the listener.
+func (l *HTTPStats) Address() string {
+	return l.address
+}
+
+// Protocol returns the address of the listener.
+func (l *HTTPStats) Protocol() string {
+	if l.listen != nil && l.listen.TLSConfig != nil {
+		return "https"
+	}
+
+	return "http"
+}
+
+// Init initializes the listener.
+func (l *HTTPStats) Init(log *slog.Logger) error {
+	l.log = log
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", l.jsonHandler)
+	l.listen = &http.Server{
+		ReadTimeout:  5 * time.Second,
+		WriteTimeout: 5 * time.Second,
+		Addr:         l.address,
+		Handler:      mux,
+	}
+
+	if l.config.TLSConfig != nil {
+		l.listen.TLSConfig = l.config.TLSConfig
+	}
+
+	return nil
+}
+
+// Serve starts listening for new connections and serving responses.
+func (l *HTTPStats) Serve(establish EstablishFn) {
+
+	var err error
+	if l.listen.TLSConfig != nil {
+		err = l.listen.ListenAndServeTLS("", "")
+	} else {
+		err = l.listen.ListenAndServe()
+	}
+
+	// After the listener has been shutdown, no need to print the http.ErrServerClosed error.
+	if err != nil && atomic.LoadUint32(&l.end) == 0 {
+		l.log.Error("failed to serve.", "error", err, "listener", l.id)
+	}
+}
+
+// Close closes the listener and any client connections.
+func (l *HTTPStats) Close(closeClients CloseFn) {
+	l.Lock()
+	defer l.Unlock()
+
+	if atomic.CompareAndSwapUint32(&l.end, 0, 1) {
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		_ = l.listen.Shutdown(ctx)
+	}
+
+	closeClients(l.id)
+}
+
+// jsonHandler is an HTTP handler which outputs the $SYS stats as JSON.
+func (l *HTTPStats) jsonHandler(w http.ResponseWriter, req *http.Request) {
+	info := *l.sysInfo.Clone()
+
+	out, err := json.MarshalIndent(info, "", "\t")
+	if err != nil {
+		_, _ = io.WriteString(w, err.Error())
+	}
+
+	_, _ = w.Write(out)
+}

listeners/http_sysinfo_test.go

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/mochi-mqtt/server/v2/system"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewHTTPStats(t *testing.T) {
+	l := NewHTTPStats(basicConfig, nil)
+	require.Equal(t, "t1", l.id)
+	require.Equal(t, testAddr, l.address)
+}
+
+func TestHTTPStatsID(t *testing.T) {
+	l := NewHTTPStats(basicConfig, nil)
+	require.Equal(t, "t1", l.ID())
+}
+
+func TestHTTPStatsAddress(t *testing.T) {
+	l := NewHTTPStats(basicConfig, nil)
+	require.Equal(t, testAddr, l.Address())
+}
+
+func TestHTTPStatsProtocol(t *testing.T) {
+	l := NewHTTPStats(basicConfig, nil)
+	require.Equal(t, "http", l.Protocol())
+}
+
+func TestHTTPStatsTLSProtocol(t *testing.T) {
+	l := NewHTTPStats(tlsConfig, nil)
+	_ = l.Init(logger)
+	require.Equal(t, "https", l.Protocol())
+}
+
+func TestHTTPStatsInit(t *testing.T) {
+	sysInfo := new(system.Info)
+	l := NewHTTPStats(basicConfig, sysInfo)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	require.NotNil(t, l.sysInfo)
+	require.Equal(t, sysInfo, l.sysInfo)
+	require.NotNil(t, l.listen)
+	require.Equal(t, testAddr, l.listen.Addr)
+}
+
+func TestHTTPStatsServeAndClose(t *testing.T) {
+	sysInfo := &system.Info{
+		Version: "test",
+	}
+
+	// setup http stats listener
+	l := NewHTTPStats(basicConfig, sysInfo)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+
+	// get body from stats address
+	resp, err := http.Get("http://localhost" + testAddr)
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+
+	defer resp.Body.Close()
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+
+	// decode body from json and check data
+	v := new(system.Info)
+	err = json.Unmarshal(body, v)
+	require.NoError(t, err)
+	require.Equal(t, "test", v.Version)
+
+	// ensure listening is closed
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+
+	require.Equal(t, true, closed)
+
+	_, err = http.Get("http://localhost" + testAddr)
+	require.Error(t, err)
+	<-o
+}
+
+func TestHTTPStatsServeTLSAndClose(t *testing.T) {
+	sysInfo := &system.Info{
+		Version: "test",
+	}
+
+	l := NewHTTPStats(tlsConfig, sysInfo)
+
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+	l.Close(MockCloser)
+}
+
+func TestHTTPStatsFailedToServe(t *testing.T) {
+	sysInfo := &system.Info{
+		Version: "test",
+	}
+
+	// setup http stats listener
+	config := basicConfig
+	config.Address = "wrong_addr"
+	l := NewHTTPStats(config, sysInfo)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	<-o
+	// ensure listening is closed
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+	require.Equal(t, true, closed)
+}

listeners/listeners.go

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"crypto/tls"
+	"net"
+	"sync"
+
+	"log/slog"
+)
+
+// Config contains configuration values for a listener.
+type Config struct {
+	Type    string
+	ID      string
+	Address string
+	// TLSConfig is a tls.Config configuration to be used with the listener. See examples folder for basic and mutual-tls use.
+	TLSConfig *tls.Config
+}
+
+// EstablishFn is a callback function for establishing new clients.
+type EstablishFn func(id string, c net.Conn) error
+
+// CloseFn is a callback function for closing all listener clients.
+type CloseFn func(id string)
+
+// Listener is an interface for network listeners. A network listener listens
+// for incoming client connections and adds them to the server.
+type Listener interface {
+	Init(*slog.Logger) error // open the network address
+	Serve(EstablishFn)       // starting actively listening for new connections
+	ID() string              // return the id of the listener
+	Address() string         // the address of the listener
+	Protocol() string        // the protocol in use by the listener
+	Close(CloseFn)           // stop and close the listener
+}
+
+// Listeners contains the network listeners for the broker.
+type Listeners struct {
+	ClientsWg sync.WaitGroup      // a waitgroup that waits for all clients in all listeners to finish.
+	internal  map[string]Listener // a map of active listeners.
+	sync.RWMutex
+}
+
+// New returns a new instance of Listeners.
+func New() *Listeners {
+	return &Listeners{
+		internal: map[string]Listener{},
+	}
+}
+
+// Add adds a new listener to the listeners map, keyed on id.
+func (l *Listeners) Add(val Listener) {
+	l.Lock()
+	defer l.Unlock()
+	l.internal[val.ID()] = val
+}
+
+// Get returns the value of a listener if it exists.
+func (l *Listeners) Get(id string) (Listener, bool) {
+	l.RLock()
+	defer l.RUnlock()
+	val, ok := l.internal[id]
+	return val, ok
+}
+
+// Len returns the length of the listeners map.
+func (l *Listeners) Len() int {
+	l.RLock()
+	defer l.RUnlock()
+	return len(l.internal)
+}
+
+// Delete removes a listener from the internal map.
+func (l *Listeners) Delete(id string) {
+	l.Lock()
+	defer l.Unlock()
+	delete(l.internal, id)
+}
+
+// Serve starts a listener serving from the internal map.
+func (l *Listeners) Serve(id string, establisher EstablishFn) {
+	l.RLock()
+	defer l.RUnlock()
+	listener := l.internal[id]
+
+	go func(e EstablishFn) {
+		listener.Serve(e)
+	}(establisher)
+}
+
+// ServeAll starts all listeners serving from the internal map.
+func (l *Listeners) ServeAll(establisher EstablishFn) {
+	l.RLock()
+	i := 0
+	ids := make([]string, len(l.internal))
+	for id := range l.internal {
+		ids[i] = id
+		i++
+	}
+	l.RUnlock()
+
+	for _, id := range ids {
+		l.Serve(id, establisher)
+	}
+}
+
+// Close stops a listener from the internal map.
+func (l *Listeners) Close(id string, closer CloseFn) {
+	l.RLock()
+	defer l.RUnlock()
+	if listener, ok := l.internal[id]; ok {
+		listener.Close(closer)
+	}
+}
+
+// CloseAll iterates and closes all registered listeners.
+func (l *Listeners) CloseAll(closer CloseFn) {
+	l.RLock()
+	i := 0
+	ids := make([]string, len(l.internal))
+	for id := range l.internal {
+		ids[i] = id
+		i++
+	}
+	l.RUnlock()
+
+	for _, id := range ids {
+		l.Close(id, closer)
+	}
+	l.ClientsWg.Wait()
+}

listeners/listeners_test.go

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"crypto/tls"
+	"log"
+	"os"
+	"testing"
+	"time"
+
+	"log/slog"
+
+	"github.com/stretchr/testify/require"
+)
+
+const testAddr = ":22222"
+
+var (
+	basicConfig = Config{ID: "t1", Address: testAddr}
+	tlsConfig   = Config{ID: "t1", Address: testAddr, TLSConfig: tlsConfigBasic}
+
+	logger = slog.New(slog.NewTextHandler(os.Stdout, nil))
+
+	testCertificate = []byte(`-----BEGIN CERTIFICATE-----
+MIIB/zCCAWgCCQDm3jV+lSF1AzANBgkqhkiG9w0BAQsFADBEMQswCQYDVQQGEwJB
+VTETMBEGA1UECAwKU29tZS1TdGF0ZTERMA8GA1UECgwITW9jaGkgQ28xDTALBgNV
+BAsMBE1RVFQwHhcNMjAwMTA0MjAzMzQyWhcNMjEwMTAzMjAzMzQyWjBEMQswCQYD
+VQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTERMA8GA1UECgwITW9jaGkgQ28x
+DTALBgNVBAsMBE1RVFQwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKz2bUz3
+AOymssVLuvSOEbQ/sF8C/Ill8nRTd7sX9WBIxHJZf+gVn8lQ4BTQ0NchLDRIlpbi
+OuZgktpd6ba8sIfVM4jbVprctky5tGsyHRFwL/GAycCtKwvuXkvcwSwLvB8b29EI
+MLQ/3vNnYuC3eZ4qqxlODJgRsfQ7mUNB8zkLAgMBAAEwDQYJKoZIhvcNAQELBQAD
+gYEAiMoKnQaD0F/J332arGvcmtbHmF2XZp/rGy3dooPug8+OPUSAJY9vTfxJwOsQ
+qN1EcI+kIgrGxzA3VRfVYV8gr7IX+fUYfVCaPGcDCfPvo/Ihu757afJRVvpafWgy
+zSpDZYu6C62h3KSzMJxffDjy7/2t8oYbTzkLSamsHJJjLZw=
+-----END CERTIFICATE-----`)
+
+	testPrivateKey = []byte(`-----BEGIN RSA PRIVATE KEY-----
+MIICXAIBAAKBgQCs9m1M9wDsprLFS7r0jhG0P7BfAvyJZfJ0U3e7F/VgSMRyWX/o
+FZ/JUOAU0NDXISw0SJaW4jrmYJLaXem2vLCH1TOI21aa3LZMubRrMh0RcC/xgMnA
+rSsL7l5L3MEsC7wfG9vRCDC0P97zZ2Lgt3meKqsZTgyYEbH0O5lDQfM5CwIDAQAB
+AoGBAKlmVVirFqmw/qhDaqD4wBg0xI3Zw/Lh+Vu7ICoK5hVeT6DbTW3GOBAY+M8K
+UXBSGhQ+/9ZZTmyyK0JZ9nw2RAG3lONU6wS41pZhB7F4siatZfP/JJfU6p+ohe8m
+n22hTw4brY/8E/tjuki9T5e2GeiUPBhjbdECkkVXMYBPKDZhAkEA5h/b/HBcsIZZ
+mL2d3dyWkXR/IxngQa4NH3124M8MfBqCYXPLgD7RDI+3oT/uVe+N0vu6+7CSMVx6
+INM67CuE0QJBAMBpKW54cfMsMya3CM1BfdPEBzDT5kTMqxJ7ez164PHv9CJCnL0Z
+AuWgM/p2WNbAF1yHNxw1eEfNbUWwVX2yhxsCQEtnMQvcPWLSAtWbe/jQaL2scGQt
+/F9JCp/A2oz7Cto3TXVlHc8dxh3ZkY/ShOO/pLb3KOODjcOCy7mpvOrZr6ECQH32
+WoFPqImhrfryaHi3H0C7XFnC30S7GGOJIy0kfI7mn9St9x50eUkKj/yv7YjpSGHy
+w0lcV9npyleNEOqxLXECQBL3VRGCfZfhfFpL8z+5+HPKXw6FxWr+p5h8o3CZ6Yi3
+OJVN3Mfo6mbz34wswrEdMXn25MzAwbhFQvCVpPZrFwc=
+-----END RSA PRIVATE KEY-----`)
+
+	tlsConfigBasic *tls.Config
+)
+
+func init() {
+	cert, err := tls.X509KeyPair(testCertificate, testPrivateKey)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Basic TLS Config
+	tlsConfigBasic = &tls.Config{
+		MinVersion:   tls.VersionTLS12,
+		Certificates: []tls.Certificate{cert},
+	}
+	tlsConfig.TLSConfig = tlsConfigBasic
+}
+
+func TestNew(t *testing.T) {
+	l := New()
+	require.NotNil(t, l.internal)
+}
+
+func TestAddListener(t *testing.T) {
+	l := New()
+	l.Add(NewMockListener("t1", testAddr))
+	require.Contains(t, l.internal, "t1")
+}
+
+func TestGetListener(t *testing.T) {
+	l := New()
+	l.Add(NewMockListener("t1", testAddr))
+	l.Add(NewMockListener("t2", testAddr))
+	require.Contains(t, l.internal, "t1")
+	require.Contains(t, l.internal, "t2")
+
+	g, ok := l.Get("t1")
+	require.True(t, ok)
+	require.Equal(t, g.ID(), "t1")
+}
+
+func TestLenListener(t *testing.T) {
+	l := New()
+	l.Add(NewMockListener("t1", testAddr))
+	l.Add(NewMockListener("t2", testAddr))
+	require.Contains(t, l.internal, "t1")
+	require.Contains(t, l.internal, "t2")
+	require.Equal(t, 2, l.Len())
+}
+
+func TestDeleteListener(t *testing.T) {
+	l := New()
+	l.Add(NewMockListener("t1", testAddr))
+	require.Contains(t, l.internal, "t1")
+	l.Delete("t1")
+	_, ok := l.Get("t1")
+	require.False(t, ok)
+	require.Nil(t, l.internal["t1"])
+}
+
+func TestServeListener(t *testing.T) {
+	l := New()
+	l.Add(NewMockListener("t1", testAddr))
+	l.Serve("t1", MockEstablisher)
+	time.Sleep(time.Millisecond)
+	require.True(t, l.internal["t1"].(*MockListener).IsServing())
+
+	l.Close("t1", MockCloser)
+	require.False(t, l.internal["t1"].(*MockListener).IsServing())
+}
+
+func TestServeAllListeners(t *testing.T) {
+	l := New()
+	l.Add(NewMockListener("t1", testAddr))
+	l.Add(NewMockListener("t2", testAddr))
+	l.Add(NewMockListener("t3", testAddr))
+	l.ServeAll(MockEstablisher)
+	time.Sleep(time.Millisecond)
+
+	require.True(t, l.internal["t1"].(*MockListener).IsServing())
+	require.True(t, l.internal["t2"].(*MockListener).IsServing())
+	require.True(t, l.internal["t3"].(*MockListener).IsServing())
+
+	l.Close("t1", MockCloser)
+	l.Close("t2", MockCloser)
+	l.Close("t3", MockCloser)
+
+	require.False(t, l.internal["t1"].(*MockListener).IsServing())
+	require.False(t, l.internal["t2"].(*MockListener).IsServing())
+	require.False(t, l.internal["t3"].(*MockListener).IsServing())
+}
+
+func TestCloseListener(t *testing.T) {
+	l := New()
+	mocked := NewMockListener("t1", testAddr)
+	l.Add(mocked)
+	l.Serve("t1", MockEstablisher)
+	time.Sleep(time.Millisecond)
+	var closed bool
+	l.Close("t1", func(id string) {
+		closed = true
+	})
+	require.True(t, closed)
+}
+
+func TestCloseAllListeners(t *testing.T) {
+	l := New()
+	l.Add(NewMockListener("t1", testAddr))
+	l.Add(NewMockListener("t2", testAddr))
+	l.Add(NewMockListener("t3", testAddr))
+	l.ServeAll(MockEstablisher)
+	time.Sleep(time.Millisecond)
+	require.True(t, l.internal["t1"].(*MockListener).IsServing())
+	require.True(t, l.internal["t2"].(*MockListener).IsServing())
+	require.True(t, l.internal["t3"].(*MockListener).IsServing())
+
+	closed := make(map[string]bool)
+	l.CloseAll(func(id string) {
+		closed[id] = true
+	})
+	require.Contains(t, closed, "t1")
+	require.Contains(t, closed, "t2")
+	require.Contains(t, closed, "t3")
+	require.True(t, closed["t1"])
+	require.True(t, closed["t2"])
+	require.True(t, closed["t3"])
+}

listeners/mock.go

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"fmt"
+	"net"
+	"sync"
+
+	"log/slog"
+)
+
+const TypeMock = "mock"
+
+// MockEstablisher is a function signature which can be used in testing.
+func MockEstablisher(id string, c net.Conn) error {
+	return nil
+}
+
+// MockCloser is a function signature which can be used in testing.
+func MockCloser(id string) {}
+
+// MockListener is a mock listener for establishing client connections.
+type MockListener struct {
+	sync.RWMutex
+	id        string    // the id of the listener
+	address   string    // the network address the listener binds to
+	Config    *Config   // configuration for the listener
+	done      chan bool // indicate the listener is done
+	Serving   bool      // indicate the listener is serving
+	Listening bool      // indiciate the listener is listening
+	ErrListen bool      // throw an error on listen
+}
+
+// NewMockListener returns a new instance of MockListener.
+func NewMockListener(id, address string) *MockListener {
+	return &MockListener{
+		id:      id,
+		address: address,
+		done:    make(chan bool),
+	}
+}
+
+// Serve serves the mock listener.
+func (l *MockListener) Serve(establisher EstablishFn) {
+	l.Lock()
+	l.Serving = true
+	l.Unlock()
+
+	for range l.done {
+		return
+	}
+}
+
+// Init initializes the listener.
+func (l *MockListener) Init(log *slog.Logger) error {
+	if l.ErrListen {
+		return fmt.Errorf("listen failure")
+	}
+
+	l.Lock()
+	defer l.Unlock()
+	l.Listening = true
+	return nil
+}
+
+// ID returns the id of the mock listener.
+func (l *MockListener) ID() string {
+	return l.id
+}
+
+// Address returns the address of the listener.
+func (l *MockListener) Address() string {
+	return l.address
+}
+
+// Protocol returns the address of the listener.
+func (l *MockListener) Protocol() string {
+	return "mock"
+}
+
+// Close closes the mock listener.
+func (l *MockListener) Close(closer CloseFn) {
+	l.Lock()
+	defer l.Unlock()
+	l.Serving = false
+	closer(l.id)
+	close(l.done)
+}
+
+// IsServing indicates whether the mock listener is serving.
+func (l *MockListener) IsServing() bool {
+	l.Lock()
+	defer l.Unlock()
+	return l.Serving
+}
+
+// IsListening indicates whether the mock listener is listening.
+func (l *MockListener) IsListening() bool {
+	l.Lock()
+	defer l.Unlock()
+	return l.Listening
+}

listeners/mock_test.go

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"net"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestMockEstablisher(t *testing.T) {
+	_, w := net.Pipe()
+	err := MockEstablisher("t1", w)
+	require.NoError(t, err)
+	_ = w.Close()
+}
+
+func TestNewMockListener(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	require.Equal(t, "t1", mocked.id)
+	require.Equal(t, testAddr, mocked.address)
+}
+func TestMockListenerID(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	require.Equal(t, "t1", mocked.ID())
+}
+
+func TestMockListenerAddress(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	require.Equal(t, testAddr, mocked.Address())
+}
+func TestMockListenerProtocol(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	require.Equal(t, "mock", mocked.Protocol())
+}
+
+func TestNewMockListenerIsListening(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	require.Equal(t, false, mocked.IsListening())
+}
+
+func TestNewMockListenerIsServing(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	require.Equal(t, false, mocked.IsServing())
+}
+
+func TestNewMockListenerInit(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	require.Equal(t, "t1", mocked.id)
+	require.Equal(t, testAddr, mocked.address)
+
+	require.Equal(t, false, mocked.IsListening())
+	err := mocked.Init(nil)
+	require.NoError(t, err)
+	require.Equal(t, true, mocked.IsListening())
+}
+
+func TestNewMockListenerInitFailure(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	mocked.ErrListen = true
+	err := mocked.Init(nil)
+	require.Error(t, err)
+}
+
+func TestMockListenerServe(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	require.Equal(t, false, mocked.IsServing())
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		mocked.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond) // easy non-channel wait for start of serving
+	require.Equal(t, true, mocked.IsServing())
+
+	var closed bool
+	mocked.Close(func(id string) {
+		closed = true
+	})
+	require.Equal(t, true, closed)
+	<-o
+
+	_ = mocked.Init(nil)
+}
+
+func TestMockListenerClose(t *testing.T) {
+	mocked := NewMockListener("t1", testAddr)
+	var closed bool
+	mocked.Close(func(id string) {
+		closed = true
+	})
+	require.Equal(t, true, closed)
+}

listeners/net.go

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: Jeroen Rinzema
+
+package listeners
+
+import (
+	"net"
+	"sync"
+	"sync/atomic"
+
+	"log/slog"
+)
+
+// Net is a listener for establishing client connections on basic TCP protocol.
+type Net struct { // [MQTT-4.2.0-1]
+	mu       sync.Mutex
+	listener net.Listener // a net.Listener which will listen for new clients
+	id       string       // the internal id of the listener
+	log      *slog.Logger // server logger
+	end      uint32       // ensure the close methods are only called once
+}
+
+// NewNet initialises and returns a listener serving incoming connections on the given net.Listener
+func NewNet(id string, listener net.Listener) *Net {
+	return &Net{
+		id:       id,
+		listener: listener,
+	}
+}
+
+// ID returns the id of the listener.
+func (l *Net) ID() string {
+	return l.id
+}
+
+// Address returns the address of the listener.
+func (l *Net) Address() string {
+	return l.listener.Addr().String()
+}
+
+// Protocol returns the network of the listener.
+func (l *Net) Protocol() string {
+	return l.listener.Addr().Network()
+}
+
+// Init initializes the listener.
+func (l *Net) Init(log *slog.Logger) error {
+	l.log = log
+	return nil
+}
+
+// Serve starts waiting for new TCP connections, and calls the establish
+// connection callback for any received.
+func (l *Net) Serve(establish EstablishFn) {
+	for {
+		if atomic.LoadUint32(&l.end) == 1 {
+			return
+		}
+
+		conn, err := l.listener.Accept()
+		if err != nil {
+			return
+		}
+
+		if atomic.LoadUint32(&l.end) == 0 {
+			go func() {
+				err = establish(l.id, conn)
+				if err != nil {
+					l.log.Warn("", "error", err)
+				}
+			}()
+		}
+	}
+}
+
+// Close closes the listener and any client connections.
+func (l *Net) Close(closeClients CloseFn) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	if atomic.CompareAndSwapUint32(&l.end, 0, 1) {
+		closeClients(l.id)
+	}
+
+	if l.listener != nil {
+		err := l.listener.Close()
+		if err != nil {
+			return
+		}
+	}
+}

listeners/net_test.go

@@ -0,0 +1,105 @@
+package listeners
+
+import (
+	"errors"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewNet(t *testing.T) {
+	n, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	l := NewNet("t1", n)
+	require.Equal(t, "t1", l.id)
+}
+
+func TestNetID(t *testing.T) {
+	n, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	l := NewNet("t1", n)
+	require.Equal(t, "t1", l.ID())
+}
+
+func TestNetAddress(t *testing.T) {
+	n, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	l := NewNet("t1", n)
+	require.Equal(t, n.Addr().String(), l.Address())
+}
+
+func TestNetProtocol(t *testing.T) {
+	n, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	l := NewNet("t1", n)
+	require.Equal(t, "tcp", l.Protocol())
+}
+
+func TestNetInit(t *testing.T) {
+	n, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	l := NewNet("t1", n)
+	err = l.Init(logger)
+	l.Close(MockCloser)
+	require.NoError(t, err)
+}
+
+func TestNetServeAndClose(t *testing.T) {
+	n, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	l := NewNet("t1", n)
+	err = l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+
+	require.True(t, closed)
+	<-o
+
+	l.Close(MockCloser)      // coverage: close closed
+	l.Serve(MockEstablisher) // coverage: serve closed
+}
+
+func TestNetEstablishThenEnd(t *testing.T) {
+	n, err := net.Listen("tcp", "127.0.0.1:0")
+	require.NoError(t, err)
+
+	l := NewNet("t1", n)
+	err = l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	established := make(chan bool)
+	go func() {
+		l.Serve(func(id string, c net.Conn) error {
+			established <- true
+			return errors.New("ending") // return an error to exit immediately
+		})
+		o <- true
+	}()
+
+	time.Sleep(time.Millisecond)
+	_, _ = net.Dial("tcp", n.Addr().String())
+	require.Equal(t, true, <-established)
+	l.Close(MockCloser)
+	<-o
+}

listeners/tcp.go

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"crypto/tls"
+	"net"
+	"sync"
+	"sync/atomic"
+
+	"log/slog"
+)
+
+const TypeTCP = "tcp"
+
+// TCP is a listener for establishing client connections on basic TCP protocol.
+type TCP struct { // [MQTT-4.2.0-1]
+	sync.RWMutex
+	id      string       // the internal id of the listener
+	address string       // the network address to bind to
+	listen  net.Listener // a net.Listener which will listen for new clients
+	config  Config       // configuration values for the listener
+	log     *slog.Logger // server logger
+	end     uint32       // ensure the close methods are only called once
+}
+
+// NewTCP initializes and returns a new TCP listener, listening on an address.
+func NewTCP(config Config) *TCP {
+	return &TCP{
+		id:      config.ID,
+		address: config.Address,
+		config:  config,
+	}
+}
+
+// ID returns the id of the listener.
+func (l *TCP) ID() string {
+	return l.id
+}
+
+// Address returns the address of the listener.
+func (l *TCP) Address() string {
+	if l.listen != nil {
+		return l.listen.Addr().String()
+	}
+	return l.address
+}
+
+// Protocol returns the address of the listener.
+func (l *TCP) Protocol() string {
+	return "tcp"
+}
+
+// Init initializes the listener.
+func (l *TCP) Init(log *slog.Logger) error {
+	l.log = log
+
+	var err error
+	if l.config.TLSConfig != nil {
+		l.listen, err = tls.Listen("tcp", l.address, l.config.TLSConfig)
+	} else {
+		l.listen, err = net.Listen("tcp", l.address)
+	}
+
+	return err
+}
+
+// Serve starts waiting for new TCP connections, and calls the establish
+// connection callback for any received.
+func (l *TCP) Serve(establish EstablishFn) {
+	for {
+		if atomic.LoadUint32(&l.end) == 1 {
+			return
+		}
+
+		conn, err := l.listen.Accept()
+		if err != nil {
+			return
+		}
+
+		if atomic.LoadUint32(&l.end) == 0 {
+			go func() {
+				err = establish(l.id, conn)
+				if err != nil {
+					l.log.Warn("", "error", err)
+				}
+			}()
+		}
+	}
+}
+
+// Close closes the listener and any client connections.
+func (l *TCP) Close(closeClients CloseFn) {
+	l.Lock()
+	defer l.Unlock()
+
+	if atomic.CompareAndSwapUint32(&l.end, 0, 1) {
+		closeClients(l.id)
+	}
+
+	if l.listen != nil {
+		err := l.listen.Close()
+		if err != nil {
+			return
+		}
+	}
+}

listeners/tcp_test.go

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"errors"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewTCP(t *testing.T) {
+	l := NewTCP(basicConfig)
+	require.Equal(t, "t1", l.id)
+	require.Equal(t, testAddr, l.address)
+}
+
+func TestTCPID(t *testing.T) {
+	l := NewTCP(basicConfig)
+	require.Equal(t, "t1", l.ID())
+}
+
+func TestTCPAddress(t *testing.T) {
+	l := NewTCP(basicConfig)
+	require.Equal(t, testAddr, l.Address())
+}
+
+func TestTCPProtocol(t *testing.T) {
+	l := NewTCP(basicConfig)
+	require.Equal(t, "tcp", l.Protocol())
+}
+
+func TestTCPProtocolTLS(t *testing.T) {
+	l := NewTCP(tlsConfig)
+	_ = l.Init(logger)
+	defer l.listen.Close()
+	require.Equal(t, "tcp", l.Protocol())
+}
+
+func TestTCPInit(t *testing.T) {
+	l := NewTCP(basicConfig)
+	err := l.Init(logger)
+	l.Close(MockCloser)
+	require.NoError(t, err)
+
+	l2 := NewTCP(tlsConfig)
+	err = l2.Init(logger)
+	l2.Close(MockCloser)
+	require.NoError(t, err)
+	require.NotNil(t, l2.config.TLSConfig)
+}
+
+func TestTCPServeAndClose(t *testing.T) {
+	l := NewTCP(basicConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+
+	require.True(t, closed)
+	<-o
+
+	l.Close(MockCloser)      // coverage: close closed
+	l.Serve(MockEstablisher) // coverage: serve closed
+}
+
+func TestTCPServeTLSAndClose(t *testing.T) {
+	l := NewTCP(tlsConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+
+	require.Equal(t, true, closed)
+	<-o
+}
+
+func TestTCPEstablishThenEnd(t *testing.T) {
+	l := NewTCP(basicConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	established := make(chan bool)
+	go func() {
+		l.Serve(func(id string, c net.Conn) error {
+			established <- true
+			return errors.New("ending") // return an error to exit immediately
+		})
+		o <- true
+	}()
+
+	time.Sleep(time.Millisecond)
+	_, _ = net.Dial("tcp", l.listen.Addr().String())
+	require.Equal(t, true, <-established)
+	l.Close(MockCloser)
+	<-o
+}

listeners/unixsock.go

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: jason@zgwit.com
+
+package listeners
+
+import (
+	"net"
+	"os"
+	"sync"
+	"sync/atomic"
+
+	"log/slog"
+)
+
+const TypeUnix = "unix"
+
+// UnixSock is a listener for establishing client connections on basic UnixSock protocol.
+type UnixSock struct {
+	sync.RWMutex
+	id      string       // the internal id of the listener.
+	address string       // the network address to bind to.
+	config  Config       // configuration values for the listener
+	listen  net.Listener // a net.Listener which will listen for new clients.
+	log     *slog.Logger // server logger
+	end     uint32       // ensure the close methods are only called once.
+}
+
+// NewUnixSock initializes and returns a new UnixSock listener, listening on an address.
+func NewUnixSock(config Config) *UnixSock {
+	return &UnixSock{
+		id:      config.ID,
+		address: config.Address,
+		config:  config,
+	}
+}
+
+// ID returns the id of the listener.
+func (l *UnixSock) ID() string {
+	return l.id
+}
+
+// Address returns the address of the listener.
+func (l *UnixSock) Address() string {
+	return l.address
+}
+
+// Protocol returns the address of the listener.
+func (l *UnixSock) Protocol() string {
+	return "unix"
+}
+
+// Init initializes the listener.
+func (l *UnixSock) Init(log *slog.Logger) error {
+	l.log = log
+
+	var err error
+	_ = os.Remove(l.address)
+	l.listen, err = net.Listen("unix", l.address)
+	return err
+}
+
+// Serve starts waiting for new UnixSock connections, and calls the establish
+// connection callback for any received.
+func (l *UnixSock) Serve(establish EstablishFn) {
+	for {
+		if atomic.LoadUint32(&l.end) == 1 {
+			return
+		}
+
+		conn, err := l.listen.Accept()
+		if err != nil {
+			return
+		}
+
+		if atomic.LoadUint32(&l.end) == 0 {
+			go func() {
+				err = establish(l.id, conn)
+				if err != nil {
+					l.log.Warn("", "error", err)
+				}
+			}()
+		}
+	}
+}
+
+// Close closes the listener and any client connections.
+func (l *UnixSock) Close(closeClients CloseFn) {
+	l.Lock()
+	defer l.Unlock()
+
+	if atomic.CompareAndSwapUint32(&l.end, 0, 1) {
+		closeClients(l.id)
+	}
+
+	if l.listen != nil {
+		err := l.listen.Close()
+		if err != nil {
+			return
+		}
+	}
+}

listeners/unixsock_test.go

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: jason@zgwit.com
+
+package listeners
+
+import (
+	"errors"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+const testUnixAddr = "mochi.sock"
+
+var (
+	unixConfig = Config{ID: "t1", Address: testUnixAddr}
+)
+
+func TestNewUnixSock(t *testing.T) {
+	l := NewUnixSock(unixConfig)
+	require.Equal(t, "t1", l.id)
+	require.Equal(t, testUnixAddr, l.address)
+}
+
+func TestUnixSockID(t *testing.T) {
+	l := NewUnixSock(unixConfig)
+	require.Equal(t, "t1", l.ID())
+}
+
+func TestUnixSockAddress(t *testing.T) {
+	l := NewUnixSock(unixConfig)
+	require.Equal(t, testUnixAddr, l.Address())
+}
+
+func TestUnixSockProtocol(t *testing.T) {
+	l := NewUnixSock(unixConfig)
+	require.Equal(t, "unix", l.Protocol())
+}
+
+func TestUnixSockInit(t *testing.T) {
+	l := NewUnixSock(unixConfig)
+	err := l.Init(logger)
+	l.Close(MockCloser)
+	require.NoError(t, err)
+
+	t2Config := unixConfig
+	t2Config.ID = "t2"
+	l2 := NewUnixSock(t2Config)
+	err = l2.Init(logger)
+	l2.Close(MockCloser)
+	require.NoError(t, err)
+}
+
+func TestUnixSockServeAndClose(t *testing.T) {
+	l := NewUnixSock(unixConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+
+	require.True(t, closed)
+	<-o
+
+	l.Close(MockCloser)      // coverage: close closed
+	l.Serve(MockEstablisher) // coverage: serve closed
+}
+
+func TestUnixSockEstablishThenEnd(t *testing.T) {
+	l := NewUnixSock(unixConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	established := make(chan bool)
+	go func() {
+		l.Serve(func(id string, c net.Conn) error {
+			established <- true
+			return errors.New("ending") // return an error to exit immediately
+		})
+		o <- true
+	}()
+
+	time.Sleep(time.Millisecond)
+	_, _ = net.Dial("unix", l.listen.Addr().String())
+	require.Equal(t, true, <-established)
+	l.Close(MockCloser)
+	<-o
+}

listeners/websocket.go

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net"
+	"net/http"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"log/slog"
+
+	"github.com/gorilla/websocket"
+)
+
+const TypeWS = "ws"
+
+var (
+	// ErrInvalidMessage indicates that a message payload was not valid.
+	ErrInvalidMessage = errors.New("message type not binary")
+)
+
+// Websocket is a listener for establishing websocket connections.
+type Websocket struct { // [MQTT-4.2.0-1]
+	sync.RWMutex
+	id        string              // the internal id of the listener
+	address   string              // the network address to bind to
+	config    Config              // configuration values for the listener
+	listen    *http.Server        // a http server for serving websocket connections
+	log       *slog.Logger        // server logger
+	establish EstablishFn         // the server's establish connection handler
+	upgrader  *websocket.Upgrader //  upgrade the incoming http/tcp connection to a websocket compliant connection.
+	end       uint32              // ensure the close methods are only called once
+}
+
+// NewWebsocket initializes and returns a new Websocket listener, listening on an address.
+func NewWebsocket(config Config) *Websocket {
+	return &Websocket{
+		id:      config.ID,
+		address: config.Address,
+		config:  config,
+		upgrader: &websocket.Upgrader{
+			Subprotocols: []string{"mqtt"},
+			CheckOrigin: func(r *http.Request) bool {
+				return true
+			},
+		},
+	}
+}
+
+// ID returns the id of the listener.
+func (l *Websocket) ID() string {
+	return l.id
+}
+
+// Address returns the address of the listener.
+func (l *Websocket) Address() string {
+	return l.address
+}
+
+// Protocol returns the address of the listener.
+func (l *Websocket) Protocol() string {
+	if l.config.TLSConfig != nil {
+		return "wss"
+	}
+
+	return "ws"
+}
+
+// Init initializes the listener.
+func (l *Websocket) Init(log *slog.Logger) error {
+	l.log = log
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/", l.handler)
+	l.listen = &http.Server{
+		Addr:         l.address,
+		Handler:      mux,
+		TLSConfig:    l.config.TLSConfig,
+		ReadTimeout:  60 * time.Second,
+		WriteTimeout: 60 * time.Second,
+	}
+
+	return nil
+}
+
+// handler upgrades and handles an incoming websocket connection.
+func (l *Websocket) handler(w http.ResponseWriter, r *http.Request) {
+	c, err := l.upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		return
+	}
+	defer c.Close()
+
+	err = l.establish(l.id, &wsConn{Conn: c.UnderlyingConn(), c: c})
+	if err != nil {
+		l.log.Warn("", "error", err)
+	}
+}
+
+// Serve starts waiting for new Websocket connections, and calls the connection
+// establishment callback for any received.
+func (l *Websocket) Serve(establish EstablishFn) {
+	var err error
+	l.establish = establish
+
+	if l.listen.TLSConfig != nil {
+		err = l.listen.ListenAndServeTLS("", "")
+	} else {
+		err = l.listen.ListenAndServe()
+	}
+
+	// After the listener has been shutdown, no need to print the http.ErrServerClosed error.
+	if err != nil && atomic.LoadUint32(&l.end) == 0 {
+		l.log.Error("failed to serve.", "error", err, "listener", l.id)
+	}
+}
+
+// Close closes the listener and any client connections.
+func (l *Websocket) Close(closeClients CloseFn) {
+	l.Lock()
+	defer l.Unlock()
+
+	if atomic.CompareAndSwapUint32(&l.end, 0, 1) {
+		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		_ = l.listen.Shutdown(ctx)
+	}
+
+	closeClients(l.id)
+}
+
+// wsConn is a websocket connection which satisfies the net.Conn interface.
+type wsConn struct {
+	net.Conn
+	c *websocket.Conn
+
+	// reader for the current message (can be nil)
+	r io.Reader
+}
+
+// Read reads the next span of bytes from the websocket connection and returns the number of bytes read.
+func (ws *wsConn) Read(p []byte) (int, error) {
+	if ws.r == nil {
+		op, r, err := ws.c.NextReader()
+		if err != nil {
+			return 0, err
+		}
+
+		if op != websocket.BinaryMessage {
+			err = ErrInvalidMessage
+			return 0, err
+		}
+
+		ws.r = r
+	}
+
+	var n int
+	for {
+		// buffer is full, return what we've read so far
+		if n == len(p) {
+			return n, nil
+		}
+
+		br, err := ws.r.Read(p[n:])
+		n += br
+		if err != nil {
+			// when ANY error occurs, we consider this the end of the current message (either because it really is, via
+			// io.EOF, or because something bad happened, in which case we want to drop the remainder)
+			ws.r = nil
+
+			if errors.Is(err, io.EOF) {
+				err = nil
+			}
+			return n, err
+		}
+	}
+}
+
+// Write writes bytes to the websocket connection.
+func (ws *wsConn) Write(p []byte) (int, error) {
+	err := ws.c.WriteMessage(websocket.BinaryMessage, p)
+	if err != nil {
+		return 0, err
+	}
+
+	return len(p), nil
+}
+
+// Close signals the underlying websocket conn to close.
+func (ws *wsConn) Close() error {
+	return ws.Conn.Close()
+}

listeners/websocket_test.go

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package listeners
+
+import (
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewWebsocket(t *testing.T) {
+	l := NewWebsocket(basicConfig)
+	require.Equal(t, "t1", l.id)
+	require.Equal(t, testAddr, l.address)
+}
+
+func TestWebsocketID(t *testing.T) {
+	l := NewWebsocket(basicConfig)
+	require.Equal(t, "t1", l.ID())
+}
+
+func TestWebsocketAddress(t *testing.T) {
+	l := NewWebsocket(basicConfig)
+	require.Equal(t, testAddr, l.Address())
+}
+
+func TestWebsocketProtocol(t *testing.T) {
+	l := NewWebsocket(basicConfig)
+	require.Equal(t, "ws", l.Protocol())
+}
+
+func TestWebsocketProtocolTLS(t *testing.T) {
+	l := NewWebsocket(tlsConfig)
+	require.Equal(t, "wss", l.Protocol())
+}
+
+func TestWebsocketInit(t *testing.T) {
+	l := NewWebsocket(basicConfig)
+	require.Nil(t, l.listen)
+	err := l.Init(logger)
+	require.NoError(t, err)
+	require.NotNil(t, l.listen)
+}
+
+func TestWebsocketServeAndClose(t *testing.T) {
+	l := NewWebsocket(basicConfig)
+	_ = l.Init(logger)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+
+	require.True(t, closed)
+	<-o
+}
+
+func TestWebsocketServeTLSAndClose(t *testing.T) {
+	l := NewWebsocket(tlsConfig)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	time.Sleep(time.Millisecond)
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+	require.Equal(t, true, closed)
+	<-o
+}
+
+func TestWebsocketFailedToServe(t *testing.T) {
+	config := tlsConfig
+	config.Address = "wrong_addr"
+	l := NewWebsocket(config)
+	err := l.Init(logger)
+	require.NoError(t, err)
+
+	o := make(chan bool)
+	go func(o chan bool) {
+		l.Serve(MockEstablisher)
+		o <- true
+	}(o)
+
+	<-o
+	var closed bool
+	l.Close(func(id string) {
+		closed = true
+	})
+	require.Equal(t, true, closed)
+}
+
+func TestWebsocketUpgrade(t *testing.T) {
+	l := NewWebsocket(basicConfig)
+	_ = l.Init(logger)
+
+	e := make(chan bool)
+	l.establish = func(id string, c net.Conn) error {
+		e <- true
+		return nil
+	}
+
+	s := httptest.NewServer(http.HandlerFunc(l.handler))
+	ws, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(s.URL, "http"), nil)
+	require.NoError(t, err)
+	require.Equal(t, true, <-e)
+
+	s.Close()
+	_ = ws.Close()
+}
+
+func TestWebsocketConnectionReads(t *testing.T) {
+	l := NewWebsocket(basicConfig)
+	_ = l.Init(nil)
+
+	recv := make(chan []byte)
+	l.establish = func(id string, c net.Conn) error {
+		var out []byte
+		for {
+			buf := make([]byte, 2048)
+			n, err := c.Read(buf)
+			require.NoError(t, err)
+			out = append(out, buf[:n]...)
+			if n < 2048 {
+				break
+			}
+		}
+
+		recv <- out
+		return nil
+	}
+
+	s := httptest.NewServer(http.HandlerFunc(l.handler))
+	ws, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(s.URL, "http"), nil)
+	require.NoError(t, err)
+
+	pkt := make([]byte, 3000) // make sure this is >2048
+	for i := 0; i < len(pkt); i++ {
+		pkt[i] = byte(i % 100)
+	}
+
+	err = ws.WriteMessage(websocket.BinaryMessage, pkt)
+	require.NoError(t, err)
+
+	got := <-recv
+	require.Equal(t, 3000, len(got))
+	require.Equal(t, pkt, got)
+
+	s.Close()
+	_ = ws.Close()
+}

mempool/bufpool.go

@@ -0,0 +1,81 @@
+package mempool
+
+import (
+	"bytes"
+	"sync"
+)
+
+var bufPool = NewBuffer(0)
+
+// GetBuffer takes a Buffer from the default buffer pool
+func GetBuffer() *bytes.Buffer { return bufPool.Get() }
+
+// PutBuffer returns Buffer to the default buffer pool
+func PutBuffer(x *bytes.Buffer) { bufPool.Put(x) }
+
+type BufferPool interface {
+	Get() *bytes.Buffer
+	Put(x *bytes.Buffer)
+}
+
+// NewBuffer returns a buffer pool. The max specify the max capacity of the Buffer the pool will
+// return. If the Buffer becoomes large than max, it will no longer be returned to the pool. If
+// max <= 0, no limit will be enforced.
+func NewBuffer(max int) BufferPool {
+	if max > 0 {
+		return newBufferWithCap(max)
+	}
+
+	return newBuffer()
+}
+
+// Buffer is a Buffer pool.
+type Buffer struct {
+	pool *sync.Pool
+}
+
+func newBuffer() *Buffer {
+	return &Buffer{
+		pool: &sync.Pool{
+			New: func() any { return new(bytes.Buffer) },
+		},
+	}
+}
+
+// Get a Buffer from the pool.
+func (b *Buffer) Get() *bytes.Buffer {
+	return b.pool.Get().(*bytes.Buffer)
+}
+
+// Put the Buffer back into pool. It resets the Buffer for reuse.
+func (b *Buffer) Put(x *bytes.Buffer) {
+	x.Reset()
+	b.pool.Put(x)
+}
+
+// BufferWithCap is a Buffer pool that
+type BufferWithCap struct {
+	bp  *Buffer
+	max int
+}
+
+func newBufferWithCap(max int) *BufferWithCap {
+	return &BufferWithCap{
+		bp:  newBuffer(),
+		max: max,
+	}
+}
+
+// Get a Buffer from the pool.
+func (b *BufferWithCap) Get() *bytes.Buffer {
+	return b.bp.Get()
+}
+
+// Put the Buffer back into the pool if the capacity doesn't exceed the limit. It resets the Buffer
+// for reuse.
+func (b *BufferWithCap) Put(x *bytes.Buffer) {
+	if x.Cap() > b.max {
+		return
+	}
+	b.bp.Put(x)
+}

mempool/bufpool_test.go

@@ -0,0 +1,96 @@
+package mempool
+
+import (
+	"bytes"
+	"reflect"
+	"runtime/debug"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewBuffer(t *testing.T) {
+	defer debug.SetGCPercent(debug.SetGCPercent(-1))
+	bp := NewBuffer(1000)
+	require.Equal(t, "*mempool.BufferWithCap", reflect.TypeOf(bp).String())
+
+	bp = NewBuffer(0)
+	require.Equal(t, "*mempool.Buffer", reflect.TypeOf(bp).String())
+
+	bp = NewBuffer(-1)
+	require.Equal(t, "*mempool.Buffer", reflect.TypeOf(bp).String())
+}
+
+func TestBuffer(t *testing.T) {
+	defer debug.SetGCPercent(debug.SetGCPercent(-1))
+	Size := 101
+
+	bp := NewBuffer(0)
+	buf := bp.Get()
+
+	for i := 0; i < Size; i++ {
+		buf.WriteByte('a')
+	}
+
+	bp.Put(buf)
+	buf = bp.Get()
+	require.Equal(t, 0, buf.Len())
+}
+
+func TestBufferWithCap(t *testing.T) {
+	defer debug.SetGCPercent(debug.SetGCPercent(-1))
+	Size := 101
+	bp := NewBuffer(100)
+	buf := bp.Get()
+
+	for i := 0; i < Size; i++ {
+		buf.WriteByte('a')
+	}
+
+	bp.Put(buf)
+	buf = bp.Get()
+	require.Equal(t, 0, buf.Len())
+	require.Equal(t, 0, buf.Cap())
+}
+
+func BenchmarkBufferPool(b *testing.B) {
+	bp := NewBuffer(0)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		b := bp.Get()
+		b.WriteString("this is a test")
+		bp.Put(b)
+	}
+}
+
+func BenchmarkBufferPoolWithCapLarger(b *testing.B) {
+	bp := NewBuffer(64 * 1024)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		b := bp.Get()
+		b.WriteString("this is a test")
+		bp.Put(b)
+	}
+}
+
+func BenchmarkBufferPoolWithCapLesser(b *testing.B) {
+	bp := NewBuffer(10)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		b := bp.Get()
+		b.WriteString("this is a test")
+		bp.Put(b)
+	}
+}
+
+func BenchmarkBufferWithoutPool(b *testing.B) {
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		b := new(bytes.Buffer)
+		b.WriteString("this is a test")
+		_ = b
+	}
+}

packets/codec.go

@@ -1,12 +1,18 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
 package packets
 
 import (
+	"bytes"
 	"encoding/binary"
+	"io"
 	"unicode/utf8"
 	"unsafe"
 )
 
-// bytesToString provides a zero-alloc, no-copy byte to string conversion.
+// bytesToString provides a zero-alloc no-copy byte to string conversion.
 // via https://github.com/golang/go/issues/25484#issuecomment-391415660
 func bytesToString(bs []byte) string {
 	return *(*string)(unsafe.Pointer(&bs))
@@ -15,12 +21,21 @@ func bytesToString(bs []byte) string {
 // decodeUint16 extracts the value of two bytes from a byte array.
 func decodeUint16(buf []byte, offset int) (uint16, int, error) {
 	if len(buf) < offset+2 {
-		return 0, 0, ErrOffsetUintOutOfRange
+		return 0, 0, ErrMalformedOffsetUintOutOfRange
 	}
 
 	return binary.BigEndian.Uint16(buf[offset : offset+2]), offset + 2, nil
 }
 
+// decodeUint32 extracts the value of four bytes from a byte array.
+func decodeUint32(buf []byte, offset int) (uint32, int, error) {
+	if len(buf) < offset+4 {
+		return 0, 0, ErrMalformedOffsetUintOutOfRange
+	}
+
+	return binary.BigEndian.Uint32(buf[offset : offset+4]), offset + 4, nil
+}
+
 // decodeString extracts a string from a byte array, beginning at an offset.
 func decodeString(buf []byte, offset int) (string, int, error) {
 	b, n, err := decodeBytes(buf, offset)
@@ -28,22 +43,27 @@ func decodeString(buf []byte, offset int) (string, int, error) {
 		return "", 0, err
 	}
 
+	if !validUTF8(b) { // [MQTT-1.5.4-1] [MQTT-3.1.3-5]
+		return "", 0, ErrMalformedInvalidUTF8
+	}
+
 	return bytesToString(b), n, nil
 }
 
+// validUTF8 checks if the byte array contains valid UTF-8 characters.
+func validUTF8(b []byte) bool {
+	return utf8.Valid(b) && bytes.IndexByte(b, 0x00) == -1 // [MQTT-1.5.4-1] [MQTT-1.5.4-2]
+}
+
 // decodeBytes extracts a byte array from a byte array, beginning at an offset. Used primarily for message payloads.
 func decodeBytes(buf []byte, offset int) ([]byte, int, error) {
 	length, next, err := decodeUint16(buf, offset)
 	if err != nil {
-		return make([]byte, 0, 0), 0, err
+		return make([]byte, 0), 0, err
 	}
 
 	if next+int(length) > len(buf) {
-		return make([]byte, 0, 0), 0, ErrOffsetStrOutOfRange
-	}
-
-	if !validUTF8(buf[next : next+int(length)]) {
-		return make([]byte, 0, 0), 0, ErrOffsetStrInvalidUTF8
+		return make([]byte, 0), 0, ErrMalformedOffsetBytesOutOfRange
 	}
 
 	return buf[next : next+int(length)], next + int(length), nil
@@ -52,7 +72,7 @@ func decodeBytes(buf []byte, offset int) ([]byte, int, error) {
 // decodeByte extracts the value of a byte from a byte array.
 func decodeByte(buf []byte, offset int) (byte, int, error) {
 	if len(buf) <= offset {
-		return 0, 0, ErrOffsetByteOutOfRange
+		return 0, 0, ErrMalformedOffsetByteOutOfRange
 	}
 	return buf[offset], offset + 1, nil
 }
@@ -60,7 +80,7 @@ func decodeByte(buf []byte, offset int) (byte, int, error) {
 // decodeByteBool extracts the value of a byte from a byte array and returns a bool.
 func decodeByteBool(buf []byte, offset int) (bool, int, error) {
 	if len(buf) <= offset {
-		return false, 0, ErrOffsetBoolOutOfRange
+		return false, 0, ErrMalformedOffsetBoolOutOfRange
 	}
 	return 1&buf[offset] > 0, offset + 1, nil
 }
@@ -75,7 +95,7 @@ func encodeBool(b bool) byte {
 
 // encodeBytes encodes a byte array to a byte array. Used primarily for message payloads.
 func encodeBytes(val []byte) []byte {
-	// In many circumstances the number of bytes being encoded is small.
+	// In most circumstances the number of bytes being encoded is small.
 	// Setting the cap to a low amount allows us to account for those without
 	// triggering allocation growth on append unless we need to.
 	buf := make([]byte, 2, 32)
@@ -90,6 +110,13 @@ func encodeUint16(val uint16) []byte {
 	return buf
 }
 
+// encodeUint32 encodes a uint16 value to a byte array.
+func encodeUint32(val uint32) []byte {
+	buf := make([]byte, 4)
+	binary.BigEndian.PutUint32(buf, val)
+	return buf
+}
+
 // encodeString encodes a string to a byte array.
 func encodeString(val string) []byte {
 	// Like encodeBytes, we set the cap to a small number to avoid
@@ -99,16 +126,47 @@ func encodeString(val string) []byte {
 	return append(buf, []byte(val)...)
 }
 
-// validUTF8 checks if the byte array contains valid UTF-8 characters, specifically
-// conforming to the MQTT specification requirements.
-func validUTF8(b []byte) bool {
-	// [MQTT-1.4.0-1] The character data in a UTF-8 encoded string MUST be well-formed UTF-8...
-	if !utf8.Valid(b) {
-		return false
+// encodeLength writes length bits for the header.
+func encodeLength(b *bytes.Buffer, length int64) {
+	// 1.5.5 Variable Byte Integer encode non-normative
+	// https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901027
+	for {
+		eb := byte(length % 128)
+		length /= 128
+		if length > 0 {
+			eb |= 0x80
+		}
+		b.WriteByte(eb)
+		if length == 0 {
+			break // [MQTT-1.5.5-1]
+		}
+	}
+}
+
+func DecodeLength(b io.ByteReader) (n, bu int, err error) {
+	// see 1.5.5 Variable Byte Integer decode non-normative
+	// https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901027
+	var multiplier uint32
+	var value uint32
+	bu = 1
+	for {
+		eb, err := b.ReadByte()
+		if err != nil {
+			return 0, bu, err
+		}
+
+		value |= uint32(eb&127) << multiplier
+		if value > 268435455 {
+			return 0, bu, ErrMalformedVariableByteInteger
+		}
+
+		if (eb & 128) == 0 {
+			break
+		}
+
+		multiplier += 7
+		bu++
 	}
 
-	// [MQTT-1.4.0-2] A UTF-8 encoded string MUST NOT include an encoding of the null character U+0000...
-	// ...
-	return true
-
+	return int(value), bu, nil
 }

packets/codec_test.go

@@ -0,0 +1,422 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"math"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestBytesToString(t *testing.T) {
+	b := []byte{'a', 'b', 'c'}
+	require.Equal(t, "abc", bytesToString(b))
+}
+
+func TestDecodeString(t *testing.T) {
+	expect := []struct {
+		name       string
+		rawBytes   []byte
+		result     string
+		offset     int
+		shouldFail error
+	}{
+		{
+			offset:   0,
+			rawBytes: []byte{0, 7, 97, 47, 98, 47, 99, 47, 100, 97},
+			result:   "a/b/c/d",
+		},
+		{
+			offset: 14,
+			rawBytes: []byte{
+				Connect << 4, 17, // Fixed header
+				0, 6, // Protocol Name - MSB+LSB
+				'M', 'Q', 'I', 's', 'd', 'p', // Protocol Name
+				3,     // Protocol Version
+				0,     // Packet Flags
+				0, 30, // Keepalive
+				0, 3, // Client ID - MSB+LSB
+				'h', 'e', 'y', // Client ID "zen"},
+			},
+			result: "hey",
+		},
+		{
+			offset:   2,
+			rawBytes: []byte{0, 0, 0, 23, 49, 47, 50, 47, 51, 47, 52, 47, 97, 47, 98, 47, 99, 47, 100, 47, 101, 47, 94, 47, 64, 47, 33, 97},
+			result:   "1/2/3/4/a/b/c/d/e/^/@/!",
+		},
+		{
+			offset:   0,
+			rawBytes: []byte{0, 5, 120, 47, 121, 47, 122, 33, 64, 35, 36, 37, 94, 38},
+			result:   "x/y/z",
+		},
+		{
+			offset:     0,
+			rawBytes:   []byte{0, 9, 'a', '/', 'b', '/', 'c', '/', 'd', 'z'},
+			shouldFail: ErrMalformedOffsetBytesOutOfRange,
+		},
+		{
+			offset:     5,
+			rawBytes:   []byte{0, 7, 97, 47, 98, 47, 'x'},
+			shouldFail: ErrMalformedOffsetBytesOutOfRange,
+		},
+		{
+			offset:     9,
+			rawBytes:   []byte{0, 7, 97, 47, 98, 47, 'y'},
+			shouldFail: ErrMalformedOffsetUintOutOfRange,
+		},
+		{
+			offset: 17,
+			rawBytes: []byte{
+				Connect << 4, 0, // Fixed header
+				0, 4, // Protocol Name - MSB+LSB
+				'M', 'Q', 'T', 'T', // Protocol Name
+				4,     // Protocol Version
+				0,     // Flags
+				0, 20, // Keepalive
+				0, 3, // Client ID - MSB+LSB
+				'z', 'e', 'n', // Client ID "zen"
+				0, 6, // Will Topic - MSB+LSB
+				'l',
+			},
+			shouldFail: ErrMalformedOffsetBytesOutOfRange,
+		},
+		{
+			offset:     0,
+			rawBytes:   []byte{0, 7, 0xc3, 0x28, 98, 47, 99, 47, 100},
+			shouldFail: ErrMalformedInvalidUTF8,
+		},
+	}
+
+	for i, wanted := range expect {
+		t.Run(fmt.Sprint(i), func(t *testing.T) {
+			result, _, err := decodeString(wanted.rawBytes, wanted.offset)
+			if wanted.shouldFail != nil {
+				require.True(t, errors.Is(err, wanted.shouldFail), "want %v to be a %v", err, wanted.shouldFail)
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, wanted.result, result)
+		})
+	}
+}
+
+func TestDecodeStringZeroWidthNoBreak(t *testing.T) { // [MQTT-1.5.4-3]
+	result, _, err := decodeString([]byte{0, 3, 0xEF, 0xBB, 0xBF}, 0)
+	require.NoError(t, err)
+	require.Equal(t, "\ufeff", result)
+}
+
+func TestDecodeBytes(t *testing.T) {
+	expect := []struct {
+		rawBytes   []byte
+		result     []uint8
+		next       int
+		offset     int
+		shouldFail error
+	}{
+		{
+			rawBytes: []byte{0, 4, 77, 81, 84, 84, 4, 194, 0, 50, 0, 36, 49, 53, 52}, // truncated connect packet (clean session)
+			result:   []byte{0x4d, 0x51, 0x54, 0x54},
+			next:     6,
+			offset:   0,
+		},
+		{
+			rawBytes: []byte{0, 4, 77, 81, 84, 84, 4, 192, 0, 50, 0, 36, 49, 53, 52, 50}, // truncated connect packet, only checking start
+			result:   []byte{0x4d, 0x51, 0x54, 0x54},
+			next:     6,
+			offset:   0,
+		},
+		{
+			rawBytes:   []byte{0, 4, 77, 81},
+			offset:     0,
+			shouldFail: ErrMalformedOffsetBytesOutOfRange,
+		},
+		{
+			rawBytes:   []byte{0, 4, 77, 81},
+			offset:     8,
+			shouldFail: ErrMalformedOffsetUintOutOfRange,
+		},
+	}
+
+	for i, wanted := range expect {
+		t.Run(fmt.Sprint(i), func(t *testing.T) {
+			result, _, err := decodeBytes(wanted.rawBytes, wanted.offset)
+			if wanted.shouldFail != nil {
+				require.True(t, errors.Is(err, wanted.shouldFail), "want %v to be a %v", err, wanted.shouldFail)
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, wanted.result, result)
+		})
+	}
+}
+
+func TestDecodeByte(t *testing.T) {
+	expect := []struct {
+		rawBytes   []byte
+		result     uint8
+		offset     int
+		shouldFail error
+	}{
+		{
+			rawBytes: []byte{0, 4, 77, 81, 84, 84}, // nonsense slice of bytes
+			result:   uint8(0x00),
+			offset:   0,
+		},
+		{
+			rawBytes: []byte{0, 4, 77, 81, 84, 84},
+			result:   uint8(0x04),
+			offset:   1,
+		},
+		{
+			rawBytes: []byte{0, 4, 77, 81, 84, 84},
+			result:   uint8(0x4d),
+			offset:   2,
+		},
+		{
+			rawBytes: []byte{0, 4, 77, 81, 84, 84},
+			result:   uint8(0x51),
+			offset:   3,
+		},
+		{
+			rawBytes:   []byte{0, 4, 77, 80, 82, 84},
+			offset:     8,
+			shouldFail: ErrMalformedOffsetByteOutOfRange,
+		},
+	}
+
+	for i, wanted := range expect {
+		t.Run(fmt.Sprint(i), func(t *testing.T) {
+			result, offset, err := decodeByte(wanted.rawBytes, wanted.offset)
+			if wanted.shouldFail != nil {
+				require.True(t, errors.Is(err, wanted.shouldFail), "want %v to be a %v", err, wanted.shouldFail)
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, wanted.result, result)
+			require.Equal(t, i+1, offset)
+		})
+	}
+}
+
+func TestDecodeUint16(t *testing.T) {
+	expect := []struct {
+		rawBytes   []byte
+		result     uint16
+		offset     int
+		shouldFail error
+	}{
+		{
+			rawBytes: []byte{0, 7, 97, 47, 98, 47, 99, 47, 100, 97},
+			result:   uint16(0x07),
+			offset:   0,
+		},
+		{
+			rawBytes: []byte{0, 7, 97, 47, 98, 47, 99, 47, 100, 97},
+			result:   uint16(0x761),
+			offset:   1,
+		},
+		{
+			rawBytes:   []byte{0, 7, 255, 47},
+			offset:     8,
+			shouldFail: ErrMalformedOffsetUintOutOfRange,
+		},
+	}
+
+	for i, wanted := range expect {
+		t.Run(fmt.Sprint(i), func(t *testing.T) {
+			result, offset, err := decodeUint16(wanted.rawBytes, wanted.offset)
+			if wanted.shouldFail != nil {
+				require.True(t, errors.Is(err, wanted.shouldFail), "want %v to be a %v", err, wanted.shouldFail)
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, wanted.result, result)
+			require.Equal(t, i+2, offset)
+		})
+	}
+}
+
+func TestDecodeUint32(t *testing.T) {
+	expect := []struct {
+		rawBytes   []byte
+		result     uint32
+		offset     int
+		shouldFail error
+	}{
+		{
+			rawBytes: []byte{0, 0, 0, 7, 8},
+			result:   uint32(7),
+			offset:   0,
+		},
+		{
+			rawBytes: []byte{0, 0, 1, 226, 64, 8},
+			result:   uint32(123456),
+			offset:   1,
+		},
+		{
+			rawBytes:   []byte{0, 7, 255, 47},
+			offset:     8,
+			shouldFail: ErrMalformedOffsetUintOutOfRange,
+		},
+	}
+
+	for i, wanted := range expect {
+		t.Run(fmt.Sprint(i), func(t *testing.T) {
+			result, offset, err := decodeUint32(wanted.rawBytes, wanted.offset)
+			if wanted.shouldFail != nil {
+				require.True(t, errors.Is(err, wanted.shouldFail), "want %v to be a %v", err, wanted.shouldFail)
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, wanted.result, result)
+			require.Equal(t, i+4, offset)
+		})
+	}
+}
+
+func TestDecodeByteBool(t *testing.T) {
+	expect := []struct {
+		rawBytes   []byte
+		result     bool
+		offset     int
+		shouldFail error
+	}{
+		{
+			rawBytes: []byte{0x00, 0x00},
+			result:   false,
+		},
+		{
+			rawBytes: []byte{0x01, 0x00},
+			result:   true,
+		},
+		{
+			rawBytes:   []byte{0x01, 0x00},
+			offset:     5,
+			shouldFail: ErrMalformedOffsetBoolOutOfRange,
+		},
+	}
+
+	for i, wanted := range expect {
+		t.Run(fmt.Sprint(i), func(t *testing.T) {
+			result, offset, err := decodeByteBool(wanted.rawBytes, wanted.offset)
+			if wanted.shouldFail != nil {
+				require.True(t, errors.Is(err, wanted.shouldFail), "want %v to be a %v", err, wanted.shouldFail)
+				return
+			}
+
+			require.NoError(t, err)
+			require.Equal(t, wanted.result, result)
+			require.Equal(t, 1, offset)
+		})
+	}
+}
+
+func TestDecodeLength(t *testing.T) {
+	b := bytes.NewBuffer([]byte{0x78})
+	n, bu, err := DecodeLength(b)
+	require.NoError(t, err)
+	require.Equal(t, 120, n)
+	require.Equal(t, 1, bu)
+
+	b = bytes.NewBuffer([]byte{255, 255, 255, 127})
+	n, bu, err = DecodeLength(b)
+	require.NoError(t, err)
+	require.Equal(t, 268435455, n)
+	require.Equal(t, 4, bu)
+}
+
+func TestDecodeLengthErrors(t *testing.T) {
+	b := bytes.NewBuffer([]byte{})
+	_, _, err := DecodeLength(b)
+	require.Error(t, err)
+
+	b = bytes.NewBuffer([]byte{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f})
+	_, _, err = DecodeLength(b)
+	require.Error(t, err)
+	require.ErrorIs(t, err, ErrMalformedVariableByteInteger)
+}
+
+func TestEncodeBool(t *testing.T) {
+	result := encodeBool(true)
+	require.Equal(t, byte(1), result)
+
+	result = encodeBool(false)
+	require.Equal(t, byte(0), result)
+
+	// Check failure.
+	result = encodeBool(false)
+	require.NotEqual(t, byte(1), result)
+}
+
+func TestEncodeBytes(t *testing.T) {
+	result := encodeBytes([]byte("testing"))
+	require.Equal(t, []uint8{0, 7, 116, 101, 115, 116, 105, 110, 103}, result)
+
+	result = encodeBytes([]byte("testing"))
+	require.NotEqual(t, []uint8{0, 7, 113, 101, 115, 116, 105, 110, 103}, result)
+}
+
+func TestEncodeUint16(t *testing.T) {
+	result := encodeUint16(0)
+	require.Equal(t, []byte{0x00, 0x00}, result)
+
+	result = encodeUint16(32767)
+	require.Equal(t, []byte{0x7f, 0xff}, result)
+
+	result = encodeUint16(math.MaxUint16)
+	require.Equal(t, []byte{0xff, 0xff}, result)
+}
+
+func TestEncodeUint32(t *testing.T) {
+	result := encodeUint32(7)
+	require.Equal(t, []byte{0x00, 0x00, 0x00, 0x07}, result)
+
+	result = encodeUint32(32767)
+	require.Equal(t, []byte{0, 0, 127, 255}, result)
+
+	result = encodeUint32(math.MaxUint32)
+	require.Equal(t, []byte{255, 255, 255, 255}, result)
+}
+
+func TestEncodeString(t *testing.T) {
+	result := encodeString("testing")
+	require.Equal(t, []uint8{0x00, 0x07, 0x74, 0x65, 0x73, 0x74, 0x69, 0x6e, 0x67}, result)
+
+	result = encodeString("")
+	require.Equal(t, []uint8{0x00, 0x00}, result)
+
+	result = encodeString("a")
+	require.Equal(t, []uint8{0x00, 0x01, 0x61}, result)
+
+	result = encodeString("b")
+	require.NotEqual(t, []uint8{0x00, 0x00}, result)
+}
+
+func TestEncodeLength(t *testing.T) {
+	b := new(bytes.Buffer)
+	encodeLength(b, 120)
+	require.Equal(t, []byte{0x78}, b.Bytes())
+
+	b = new(bytes.Buffer)
+	encodeLength(b, math.MaxInt64)
+	require.Equal(t, []byte{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f}, b.Bytes())
+}
+
+func TestValidUTF8(t *testing.T) {
+	require.True(t, validUTF8([]byte{0x74, 0x65, 0x73, 0x74, 0x69, 0x6e, 0x67}))
+	require.False(t, validUTF8([]byte{0xff, 0xff}))
+	require.False(t, validUTF8([]byte{0x74, 0x00, 0x73, 0x74}))
+}

packets/codes.go

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+// Code contains a reason code and reason string for a response.
+type Code struct {
+	Reason string
+	Code   byte
+}
+
+// String returns the readable reason for a code.
+func (c Code) String() string {
+	return c.Reason
+}
+
+// Error returns the readable reason for a code.
+func (c Code) Error() string {
+	return c.Reason
+}
+
+var (
+	// QosCodes indicates the reason codes for each Qos byte.
+	QosCodes = map[byte]Code{
+		0: CodeGrantedQos0,
+		1: CodeGrantedQos1,
+		2: CodeGrantedQos2,
+	}
+
+	CodeSuccessIgnore                         = Code{Code: 0x00, Reason: "ignore packet"}
+	CodeSuccess                               = Code{Code: 0x00, Reason: "success"}
+	CodeDisconnect                            = Code{Code: 0x00, Reason: "disconnected"}
+	CodeGrantedQos0                           = Code{Code: 0x00, Reason: "granted qos 0"}
+	CodeGrantedQos1                           = Code{Code: 0x01, Reason: "granted qos 1"}
+	CodeGrantedQos2                           = Code{Code: 0x02, Reason: "granted qos 2"}
+	CodeDisconnectWillMessage                 = Code{Code: 0x04, Reason: "disconnect with will message"}
+	CodeNoMatchingSubscribers                 = Code{Code: 0x10, Reason: "no matching subscribers"}
+	CodeNoSubscriptionExisted                 = Code{Code: 0x11, Reason: "no subscription existed"}
+	CodeContinueAuthentication                = Code{Code: 0x18, Reason: "continue authentication"}
+	CodeReAuthenticate                        = Code{Code: 0x19, Reason: "re-authenticate"}
+	ErrUnspecifiedError                       = Code{Code: 0x80, Reason: "unspecified error"}
+	ErrMalformedPacket                        = Code{Code: 0x81, Reason: "malformed packet"}
+	ErrMalformedProtocolName                  = Code{Code: 0x81, Reason: "malformed packet: protocol name"}
+	ErrMalformedProtocolVersion               = Code{Code: 0x81, Reason: "malformed packet: protocol version"}
+	ErrMalformedFlags                         = Code{Code: 0x81, Reason: "malformed packet: flags"}
+	ErrMalformedKeepalive                     = Code{Code: 0x81, Reason: "malformed packet: keepalive"}
+	ErrMalformedPacketID                      = Code{Code: 0x81, Reason: "malformed packet: packet identifier"}
+	ErrMalformedTopic                         = Code{Code: 0x81, Reason: "malformed packet: topic"}
+	ErrMalformedWillTopic                     = Code{Code: 0x81, Reason: "malformed packet: will topic"}
+	ErrMalformedWillPayload                   = Code{Code: 0x81, Reason: "malformed packet: will message"}
+	ErrMalformedUsername                      = Code{Code: 0x81, Reason: "malformed packet: username"}
+	ErrMalformedPassword                      = Code{Code: 0x81, Reason: "malformed packet: password"}
+	ErrMalformedQos                           = Code{Code: 0x81, Reason: "malformed packet: qos"}
+	ErrMalformedOffsetUintOutOfRange          = Code{Code: 0x81, Reason: "malformed packet: offset uint out of range"}
+	ErrMalformedOffsetBytesOutOfRange         = Code{Code: 0x81, Reason: "malformed packet: offset bytes out of range"}
+	ErrMalformedOffsetByteOutOfRange          = Code{Code: 0x81, Reason: "malformed packet: offset byte out of range"}
+	ErrMalformedOffsetBoolOutOfRange          = Code{Code: 0x81, Reason: "malformed packet: offset boolean out of range"}
+	ErrMalformedInvalidUTF8                   = Code{Code: 0x81, Reason: "malformed packet: invalid utf-8 string"}
+	ErrMalformedVariableByteInteger           = Code{Code: 0x81, Reason: "malformed packet: variable byte integer out of range"}
+	ErrMalformedBadProperty                   = Code{Code: 0x81, Reason: "malformed packet: unknown property"}
+	ErrMalformedProperties                    = Code{Code: 0x81, Reason: "malformed packet: properties"}
+	ErrMalformedWillProperties                = Code{Code: 0x81, Reason: "malformed packet: will properties"}
+	ErrMalformedSessionPresent                = Code{Code: 0x81, Reason: "malformed packet: session present"}
+	ErrMalformedReasonCode                    = Code{Code: 0x81, Reason: "malformed packet: reason code"}
+	ErrProtocolViolation                      = Code{Code: 0x82, Reason: "protocol violation"}
+	ErrProtocolViolationProtocolName          = Code{Code: 0x82, Reason: "protocol violation: protocol name"}
+	ErrProtocolViolationProtocolVersion       = Code{Code: 0x82, Reason: "protocol violation: protocol version"}
+	ErrProtocolViolationReservedBit           = Code{Code: 0x82, Reason: "protocol violation: reserved bit not 0"}
+	ErrProtocolViolationFlagNoUsername        = Code{Code: 0x82, Reason: "protocol violation: username flag set but no value"}
+	ErrProtocolViolationFlagNoPassword        = Code{Code: 0x82, Reason: "protocol violation: password flag set but no value"}
+	ErrProtocolViolationUsernameNoFlag        = Code{Code: 0x82, Reason: "protocol violation: username set but no flag"}
+	ErrProtocolViolationPasswordNoFlag        = Code{Code: 0x82, Reason: "protocol violation: username set but no flag"}
+	ErrProtocolViolationPasswordTooLong       = Code{Code: 0x82, Reason: "protocol violation: password too long"}
+	ErrProtocolViolationUsernameTooLong       = Code{Code: 0x82, Reason: "protocol violation: username too long"}
+	ErrProtocolViolationNoPacketID            = Code{Code: 0x82, Reason: "protocol violation: missing packet id"}
+	ErrProtocolViolationSurplusPacketID       = Code{Code: 0x82, Reason: "protocol violation: surplus packet id"}
+	ErrProtocolViolationQosOutOfRange         = Code{Code: 0x82, Reason: "protocol violation: qos out of range"}
+	ErrProtocolViolationSecondConnect         = Code{Code: 0x82, Reason: "protocol violation: second connect packet"}
+	ErrProtocolViolationZeroNonZeroExpiry     = Code{Code: 0x82, Reason: "protocol violation: non-zero expiry"}
+	ErrProtocolViolationRequireFirstConnect   = Code{Code: 0x82, Reason: "protocol violation: first packet must be connect"}
+	ErrProtocolViolationWillFlagNoPayload     = Code{Code: 0x82, Reason: "protocol violation: will flag no payload"}
+	ErrProtocolViolationWillFlagSurplusRetain = Code{Code: 0x82, Reason: "protocol violation: will flag surplus retain"}
+	ErrProtocolViolationSurplusWildcard       = Code{Code: 0x82, Reason: "protocol violation: topic contains wildcards"}
+	ErrProtocolViolationSurplusSubID          = Code{Code: 0x82, Reason: "protocol violation: contained subscription identifier"}
+	ErrProtocolViolationInvalidTopic          = Code{Code: 0x82, Reason: "protocol violation: invalid topic"}
+	ErrProtocolViolationInvalidSharedNoLocal  = Code{Code: 0x82, Reason: "protocol violation: invalid shared no local"}
+	ErrProtocolViolationNoFilters             = Code{Code: 0x82, Reason: "protocol violation: must contain at least one filter"}
+	ErrProtocolViolationInvalidReason         = Code{Code: 0x82, Reason: "protocol violation: invalid reason"}
+	ErrProtocolViolationOversizeSubID         = Code{Code: 0x82, Reason: "protocol violation: oversize subscription id"}
+	ErrProtocolViolationDupNoQos              = Code{Code: 0x82, Reason: "protocol violation: dup true with no qos"}
+	ErrProtocolViolationUnsupportedProperty   = Code{Code: 0x82, Reason: "protocol violation: unsupported property"}
+	ErrProtocolViolationNoTopic               = Code{Code: 0x82, Reason: "protocol violation: no topic or alias"}
+	ErrImplementationSpecificError            = Code{Code: 0x83, Reason: "implementation specific error"}
+	ErrRejectPacket                           = Code{Code: 0x83, Reason: "packet rejected"}
+	ErrUnsupportedProtocolVersion             = Code{Code: 0x84, Reason: "unsupported protocol version"}
+	ErrClientIdentifierNotValid               = Code{Code: 0x85, Reason: "client identifier not valid"}
+	ErrClientIdentifierTooLong                = Code{Code: 0x85, Reason: "client identifier too long"}
+	ErrBadUsernameOrPassword                  = Code{Code: 0x86, Reason: "bad username or password"}
+	ErrNotAuthorized                          = Code{Code: 0x87, Reason: "not authorized"}
+	ErrServerUnavailable                      = Code{Code: 0x88, Reason: "server unavailable"}
+	ErrServerBusy                             = Code{Code: 0x89, Reason: "server busy"}
+	ErrBanned                                 = Code{Code: 0x8A, Reason: "banned"}
+	ErrServerShuttingDown                     = Code{Code: 0x8B, Reason: "server shutting down"}
+	ErrBadAuthenticationMethod                = Code{Code: 0x8C, Reason: "bad authentication method"}
+	ErrKeepAliveTimeout                       = Code{Code: 0x8D, Reason: "keep alive timeout"}
+	ErrSessionTakenOver                       = Code{Code: 0x8E, Reason: "session takeover"}
+	ErrTopicFilterInvalid                     = Code{Code: 0x8F, Reason: "topic filter invalid"}
+	ErrTopicNameInvalid                       = Code{Code: 0x90, Reason: "topic name invalid"}
+	ErrPacketIdentifierInUse                  = Code{Code: 0x91, Reason: "packet identifier in use"}
+	ErrPacketIdentifierNotFound               = Code{Code: 0x92, Reason: "packet identifier not found"}
+	ErrReceiveMaximum                         = Code{Code: 0x93, Reason: "receive maximum exceeded"}
+	ErrTopicAliasInvalid                      = Code{Code: 0x94, Reason: "topic alias invalid"}
+	ErrPacketTooLarge                         = Code{Code: 0x95, Reason: "packet too large"}
+	ErrMessageRateTooHigh                     = Code{Code: 0x96, Reason: "message rate too high"}
+	ErrQuotaExceeded                          = Code{Code: 0x97, Reason: "quota exceeded"}
+	ErrPendingClientWritesExceeded            = Code{Code: 0x97, Reason: "too many pending writes"}
+	ErrAdministrativeAction                   = Code{Code: 0x98, Reason: "administrative action"}
+	ErrPayloadFormatInvalid                   = Code{Code: 0x99, Reason: "payload format invalid"}
+	ErrRetainNotSupported                     = Code{Code: 0x9A, Reason: "retain not supported"}
+	ErrQosNotSupported                        = Code{Code: 0x9B, Reason: "qos not supported"}
+	ErrUseAnotherServer                       = Code{Code: 0x9C, Reason: "use another server"}
+	ErrServerMoved                            = Code{Code: 0x9D, Reason: "server moved"}
+	ErrSharedSubscriptionsNotSupported        = Code{Code: 0x9E, Reason: "shared subscriptions not supported"}
+	ErrConnectionRateExceeded                 = Code{Code: 0x9F, Reason: "connection rate exceeded"}
+	ErrMaxConnectTime                         = Code{Code: 0xA0, Reason: "maximum connect time"}
+	ErrSubscriptionIdentifiersNotSupported    = Code{Code: 0xA1, Reason: "subscription identifiers not supported"}
+	ErrWildcardSubscriptionsNotSupported      = Code{Code: 0xA2, Reason: "wildcard subscriptions not supported"}
+	ErrInlineSubscriptionHandlerInvalid       = Code{Code: 0xA3, Reason: "inline subscription handler not valid."}
+
+	// MQTTv3 specific bytes.
+	Err3UnsupportedProtocolVersion = Code{Code: 0x01}
+	Err3ClientIdentifierNotValid   = Code{Code: 0x02}
+	Err3ServerUnavailable          = Code{Code: 0x03}
+	ErrMalformedUsernameOrPassword = Code{Code: 0x04}
+	Err3NotAuthorized              = Code{Code: 0x05}
+
+	// V5CodesToV3 maps MQTTv5 Connack reason codes to MQTTv3 return codes.
+	// This is required because MQTTv3 has different return byte specification.
+	// See http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc385349257
+	V5CodesToV3 = map[Code]Code{
+		ErrUnsupportedProtocolVersion: Err3UnsupportedProtocolVersion,
+		ErrClientIdentifierNotValid:   Err3ClientIdentifierNotValid,
+		ErrServerUnavailable:          Err3ServerUnavailable,
+		ErrMalformedUsername:          ErrMalformedUsernameOrPassword,
+		ErrMalformedPassword:          ErrMalformedUsernameOrPassword,
+		ErrBadUsernameOrPassword:      Err3NotAuthorized,
+	}
+)

packets/codes_test.go

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestCodesString(t *testing.T) {
+	c := Code{
+		Reason: "test",
+		Code:   0x1,
+	}
+
+	require.Equal(t, "test", c.String())
+}
+
+func TestCodesError(t *testing.T) {
+	c := Code{
+		Reason: "error",
+		Code:   0x1,
+	}
+
+	require.Equal(t, "error", error(c).Error())
+}

packets/fixedheader.go

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+import (
+	"bytes"
+)
+
+// FixedHeader contains the values of the fixed header portion of the MQTT packet.
+type FixedHeader struct {
+	Remaining int  `json:"remaining"` // the number of remaining bytes in the payload.
+	Type      byte `json:"type"`      // the type of the packet (PUBLISH, SUBSCRIBE, etc) from bits 7 - 4 (byte 1).
+	Qos       byte `json:"qos"`       // indicates the quality of service expected.
+	Dup       bool `json:"dup"`       // indicates if the packet was already sent at an earlier time.
+	Retain    bool `json:"retain"`    // whether the message should be retained.
+}
+
+// Encode encodes the FixedHeader and returns a bytes buffer.
+func (fh *FixedHeader) Encode(buf *bytes.Buffer) {
+	buf.WriteByte(fh.Type<<4 | encodeBool(fh.Dup)<<3 | fh.Qos<<1 | encodeBool(fh.Retain))
+	encodeLength(buf, int64(fh.Remaining))
+}
+
+// Decode extracts the specification bits from the header byte.
+func (fh *FixedHeader) Decode(hb byte) error {
+	fh.Type = hb >> 4 // Get the message type from the first 4 bytes.
+
+	switch fh.Type {
+	case Publish:
+		if (hb>>1)&0x01 > 0 && (hb>>1)&0x02 > 0 {
+			return ErrProtocolViolationQosOutOfRange // [MQTT-3.3.1-4]
+		}
+
+		fh.Dup = (hb>>3)&0x01 > 0 // is duplicate
+		fh.Qos = (hb >> 1) & 0x03 // qos flag
+		fh.Retain = hb&0x01 > 0   // is retain flag
+	case Pubrel:
+		fallthrough
+	case Subscribe:
+		fallthrough
+	case Unsubscribe:
+		if (hb>>0)&0x01 != 0 || (hb>>1)&0x01 != 1 || (hb>>2)&0x01 != 0 || (hb>>3)&0x01 != 0 { // [MQTT-3.8.1-1] [MQTT-3.10.1-1]
+			return ErrMalformedFlags
+		}
+
+		fh.Qos = (hb >> 1) & 0x03
+	default:
+		if (hb>>0)&0x01 != 0 ||
+			(hb>>1)&0x01 != 0 ||
+			(hb>>2)&0x01 != 0 ||
+			(hb>>3)&0x01 != 0 { // [MQTT-3.8.3-5] [MQTT-3.14.1-1] [MQTT-3.15.1-1]
+			return ErrMalformedFlags
+		}
+	}
+
+	if fh.Qos == 0 && fh.Dup {
+		return ErrProtocolViolationDupNoQos // [MQTT-3.3.1-2]
+	}
+
+	return nil
+}

packets/fixedheader_test.go

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+type fixedHeaderTable struct {
+	desc        string
+	rawBytes    []byte
+	header      FixedHeader
+	packetError bool
+	expect      error
+}
+
+var fixedHeaderExpected = []fixedHeaderTable{
+	{
+		desc:     "connect",
+		rawBytes: []byte{Connect << 4, 0x00},
+		header:   FixedHeader{Type: Connect, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "connack",
+		rawBytes: []byte{Connack << 4, 0x00},
+		header:   FixedHeader{Type: Connack, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "publish",
+		rawBytes: []byte{Publish << 4, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "publish qos 1",
+		rawBytes: []byte{Publish<<4 | 1<<1, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 1, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "publish qos 1 retain",
+		rawBytes: []byte{Publish<<4 | 1<<1 | 1, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 1, Retain: true, Remaining: 0},
+	},
+	{
+		desc:     "publish qos 2",
+		rawBytes: []byte{Publish<<4 | 2<<1, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 2, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "publish qos 2 retain",
+		rawBytes: []byte{Publish<<4 | 2<<1 | 1, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 2, Retain: true, Remaining: 0},
+	},
+	{
+		desc:     "publish dup qos 0",
+		rawBytes: []byte{Publish<<4 | 1<<3, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: true, Qos: 0, Retain: false, Remaining: 0},
+		expect:   ErrProtocolViolationDupNoQos,
+	},
+	{
+		desc:     "publish dup qos 0 retain",
+		rawBytes: []byte{Publish<<4 | 1<<3 | 1, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: true, Qos: 0, Retain: true, Remaining: 0},
+		expect:   ErrProtocolViolationDupNoQos,
+	},
+	{
+		desc:     "publish dup qos 1 retain",
+		rawBytes: []byte{Publish<<4 | 1<<3 | 1<<1 | 1, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: true, Qos: 1, Retain: true, Remaining: 0},
+	},
+	{
+		desc:     "publish dup qos 2 retain",
+		rawBytes: []byte{Publish<<4 | 1<<3 | 2<<1 | 1, 0x00},
+		header:   FixedHeader{Type: Publish, Dup: true, Qos: 2, Retain: true, Remaining: 0},
+	},
+	{
+		desc:     "puback",
+		rawBytes: []byte{Puback << 4, 0x00},
+		header:   FixedHeader{Type: Puback, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "pubrec",
+		rawBytes: []byte{Pubrec << 4, 0x00},
+		header:   FixedHeader{Type: Pubrec, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "pubrel",
+		rawBytes: []byte{Pubrel<<4 | 1<<1, 0x00},
+		header:   FixedHeader{Type: Pubrel, Dup: false, Qos: 1, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "pubcomp",
+		rawBytes: []byte{Pubcomp << 4, 0x00},
+		header:   FixedHeader{Type: Pubcomp, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "subscribe",
+		rawBytes: []byte{Subscribe<<4 | 1<<1, 0x00},
+		header:   FixedHeader{Type: Subscribe, Dup: false, Qos: 1, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "suback",
+		rawBytes: []byte{Suback << 4, 0x00},
+		header:   FixedHeader{Type: Suback, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "unsubscribe",
+		rawBytes: []byte{Unsubscribe<<4 | 1<<1, 0x00},
+		header:   FixedHeader{Type: Unsubscribe, Dup: false, Qos: 1, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "unsuback",
+		rawBytes: []byte{Unsuback << 4, 0x00},
+		header:   FixedHeader{Type: Unsuback, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "pingreq",
+		rawBytes: []byte{Pingreq << 4, 0x00},
+		header:   FixedHeader{Type: Pingreq, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "pingresp",
+		rawBytes: []byte{Pingresp << 4, 0x00},
+		header:   FixedHeader{Type: Pingresp, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "disconnect",
+		rawBytes: []byte{Disconnect << 4, 0x00},
+		header:   FixedHeader{Type: Disconnect, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+	{
+		desc:     "auth",
+		rawBytes: []byte{Auth << 4, 0x00},
+		header:   FixedHeader{Type: Auth, Dup: false, Qos: 0, Retain: false, Remaining: 0},
+	},
+
+	// remaining length
+	{
+		desc:     "remaining length 10",
+		rawBytes: []byte{Publish << 4, 0x0a},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 0, Retain: false, Remaining: 10},
+	},
+	{
+		desc:     "remaining length 512",
+		rawBytes: []byte{Publish << 4, 0x80, 0x04},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 0, Retain: false, Remaining: 512},
+	},
+	{
+		desc:     "remaining length 978",
+		rawBytes: []byte{Publish << 4, 0xd2, 0x07},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 0, Retain: false, Remaining: 978},
+	},
+	{
+		desc:     "remaining length 20202",
+		rawBytes: []byte{Publish << 4, 0x86, 0x9d, 0x01},
+		header:   FixedHeader{Type: Publish, Dup: false, Qos: 0, Retain: false, Remaining: 20102},
+	},
+	{
+		desc:        "remaining length oversize",
+		rawBytes:    []byte{Publish << 4, 0xd5, 0x86, 0xf9, 0x9e, 0x01},
+		header:      FixedHeader{Type: Publish, Dup: false, Qos: 0, Retain: false, Remaining: 333333333},
+		packetError: true,
+	},
+
+	// Invalid flags for packet
+	{
+		desc:     "invalid type dup is true",
+		rawBytes: []byte{Connect<<4 | 1<<3, 0x00},
+		header:   FixedHeader{Type: Connect, Dup: true, Qos: 0, Retain: false, Remaining: 0},
+		expect:   ErrMalformedFlags,
+	},
+	{
+		desc:     "invalid type qos is 1",
+		rawBytes: []byte{Connect<<4 | 1<<1, 0x00},
+		header:   FixedHeader{Type: Connect, Dup: false, Qos: 1, Retain: false, Remaining: 0},
+		expect:   ErrMalformedFlags,
+	},
+	{
+		desc:     "invalid type retain is true",
+		rawBytes: []byte{Connect<<4 | 1, 0x00},
+		header:   FixedHeader{Type: Connect, Dup: false, Qos: 0, Retain: true, Remaining: 0},
+		expect:   ErrMalformedFlags,
+	},
+	{
+		desc:     "invalid publish qos bits 1 + 2 set",
+		rawBytes: []byte{Publish<<4 | 1<<1 | 1<<2, 0x00},
+		header:   FixedHeader{Type: Publish},
+		expect:   ErrProtocolViolationQosOutOfRange,
+	},
+	{
+		desc:     "invalid pubrel bits 3,2,1,0 should be 0,0,1,0",
+		rawBytes: []byte{Pubrel<<4 | 1<<2 | 1<<0, 0x00},
+		header:   FixedHeader{Type: Pubrel, Qos: 1},
+		expect:   ErrMalformedFlags,
+	},
+	{
+		desc:     "invalid subscribe bits 3,2,1,0 should be 0,0,1,0",
+		rawBytes: []byte{Subscribe<<4 | 1<<2, 0x00},
+		header:   FixedHeader{Type: Subscribe, Qos: 1},
+		expect:   ErrMalformedFlags,
+	},
+}
+
+func TestFixedHeaderEncode(t *testing.T) {
+	for _, wanted := range fixedHeaderExpected {
+		t.Run(wanted.desc, func(t *testing.T) {
+			buf := new(bytes.Buffer)
+			wanted.header.Encode(buf)
+			if wanted.expect == nil {
+				require.Equal(t, len(wanted.rawBytes), len(buf.Bytes()))
+				require.EqualValues(t, wanted.rawBytes, buf.Bytes())
+			}
+		})
+	}
+}
+
+func TestFixedHeaderDecode(t *testing.T) {
+	for _, wanted := range fixedHeaderExpected {
+		t.Run(wanted.desc, func(t *testing.T) {
+			fh := new(FixedHeader)
+			err := fh.Decode(wanted.rawBytes[0])
+			if wanted.expect != nil {
+				require.Equal(t, wanted.expect, err)
+			} else {
+				require.NoError(t, err)
+				require.Equal(t, wanted.header.Type, fh.Type)
+				require.Equal(t, wanted.header.Dup, fh.Dup)
+				require.Equal(t, wanted.header.Qos, fh.Qos)
+				require.Equal(t, wanted.header.Retain, fh.Retain)
+			}
+		})
+	}
+}

packets/packets_test.go

@@ -0,0 +1,505 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2023 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+import (
+	"bytes"
+	"fmt"
+	"testing"
+
+	"github.com/jinzhu/copier"
+	"github.com/stretchr/testify/require"
+)
+
+const pkInfo = "packet type %v, %s"
+
+var packetList = []byte{
+	Connect,
+	Connack,
+	Publish,
+	Puback,
+	Pubrec,
+	Pubrel,
+	Pubcomp,
+	Subscribe,
+	Suback,
+	Unsubscribe,
+	Unsuback,
+	Pingreq,
+	Pingresp,
+	Disconnect,
+	Auth,
+}
+
+var pkTable = []TPacketCase{
+	TPacketData[Connect].Get(TConnectMqtt311),
+	TPacketData[Connect].Get(TConnectMqtt5),
+	TPacketData[Connect].Get(TConnectUserPassLWT),
+	TPacketData[Connack].Get(TConnackAcceptedMqtt5),
+	TPacketData[Connack].Get(TConnackAcceptedNoSession),
+	TPacketData[Publish].Get(TPublishBasic),
+	TPacketData[Publish].Get(TPublishMqtt5),
+	TPacketData[Puback].Get(TPuback),
+	TPacketData[Pubrec].Get(TPubrec),
+	TPacketData[Pubrel].Get(TPubrel),
+	TPacketData[Pubcomp].Get(TPubcomp),
+	TPacketData[Subscribe].Get(TSubscribe),
+	TPacketData[Subscribe].Get(TSubscribeMqtt5),
+	TPacketData[Suback].Get(TSuback),
+	TPacketData[Unsubscribe].Get(TUnsubscribe),
+	TPacketData[Unsubscribe].Get(TUnsubscribeMqtt5),
+	TPacketData[Pingreq].Get(TPingreq),
+	TPacketData[Pingresp].Get(TPingresp),
+	TPacketData[Disconnect].Get(TDisconnect),
+	TPacketData[Disconnect].Get(TDisconnectMqtt5),
+}
+
+func TestNewPackets(t *testing.T) {
+	s := NewPackets()
+	require.NotNil(t, s.internal)
+}
+
+func TestPacketsAdd(t *testing.T) {
+	s := NewPackets()
+	s.Add("cl1", Packet{})
+	require.Contains(t, s.internal, "cl1")
+}
+
+func TestPacketsGet(t *testing.T) {
+	s := NewPackets()
+	s.Add("cl1", Packet{TopicName: "a1"})
+	s.Add("cl2", Packet{TopicName: "a2"})
+	require.Contains(t, s.internal, "cl1")
+	require.Contains(t, s.internal, "cl2")
+
+	pk, ok := s.Get("cl1")
+	require.True(t, ok)
+	require.Equal(t, "a1", pk.TopicName)
+}
+
+func TestPacketsGetAll(t *testing.T) {
+	s := NewPackets()
+	s.Add("cl1", Packet{TopicName: "a1"})
+	s.Add("cl2", Packet{TopicName: "a2"})
+	s.Add("cl3", Packet{TopicName: "a3"})
+	require.Contains(t, s.internal, "cl1")
+	require.Contains(t, s.internal, "cl2")
+	require.Contains(t, s.internal, "cl3")
+
+	subs := s.GetAll()
+	require.Len(t, subs, 3)
+}
+
+func TestPacketsLen(t *testing.T) {
+	s := NewPackets()
+	s.Add("cl1", Packet{TopicName: "a1"})
+	s.Add("cl2", Packet{TopicName: "a2"})
+	require.Contains(t, s.internal, "cl1")
+	require.Contains(t, s.internal, "cl2")
+	require.Equal(t, 2, s.Len())
+}
+
+func TestSPacketsDelete(t *testing.T) {
+	s := NewPackets()
+	s.Add("cl1", Packet{TopicName: "a1"})
+	require.Contains(t, s.internal, "cl1")
+
+	s.Delete("cl1")
+	_, ok := s.Get("cl1")
+	require.False(t, ok)
+}
+
+func TestFormatPacketID(t *testing.T) {
+	for _, id := range []uint16{0, 7, 0x100, 0xffff} {
+		packet := &Packet{PacketID: id}
+		require.Equal(t, fmt.Sprint(id), packet.FormatID())
+	}
+}
+
+func TestSubscriptionOptionsEncodeDecode(t *testing.T) {
+	p := &Subscription{
+		Qos:               2,
+		NoLocal:           true,
+		RetainAsPublished: true,
+		RetainHandling:    2,
+	}
+	x := new(Subscription)
+	x.decode(p.encode())
+	require.Equal(t, *p, *x)
+
+	p = &Subscription{
+		Qos:               1,
+		NoLocal:           false,
+		RetainAsPublished: false,
+		RetainHandling:    1,
+	}
+	x = new(Subscription)
+	x.decode(p.encode())
+	require.Equal(t, *p, *x)
+}
+
+func TestPacketEncode(t *testing.T) {
+	for _, pkt := range packetList {
+		require.Contains(t, TPacketData, pkt)
+		for _, wanted := range TPacketData[pkt] {
+			t.Run(fmt.Sprintf("%s %s", PacketNames[pkt], wanted.Desc), func(t *testing.T) {
+				if !encodeTestOK(wanted) {
+					return
+				}
+
+				pk := new(Packet)
+				_ = copier.Copy(pk, wanted.Packet)
+				require.Equal(t, pkt, pk.FixedHeader.Type, pkInfo, pkt, wanted.Desc)
+
+				pk.Mods.AllowResponseInfo = true
+
+				buf := new(bytes.Buffer)
+				var err error
+				switch pkt {
+				case Connect:
+					err = pk.ConnectEncode(buf)
+				case Connack:
+					err = pk.ConnackEncode(buf)
+				case Publish:
+					err = pk.PublishEncode(buf)
+				case Puback:
+					err = pk.PubackEncode(buf)
+				case Pubrec:
+					err = pk.PubrecEncode(buf)
+				case Pubrel:
+					err = pk.PubrelEncode(buf)
+				case Pubcomp:
+					err = pk.PubcompEncode(buf)
+				case Subscribe:
+					err = pk.SubscribeEncode(buf)
+				case Suback:
+					err = pk.SubackEncode(buf)
+				case Unsubscribe:
+					err = pk.UnsubscribeEncode(buf)
+				case Unsuback:
+					err = pk.UnsubackEncode(buf)
+				case Pingreq:
+					err = pk.PingreqEncode(buf)
+				case Pingresp:
+					err = pk.PingrespEncode(buf)
+				case Disconnect:
+					err = pk.DisconnectEncode(buf)
+				case Auth:
+					err = pk.AuthEncode(buf)
+				}
+				if wanted.Expect != nil {
+					require.Error(t, err, pkInfo, pkt, wanted.Desc)
+					return
+				}
+
+				require.NoError(t, err, pkInfo, pkt, wanted.Desc)
+				encoded := buf.Bytes()
+
+				// If ActualBytes is set, compare mutated version of byte string instead (to avoid length mismatches, etc).
+				if len(wanted.ActualBytes) > 0 {
+					wanted.RawBytes = wanted.ActualBytes
+				}
+				require.EqualValues(t, wanted.RawBytes, encoded, pkInfo, pkt, wanted.Desc)
+			})
+		}
+	}
+}
+
+func TestPacketDecode(t *testing.T) {
+	for _, pkt := range packetList {
+		require.Contains(t, TPacketData, pkt)
+		for _, wanted := range TPacketData[pkt] {
+			t.Run(fmt.Sprintf("%s %s", PacketNames[pkt], wanted.Desc), func(t *testing.T) {
+				if !decodeTestOK(wanted) {
+					return
+				}
+
+				pk := &Packet{FixedHeader: FixedHeader{Type: pkt}}
+				pk.Mods.AllowResponseInfo = true
+				_ = pk.FixedHeader.Decode(wanted.RawBytes[0])
+				if len(wanted.RawBytes) > 0 {
+					pk.FixedHeader.Remaining = int(wanted.RawBytes[1])
+				}
+
+				if wanted.Packet != nil && wanted.Packet.ProtocolVersion != 0 {
+					pk.ProtocolVersion = wanted.Packet.ProtocolVersion
+				}
+
+				buf := wanted.RawBytes[2:]
+				var err error
+				switch pkt {
+				case Connect:
+					err = pk.ConnectDecode(buf)
+				case Connack:
+					err = pk.ConnackDecode(buf)
+				case Publish:
+					err = pk.PublishDecode(buf)
+				case Puback:
+					err = pk.PubackDecode(buf)
+				case Pubrec:
+					err = pk.PubrecDecode(buf)
+				case Pubrel:
+					err = pk.PubrelDecode(buf)
+				case Pubcomp:
+					err = pk.PubcompDecode(buf)
+				case Subscribe:
+					err = pk.SubscribeDecode(buf)
+				case Suback:
+					err = pk.SubackDecode(buf)
+				case Unsubscribe:
+					err = pk.UnsubscribeDecode(buf)
+				case Unsuback:
+					err = pk.UnsubackDecode(buf)
+				case Pingreq:
+					err = pk.PingreqDecode(buf)
+				case Pingresp:
+					err = pk.PingrespDecode(buf)
+				case Disconnect:
+					err = pk.DisconnectDecode(buf)
+				case Auth:
+					err = pk.AuthDecode(buf)
+				}
+
+				if wanted.FailFirst != nil {
+					require.Error(t, err, pkInfo, pkt, wanted.Desc)
+					require.ErrorIs(t, err, wanted.FailFirst, pkInfo, pkt, wanted.Desc)
+					return
+				}
+
+				require.NoError(t, err, pkInfo, pkt, wanted.Desc)
+
+				require.EqualValues(t, wanted.Packet.Filters, pk.Filters, pkInfo, pkt, wanted.Desc)
+
+				require.Equal(t, wanted.Packet.FixedHeader.Type, pk.FixedHeader.Type, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.FixedHeader.Dup, pk.FixedHeader.Dup, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.FixedHeader.Qos, pk.FixedHeader.Qos, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.FixedHeader.Retain, pk.FixedHeader.Retain, pkInfo, pkt, wanted.Desc)
+
+				if pkt == Connect {
+					// we use ProtocolVersion for controlling packet encoding, but we don't need to test
+					// against it unless it's a connect packet.
+					require.Equal(t, wanted.Packet.ProtocolVersion, pk.ProtocolVersion, pkInfo, pkt, wanted.Desc)
+				}
+				require.Equal(t, wanted.Packet.Connect.ProtocolName, pk.Connect.ProtocolName, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.Clean, pk.Connect.Clean, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.ClientIdentifier, pk.Connect.ClientIdentifier, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.Keepalive, pk.Connect.Keepalive, pkInfo, pkt, wanted.Desc)
+
+				require.Equal(t, wanted.Packet.Connect.UsernameFlag, pk.Connect.UsernameFlag, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.Username, pk.Connect.Username, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.PasswordFlag, pk.Connect.PasswordFlag, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.Password, pk.Connect.Password, pkInfo, pkt, wanted.Desc)
+
+				require.Equal(t, wanted.Packet.Connect.WillFlag, pk.Connect.WillFlag, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.WillTopic, pk.Connect.WillTopic, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.WillPayload, pk.Connect.WillPayload, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.WillQos, pk.Connect.WillQos, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.Connect.WillRetain, pk.Connect.WillRetain, pkInfo, pkt, wanted.Desc)
+
+				require.Equal(t, wanted.Packet.ReasonCodes, pk.ReasonCodes, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.ReasonCode, pk.ReasonCode, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.SessionPresent, pk.SessionPresent, pkInfo, pkt, wanted.Desc)
+				require.Equal(t, wanted.Packet.PacketID, pk.PacketID, pkInfo, pkt, wanted.Desc)
+
+				require.EqualValues(t, wanted.Packet.Properties, pk.Properties)
+				require.EqualValues(t, wanted.Packet.Connect.WillProperties, pk.Connect.WillProperties)
+			})
+		}
+	}
+}
+
+func TestValidate(t *testing.T) {
+	for _, pkt := range packetList {
+		require.Contains(t, TPacketData, pkt)
+		for _, wanted := range TPacketData[pkt] {
+			t.Run(fmt.Sprintf("%s %s", PacketNames[pkt], wanted.Desc), func(t *testing.T) {
+				if wanted.Group == "validate" || wanted.Primary {
+					pk := wanted.Packet
+					var err error
+					switch pkt {
+					case Connect:
+						err = pk.ConnectValidate()
+					case Publish:
+						err = pk.PublishValidate(1024)
+					case Subscribe:
+						err = pk.SubscribeValidate()
+					case Unsubscribe:
+						err = pk.UnsubscribeValidate()
+					case Auth:
+						err = pk.AuthValidate()
+					}
+
+					if wanted.Expect != nil {
+						require.Error(t, err, pkInfo, pkt, wanted.Desc)
+						require.ErrorIs(t, wanted.Expect, err, pkInfo, pkt, wanted.Desc)
+					}
+				}
+			})
+		}
+	}
+}
+
+func TestAckValidatePubrec(t *testing.T) {
+	for _, b := range []byte{
+		CodeSuccess.Code,
+		CodeNoMatchingSubscribers.Code,
+		ErrUnspecifiedError.Code,
+		ErrImplementationSpecificError.Code,
+		ErrNotAuthorized.Code,
+		ErrTopicNameInvalid.Code,
+		ErrPacketIdentifierInUse.Code,
+		ErrQuotaExceeded.Code,
+		ErrPayloadFormatInvalid.Code,
+	} {
+		pk := Packet{FixedHeader: FixedHeader{Type: Pubrec}, ReasonCode: b}
+		require.True(t, pk.ReasonCodeValid())
+	}
+	pk := Packet{FixedHeader: FixedHeader{Type: Pubrec}, ReasonCode: ErrClientIdentifierTooLong.Code}
+	require.False(t, pk.ReasonCodeValid())
+}
+
+func TestAckValidatePubrel(t *testing.T) {
+	for _, b := range []byte{
+		CodeSuccess.Code,
+		ErrPacketIdentifierNotFound.Code,
+	} {
+		pk := Packet{FixedHeader: FixedHeader{Type: Pubrel}, ReasonCode: b}
+		require.True(t, pk.ReasonCodeValid())
+	}
+	pk := Packet{FixedHeader: FixedHeader{Type: Pubrel}, ReasonCode: ErrClientIdentifierTooLong.Code}
+	require.False(t, pk.ReasonCodeValid())
+}
+
+func TestAckValidatePubcomp(t *testing.T) {
+	for _, b := range []byte{
+		CodeSuccess.Code,
+		ErrPacketIdentifierNotFound.Code,
+	} {
+		pk := Packet{FixedHeader: FixedHeader{Type: Pubcomp}, ReasonCode: b}
+		require.True(t, pk.ReasonCodeValid())
+	}
+	pk := Packet{FixedHeader: FixedHeader{Type: Pubrel}, ReasonCode: ErrClientIdentifierTooLong.Code}
+	require.False(t, pk.ReasonCodeValid())
+}
+
+func TestAckValidateSuback(t *testing.T) {
+	for _, b := range []byte{
+		CodeGrantedQos0.Code,
+		CodeGrantedQos1.Code,
+		CodeGrantedQos2.Code,
+		ErrUnspecifiedError.Code,
+		ErrImplementationSpecificError.Code,
+		ErrNotAuthorized.Code,
+		ErrTopicFilterInvalid.Code,
+		ErrPacketIdentifierInUse.Code,
+		ErrQuotaExceeded.Code,
+		ErrSharedSubscriptionsNotSupported.Code,
+		ErrSubscriptionIdentifiersNotSupported.Code,
+		ErrWildcardSubscriptionsNotSupported.Code,
+	} {
+		pk := Packet{FixedHeader: FixedHeader{Type: Suback}, ReasonCode: b}
+		require.True(t, pk.ReasonCodeValid())
+	}
+
+	pk := Packet{FixedHeader: FixedHeader{Type: Suback}, ReasonCode: ErrClientIdentifierTooLong.Code}
+	require.False(t, pk.ReasonCodeValid())
+}
+
+func TestAckValidateUnsuback(t *testing.T) {
+	for _, b := range []byte{
+		CodeSuccess.Code,
+		CodeNoSubscriptionExisted.Code,
+		ErrUnspecifiedError.Code,
+		ErrImplementationSpecificError.Code,
+		ErrNotAuthorized.Code,
+		ErrTopicFilterInvalid.Code,
+		ErrPacketIdentifierInUse.Code,
+	} {
+		pk := Packet{FixedHeader: FixedHeader{Type: Unsuback}, ReasonCode: b}
+		require.True(t, pk.ReasonCodeValid())
+	}
+
+	pk := Packet{FixedHeader: FixedHeader{Type: Unsuback}, ReasonCode: ErrClientIdentifierTooLong.Code}
+	require.False(t, pk.ReasonCodeValid())
+}
+
+func TestReasonCodeValidMisc(t *testing.T) {
+	pk := Packet{FixedHeader: FixedHeader{Type: Connack}, ReasonCode: CodeSuccess.Code}
+	require.True(t, pk.ReasonCodeValid())
+}
+
+func TestCopy(t *testing.T) {
+	for _, tt := range pkTable {
+		pkc := tt.Packet.Copy(true)
+
+		require.Equal(t, tt.Packet.FixedHeader.Qos, pkc.FixedHeader.Qos, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, false, pkc.FixedHeader.Dup, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, false, pkc.FixedHeader.Retain, pkInfo, tt.Case, tt.Desc)
+
+		require.Equal(t, tt.Packet.TopicName, pkc.TopicName, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.ClientIdentifier, pkc.Connect.ClientIdentifier, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.Keepalive, pkc.Connect.Keepalive, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.ProtocolVersion, pkc.ProtocolVersion, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.PasswordFlag, pkc.Connect.PasswordFlag, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.UsernameFlag, pkc.Connect.UsernameFlag, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.WillQos, pkc.Connect.WillQos, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.WillTopic, pkc.Connect.WillTopic, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.WillFlag, pkc.Connect.WillFlag, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.WillRetain, pkc.Connect.WillRetain, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.WillProperties, pkc.Connect.WillProperties, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Properties, pkc.Properties, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.Clean, pkc.Connect.Clean, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.SessionPresent, pkc.SessionPresent, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.ReasonCode, pkc.ReasonCode, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.PacketID, pkc.PacketID, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Filters, pkc.Filters, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Payload, pkc.Payload, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.Password, pkc.Connect.Password, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.Username, pkc.Connect.Username, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.ProtocolName, pkc.Connect.ProtocolName, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Connect.WillPayload, pkc.Connect.WillPayload, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.ReasonCodes, pkc.ReasonCodes, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Created, pkc.Created, pkInfo, tt.Case, tt.Desc)
+		require.Equal(t, tt.Packet.Origin, pkc.Origin, pkInfo, tt.Case, tt.Desc)
+		require.EqualValues(t, pkc.Properties, tt.Packet.Properties)
+
+		pkcc := tt.Packet.Copy(false)
+		require.Equal(t, uint16(0), pkcc.PacketID, pkInfo, tt.Case, tt.Desc)
+	}
+}
+
+func TestMergeSubscription(t *testing.T) {
+	sub := Subscription{
+		Filter:            "a/b/c",
+		RetainHandling:    0,
+		Qos:               0,
+		RetainAsPublished: false,
+		NoLocal:           false,
+		Identifier:        1,
+	}
+
+	sub2 := Subscription{
+		Filter:            "a/b/d",
+		RetainHandling:    0,
+		Qos:               2,
+		RetainAsPublished: false,
+		NoLocal:           true,
+		Identifier:        2,
+	}
+
+	expect := Subscription{
+		Filter:            "a/b/c",
+		RetainHandling:    0,
+		Qos:               2,
+		RetainAsPublished: false,
+		NoLocal:           true,
+		Identifier:        1,
+		Identifiers: map[string]int{
+			"a/b/c": 1,
+			"a/b/d": 2,
+		},
+	}
+	require.Equal(t, expect, sub.Merge(sub2))
+}

packets/properties.go

@@ -0,0 +1,481 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+import (
+	"bytes"
+	"fmt"
+	"strings"
+
+	"github.com/mochi-mqtt/server/v2/mempool"
+)
+
+const (
+	PropPayloadFormat          byte = 1
+	PropMessageExpiryInterval  byte = 2
+	PropContentType            byte = 3
+	PropResponseTopic          byte = 8
+	PropCorrelationData        byte = 9
+	PropSubscriptionIdentifier byte = 11
+	PropSessionExpiryInterval  byte = 17
+	PropAssignedClientID       byte = 18
+	PropServerKeepAlive        byte = 19
+	PropAuthenticationMethod   byte = 21
+	PropAuthenticationData     byte = 22
+	PropRequestProblemInfo     byte = 23
+	PropWillDelayInterval      byte = 24
+	PropRequestResponseInfo    byte = 25
+	PropResponseInfo           byte = 26
+	PropServerReference        byte = 28
+	PropReasonString           byte = 31
+	PropReceiveMaximum         byte = 33
+	PropTopicAliasMaximum      byte = 34
+	PropTopicAlias             byte = 35
+	PropMaximumQos             byte = 36
+	PropRetainAvailable        byte = 37
+	PropUser                   byte = 38
+	PropMaximumPacketSize      byte = 39
+	PropWildcardSubAvailable   byte = 40
+	PropSubIDAvailable         byte = 41
+	PropSharedSubAvailable     byte = 42
+)
+
+// validPacketProperties indicates which properties are valid for which packet types.
+var validPacketProperties = map[byte]map[byte]byte{
+	PropPayloadFormat:          {Publish: 1, WillProperties: 1},
+	PropMessageExpiryInterval:  {Publish: 1, WillProperties: 1},
+	PropContentType:            {Publish: 1, WillProperties: 1},
+	PropResponseTopic:          {Publish: 1, WillProperties: 1},
+	PropCorrelationData:        {Publish: 1, WillProperties: 1},
+	PropSubscriptionIdentifier: {Publish: 1, Subscribe: 1},
+	PropSessionExpiryInterval:  {Connect: 1, Connack: 1, Disconnect: 1},
+	PropAssignedClientID:       {Connack: 1},
+	PropServerKeepAlive:        {Connack: 1},
+	PropAuthenticationMethod:   {Connect: 1, Connack: 1, Auth: 1},
+	PropAuthenticationData:     {Connect: 1, Connack: 1, Auth: 1},
+	PropRequestProblemInfo:     {Connect: 1},
+	PropWillDelayInterval:      {WillProperties: 1},
+	PropRequestResponseInfo:    {Connect: 1},
+	PropResponseInfo:           {Connack: 1},
+	PropServerReference:        {Connack: 1, Disconnect: 1},
+	PropReasonString:           {Connack: 1, Puback: 1, Pubrec: 1, Pubrel: 1, Pubcomp: 1, Suback: 1, Unsuback: 1, Disconnect: 1, Auth: 1},
+	PropReceiveMaximum:         {Connect: 1, Connack: 1},
+	PropTopicAliasMaximum:      {Connect: 1, Connack: 1},
+	PropTopicAlias:             {Publish: 1},
+	PropMaximumQos:             {Connack: 1},
+	PropRetainAvailable:        {Connack: 1},
+	PropUser:                   {Connect: 1, Connack: 1, Publish: 1, Puback: 1, Pubrec: 1, Pubrel: 1, Pubcomp: 1, Subscribe: 1, Suback: 1, Unsubscribe: 1, Unsuback: 1, Disconnect: 1, Auth: 1, WillProperties: 1},
+	PropMaximumPacketSize:      {Connect: 1, Connack: 1},
+	PropWildcardSubAvailable:   {Connack: 1},
+	PropSubIDAvailable:         {Connack: 1},
+	PropSharedSubAvailable:     {Connack: 1},
+}
+
+// UserProperty is an arbitrary key-value pair for a packet user properties array.
+type UserProperty struct { // [MQTT-1.5.7-1]
+	Key string `json:"k"`
+	Val string `json:"v"`
+}
+
+// Properties contains all mqtt v5 properties available for a packet.
+// Some properties have valid values of 0 or not-present. In this case, we opt for
+// property flags to indicate the usage of property.
+// Refer to mqtt v5 2.2.2.2 Property spec for more information.
+type Properties struct {
+	CorrelationData           []byte         `json:"cd"`
+	SubscriptionIdentifier    []int          `json:"si"`
+	AuthenticationData        []byte         `json:"ad"`
+	User                      []UserProperty `json:"user"`
+	ContentType               string         `json:"ct"`
+	ResponseTopic             string         `json:"rt"`
+	AssignedClientID          string         `json:"aci"`
+	AuthenticationMethod      string         `json:"am"`
+	ResponseInfo              string         `json:"ri"`
+	ServerReference           string         `json:"sr"`
+	ReasonString              string         `json:"rs"`
+	MessageExpiryInterval     uint32         `json:"me"`
+	SessionExpiryInterval     uint32         `json:"sei"`
+	WillDelayInterval         uint32         `json:"wdi"`
+	MaximumPacketSize         uint32         `json:"mps"`
+	ServerKeepAlive           uint16         `json:"ska"`
+	ReceiveMaximum            uint16         `json:"rm"`
+	TopicAliasMaximum         uint16         `json:"tam"`
+	TopicAlias                uint16         `json:"ta"`
+	PayloadFormat             byte           `json:"pf"`
+	PayloadFormatFlag         bool           `json:"fpf"`
+	SessionExpiryIntervalFlag bool           `json:"fsei"`
+	ServerKeepAliveFlag       bool           `json:"fska"`
+	RequestProblemInfo        byte           `json:"rpi"`
+	RequestProblemInfoFlag    bool           `json:"frpi"`
+	RequestResponseInfo       byte           `json:"rri"`
+	TopicAliasFlag            bool           `json:"fta"`
+	MaximumQos                byte           `json:"mqos"`
+	MaximumQosFlag            bool           `json:"fmqos"`
+	RetainAvailable           byte           `json:"ra"`
+	RetainAvailableFlag       bool           `json:"fra"`
+	WildcardSubAvailable      byte           `json:"wsa"`
+	WildcardSubAvailableFlag  bool           `json:"fwsa"`
+	SubIDAvailable            byte           `json:"sida"`
+	SubIDAvailableFlag        bool           `json:"fsida"`
+	SharedSubAvailable        byte           `json:"ssa"`
+	SharedSubAvailableFlag    bool           `json:"fssa"`
+}
+
+// Copy creates a new Properties struct with copies of the values.
+func (p *Properties) Copy(allowTransfer bool) Properties {
+	pr := Properties{
+		PayloadFormat:             p.PayloadFormat, // [MQTT-3.3.2-4]
+		PayloadFormatFlag:         p.PayloadFormatFlag,
+		MessageExpiryInterval:     p.MessageExpiryInterval,
+		ContentType:               p.ContentType,   // [MQTT-3.3.2-20]
+		ResponseTopic:             p.ResponseTopic, // [MQTT-3.3.2-15]
+		SessionExpiryInterval:     p.SessionExpiryInterval,
+		SessionExpiryIntervalFlag: p.SessionExpiryIntervalFlag,
+		AssignedClientID:          p.AssignedClientID,
+		ServerKeepAlive:           p.ServerKeepAlive,
+		ServerKeepAliveFlag:       p.ServerKeepAliveFlag,
+		AuthenticationMethod:      p.AuthenticationMethod,
+		RequestProblemInfo:        p.RequestProblemInfo,
+		RequestProblemInfoFlag:    p.RequestProblemInfoFlag,
+		WillDelayInterval:         p.WillDelayInterval,
+		RequestResponseInfo:       p.RequestResponseInfo,
+		ResponseInfo:              p.ResponseInfo,
+		ServerReference:           p.ServerReference,
+		ReasonString:              p.ReasonString,
+		ReceiveMaximum:            p.ReceiveMaximum,
+		TopicAliasMaximum:         p.TopicAliasMaximum,
+		TopicAlias:                0, // NB; do not copy topic alias [MQTT-3.3.2-7] + we do not send to clients (currently) [MQTT-3.1.2-26] [MQTT-3.1.2-27]
+		MaximumQos:                p.MaximumQos,
+		MaximumQosFlag:            p.MaximumQosFlag,
+		RetainAvailable:           p.RetainAvailable,
+		RetainAvailableFlag:       p.RetainAvailableFlag,
+		MaximumPacketSize:         p.MaximumPacketSize,
+		WildcardSubAvailable:      p.WildcardSubAvailable,
+		WildcardSubAvailableFlag:  p.WildcardSubAvailableFlag,
+		SubIDAvailable:            p.SubIDAvailable,
+		SubIDAvailableFlag:        p.SubIDAvailableFlag,
+		SharedSubAvailable:        p.SharedSubAvailable,
+		SharedSubAvailableFlag:    p.SharedSubAvailableFlag,
+	}
+
+	if allowTransfer {
+		pr.TopicAlias = p.TopicAlias
+		pr.TopicAliasFlag = p.TopicAliasFlag
+	}
+
+	if len(p.CorrelationData) > 0 {
+		pr.CorrelationData = append([]byte{}, p.CorrelationData...) // [MQTT-3.3.2-16]
+	}
+
+	if len(p.SubscriptionIdentifier) > 0 {
+		pr.SubscriptionIdentifier = append([]int{}, p.SubscriptionIdentifier...)
+	}
+
+	if len(p.AuthenticationData) > 0 {
+		pr.AuthenticationData = append([]byte{}, p.AuthenticationData...)
+	}
+
+	if len(p.User) > 0 {
+		pr.User = []UserProperty{}
+		for _, v := range p.User {
+			pr.User = append(pr.User, UserProperty{ // [MQTT-3.3.2-17]
+				Key: v.Key,
+				Val: v.Val,
+			})
+		}
+	}
+
+	return pr
+}
+
+// canEncode returns true if the property type is valid for the packet type.
+func (p *Properties) canEncode(pkt byte, k byte) bool {
+	return validPacketProperties[k][pkt] == 1
+}
+
+// Encode encodes properties into a bytes buffer.
+func (p *Properties) Encode(pkt byte, mods Mods, b *bytes.Buffer, n int) {
+	if p == nil {
+		return
+	}
+
+	buf := mempool.GetBuffer()
+	defer mempool.PutBuffer(buf)
+	if p.canEncode(pkt, PropPayloadFormat) && p.PayloadFormatFlag {
+		buf.WriteByte(PropPayloadFormat)
+		buf.WriteByte(p.PayloadFormat)
+	}
+
+	if p.canEncode(pkt, PropMessageExpiryInterval) && p.MessageExpiryInterval > 0 {
+		buf.WriteByte(PropMessageExpiryInterval)
+		buf.Write(encodeUint32(p.MessageExpiryInterval))
+	}
+
+	if p.canEncode(pkt, PropContentType) && p.ContentType != "" {
+		buf.WriteByte(PropContentType)
+		buf.Write(encodeString(p.ContentType)) // [MQTT-3.3.2-19]
+	}
+
+	if mods.AllowResponseInfo && p.canEncode(pkt, PropResponseTopic) && //  [MQTT-3.3.2-14]
+		p.ResponseTopic != "" && !strings.ContainsAny(p.ResponseTopic, "+#") { // [MQTT-3.1.2-28]
+		buf.WriteByte(PropResponseTopic)
+		buf.Write(encodeString(p.ResponseTopic)) // [MQTT-3.3.2-13]
+	}
+
+	if mods.AllowResponseInfo && p.canEncode(pkt, PropCorrelationData) && len(p.CorrelationData) > 0 { // [MQTT-3.1.2-28]
+		buf.WriteByte(PropCorrelationData)
+		buf.Write(encodeBytes(p.CorrelationData))
+	}
+
+	if p.canEncode(pkt, PropSubscriptionIdentifier) && len(p.SubscriptionIdentifier) > 0 {
+		for _, v := range p.SubscriptionIdentifier {
+			if v > 0 {
+				buf.WriteByte(PropSubscriptionIdentifier)
+				encodeLength(buf, int64(v))
+			}
+		}
+	}
+
+	if p.canEncode(pkt, PropSessionExpiryInterval) && p.SessionExpiryIntervalFlag { // [MQTT-3.14.2-2]
+		buf.WriteByte(PropSessionExpiryInterval)
+		buf.Write(encodeUint32(p.SessionExpiryInterval))
+	}
+
+	if p.canEncode(pkt, PropAssignedClientID) && p.AssignedClientID != "" {
+		buf.WriteByte(PropAssignedClientID)
+		buf.Write(encodeString(p.AssignedClientID))
+	}
+
+	if p.canEncode(pkt, PropServerKeepAlive) && p.ServerKeepAliveFlag {
+		buf.WriteByte(PropServerKeepAlive)
+		buf.Write(encodeUint16(p.ServerKeepAlive))
+	}
+
+	if p.canEncode(pkt, PropAuthenticationMethod) && p.AuthenticationMethod != "" {
+		buf.WriteByte(PropAuthenticationMethod)
+		buf.Write(encodeString(p.AuthenticationMethod))
+	}
+
+	if p.canEncode(pkt, PropAuthenticationData) && len(p.AuthenticationData) > 0 {
+		buf.WriteByte(PropAuthenticationData)
+		buf.Write(encodeBytes(p.AuthenticationData))
+	}
+
+	if p.canEncode(pkt, PropRequestProblemInfo) && p.RequestProblemInfoFlag {
+		buf.WriteByte(PropRequestProblemInfo)
+		buf.WriteByte(p.RequestProblemInfo)
+	}
+
+	if p.canEncode(pkt, PropWillDelayInterval) && p.WillDelayInterval > 0 {
+		buf.WriteByte(PropWillDelayInterval)
+		buf.Write(encodeUint32(p.WillDelayInterval))
+	}
+
+	if p.canEncode(pkt, PropRequestResponseInfo) && p.RequestResponseInfo > 0 {
+		buf.WriteByte(PropRequestResponseInfo)
+		buf.WriteByte(p.RequestResponseInfo)
+	}
+
+	if mods.AllowResponseInfo && p.canEncode(pkt, PropResponseInfo) && len(p.ResponseInfo) > 0 { // [MQTT-3.1.2-28]
+		buf.WriteByte(PropResponseInfo)
+		buf.Write(encodeString(p.ResponseInfo))
+	}
+
+	if p.canEncode(pkt, PropServerReference) && len(p.ServerReference) > 0 {
+		buf.WriteByte(PropServerReference)
+		buf.Write(encodeString(p.ServerReference))
+	}
+
+	// [MQTT-3.2.2-19] [MQTT-3.14.2-3] [MQTT-3.4.2-2] [MQTT-3.5.2-2]
+	// [MQTT-3.6.2-2] [MQTT-3.9.2-1] [MQTT-3.11.2-1] [MQTT-3.15.2-2]
+	if !mods.DisallowProblemInfo && p.canEncode(pkt, PropReasonString) && p.ReasonString != "" {
+		b := encodeString(p.ReasonString)
+		if mods.MaxSize == 0 || uint32(n+len(b)+1) < mods.MaxSize {
+			buf.WriteByte(PropReasonString)
+			buf.Write(b)
+		}
+	}
+
+	if p.canEncode(pkt, PropReceiveMaximum) && p.ReceiveMaximum > 0 {
+		buf.WriteByte(PropReceiveMaximum)
+		buf.Write(encodeUint16(p.ReceiveMaximum))
+	}
+
+	if p.canEncode(pkt, PropTopicAliasMaximum) && p.TopicAliasMaximum > 0 {
+		buf.WriteByte(PropTopicAliasMaximum)
+		buf.Write(encodeUint16(p.TopicAliasMaximum))
+	}
+
+	if p.canEncode(pkt, PropTopicAlias) && p.TopicAliasFlag && p.TopicAlias > 0 { // [MQTT-3.3.2-8]
+		buf.WriteByte(PropTopicAlias)
+		buf.Write(encodeUint16(p.TopicAlias))
+	}
+
+	if p.canEncode(pkt, PropMaximumQos) && p.MaximumQosFlag && p.MaximumQos < 2 {
+		buf.WriteByte(PropMaximumQos)
+		buf.WriteByte(p.MaximumQos)
+	}
+
+	if p.canEncode(pkt, PropRetainAvailable) && p.RetainAvailableFlag {
+		buf.WriteByte(PropRetainAvailable)
+		buf.WriteByte(p.RetainAvailable)
+	}
+
+	if !mods.DisallowProblemInfo && p.canEncode(pkt, PropUser) {
+		pb := mempool.GetBuffer()
+		defer mempool.PutBuffer(pb)
+		for _, v := range p.User {
+			pb.WriteByte(PropUser)
+			pb.Write(encodeString(v.Key))
+			pb.Write(encodeString(v.Val))
+		}
+		// [MQTT-3.2.2-20] [MQTT-3.14.2-4] [MQTT-3.4.2-3] [MQTT-3.5.2-3]
+		// [MQTT-3.6.2-3] [MQTT-3.9.2-2] [MQTT-3.11.2-2] [MQTT-3.15.2-3]
+		if mods.MaxSize == 0 || uint32(n+pb.Len()+1) < mods.MaxSize {
+			buf.Write(pb.Bytes())
+		}
+	}
+
+	if p.canEncode(pkt, PropMaximumPacketSize) && p.MaximumPacketSize > 0 {
+		buf.WriteByte(PropMaximumPacketSize)
+		buf.Write(encodeUint32(p.MaximumPacketSize))
+	}
+
+	if p.canEncode(pkt, PropWildcardSubAvailable) && p.WildcardSubAvailableFlag {
+		buf.WriteByte(PropWildcardSubAvailable)
+		buf.WriteByte(p.WildcardSubAvailable)
+	}
+
+	if p.canEncode(pkt, PropSubIDAvailable) && p.SubIDAvailableFlag {
+		buf.WriteByte(PropSubIDAvailable)
+		buf.WriteByte(p.SubIDAvailable)
+	}
+
+	if p.canEncode(pkt, PropSharedSubAvailable) && p.SharedSubAvailableFlag {
+		buf.WriteByte(PropSharedSubAvailable)
+		buf.WriteByte(p.SharedSubAvailable)
+	}
+
+	encodeLength(b, int64(buf.Len()))
+	b.Write(buf.Bytes()) // [MQTT-3.1.3-10]
+}
+
+// Decode decodes property bytes into a properties struct.
+func (p *Properties) Decode(pkt byte, b *bytes.Buffer) (n int, err error) {
+	if p == nil {
+		return 0, nil
+	}
+
+	var bu int
+	n, bu, err = DecodeLength(b)
+	if err != nil {
+		return n + bu, err
+	}
+
+	if n == 0 {
+		return n + bu, nil
+	}
+
+	bt := b.Bytes()
+	var k byte
+	for offset := 0; offset < n; {
+		k, offset, err = decodeByte(bt, offset)
+		if err != nil {
+			return n + bu, err
+		}
+
+		if _, ok := validPacketProperties[k][pkt]; !ok {
+			return n + bu, fmt.Errorf("property type %v not valid for packet type %v: %w", k, pkt, ErrProtocolViolationUnsupportedProperty)
+		}
+
+		switch k {
+		case PropPayloadFormat:
+			p.PayloadFormat, offset, err = decodeByte(bt, offset)
+			p.PayloadFormatFlag = true
+		case PropMessageExpiryInterval:
+			p.MessageExpiryInterval, offset, err = decodeUint32(bt, offset)
+		case PropContentType:
+			p.ContentType, offset, err = decodeString(bt, offset)
+		case PropResponseTopic:
+			p.ResponseTopic, offset, err = decodeString(bt, offset)
+		case PropCorrelationData:
+			p.CorrelationData, offset, err = decodeBytes(bt, offset)
+		case PropSubscriptionIdentifier:
+			if p.SubscriptionIdentifier == nil {
+				p.SubscriptionIdentifier = []int{}
+			}
+
+			n, bu, err := DecodeLength(bytes.NewBuffer(bt[offset:]))
+			if err != nil {
+				return n + bu, err
+			}
+			p.SubscriptionIdentifier = append(p.SubscriptionIdentifier, n)
+			offset += bu
+		case PropSessionExpiryInterval:
+			p.SessionExpiryInterval, offset, err = decodeUint32(bt, offset)
+			p.SessionExpiryIntervalFlag = true
+		case PropAssignedClientID:
+			p.AssignedClientID, offset, err = decodeString(bt, offset)
+		case PropServerKeepAlive:
+			p.ServerKeepAlive, offset, err = decodeUint16(bt, offset)
+			p.ServerKeepAliveFlag = true
+		case PropAuthenticationMethod:
+			p.AuthenticationMethod, offset, err = decodeString(bt, offset)
+		case PropAuthenticationData:
+			p.AuthenticationData, offset, err = decodeBytes(bt, offset)
+		case PropRequestProblemInfo:
+			p.RequestProblemInfo, offset, err = decodeByte(bt, offset)
+			p.RequestProblemInfoFlag = true
+		case PropWillDelayInterval:
+			p.WillDelayInterval, offset, err = decodeUint32(bt, offset)
+		case PropRequestResponseInfo:
+			p.RequestResponseInfo, offset, err = decodeByte(bt, offset)
+		case PropResponseInfo:
+			p.ResponseInfo, offset, err = decodeString(bt, offset)
+		case PropServerReference:
+			p.ServerReference, offset, err = decodeString(bt, offset)
+		case PropReasonString:
+			p.ReasonString, offset, err = decodeString(bt, offset)
+		case PropReceiveMaximum:
+			p.ReceiveMaximum, offset, err = decodeUint16(bt, offset)
+		case PropTopicAliasMaximum:
+			p.TopicAliasMaximum, offset, err = decodeUint16(bt, offset)
+		case PropTopicAlias:
+			p.TopicAlias, offset, err = decodeUint16(bt, offset)
+			p.TopicAliasFlag = true
+		case PropMaximumQos:
+			p.MaximumQos, offset, err = decodeByte(bt, offset)
+			p.MaximumQosFlag = true
+		case PropRetainAvailable:
+			p.RetainAvailable, offset, err = decodeByte(bt, offset)
+			p.RetainAvailableFlag = true
+		case PropUser:
+			var k, v string
+			k, offset, err = decodeString(bt, offset)
+			if err != nil {
+				return n + bu, err
+			}
+			v, offset, err = decodeString(bt, offset)
+			p.User = append(p.User, UserProperty{Key: k, Val: v})
+		case PropMaximumPacketSize:
+			p.MaximumPacketSize, offset, err = decodeUint32(bt, offset)
+		case PropWildcardSubAvailable:
+			p.WildcardSubAvailable, offset, err = decodeByte(bt, offset)
+			p.WildcardSubAvailableFlag = true
+		case PropSubIDAvailable:
+			p.SubIDAvailable, offset, err = decodeByte(bt, offset)
+			p.SubIDAvailableFlag = true
+		case PropSharedSubAvailable:
+			p.SharedSubAvailable, offset, err = decodeByte(bt, offset)
+			p.SharedSubAvailableFlag = true
+		}
+
+		if err != nil {
+			return n + bu, err
+		}
+	}
+
+	return n + bu, nil
+}

packets/properties_test.go

@@ -0,0 +1,333 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+var (
+	propertiesStruct = Properties{
+		PayloadFormat:             byte(1), // UTF-8 Format
+		PayloadFormatFlag:         true,
+		MessageExpiryInterval:     uint32(2),
+		ContentType:               "text/plain",
+		ResponseTopic:             "a/b/c",
+		CorrelationData:           []byte("data"),
+		SubscriptionIdentifier:    []int{322122},
+		SessionExpiryInterval:     uint32(120),
+		SessionExpiryIntervalFlag: true,
+		AssignedClientID:          "mochi-v5",
+		ServerKeepAlive:           uint16(20),
+		ServerKeepAliveFlag:       true,
+		AuthenticationMethod:      "SHA-1",
+		AuthenticationData:        []byte("auth-data"),
+		RequestProblemInfo:        byte(1),
+		RequestProblemInfoFlag:    true,
+		WillDelayInterval:         uint32(600),
+		RequestResponseInfo:       byte(1),
+		ResponseInfo:              "response",
+		ServerReference:           "mochi-2",
+		ReasonString:              "reason",
+		ReceiveMaximum:            uint16(500),
+		TopicAliasMaximum:         uint16(999),
+		TopicAlias:                uint16(3),
+		TopicAliasFlag:            true,
+		MaximumQos:                byte(1),
+		MaximumQosFlag:            true,
+		RetainAvailable:           byte(1),
+		RetainAvailableFlag:       true,
+		User: []UserProperty{
+			{
+				Key: "hello",
+				Val: "世界",
+			},
+			{
+				Key: "key2",
+				Val: "value2",
+			},
+		},
+		MaximumPacketSize:        uint32(32000),
+		WildcardSubAvailable:     byte(1),
+		WildcardSubAvailableFlag: true,
+		SubIDAvailable:           byte(1),
+		SubIDAvailableFlag:       true,
+		SharedSubAvailable:       byte(1),
+		SharedSubAvailableFlag:   true,
+	}
+
+	propertiesBytes = []byte{
+		172, 1, // VBI
+
+		// Payload Format (1) (vbi:2)
+		1, 1,
+
+		// Message Expiry (2) (vbi:7)
+		2, 0, 0, 0, 2,
+
+		// Content Type (3) (vbi:20)
+		3,
+		0, 10, 't', 'e', 'x', 't', '/', 'p', 'l', 'a', 'i', 'n',
+
+		// Response Topic (8) (vbi:28)
+		8,
+		0, 5, 'a', '/', 'b', '/', 'c',
+
+		// Correlations Data (9) (vbi:35)
+		9,
+		0, 4, 'd', 'a', 't', 'a',
+
+		// Subscription Identifier (11) (vbi:39)
+		11,
+		202, 212, 19,
+
+		// Session Expiry Interval (17) (vbi:43)
+		17,
+		0, 0, 0, 120,
+
+		// Assigned Client ID (18) (vbi:55)
+		18,
+		0, 8, 'm', 'o', 'c', 'h', 'i', '-', 'v', '5',
+
+		// Server Keep Alive (19) (vbi:58)
+		19,
+		0, 20,
+
+		// Authentication Method (21) (vbi:66)
+		21,
+		0, 5, 'S', 'H', 'A', '-', '1',
+
+		// Authentication Data (22) (vbi:78)
+		22,
+		0, 9, 'a', 'u', 't', 'h', '-', 'd', 'a', 't', 'a',
+
+		// Request Problem Info (23) (vbi:80)
+		23, 1,
+
+		// Will Delay Interval (24) (vbi:85)
+		24,
+		0, 0, 2, 88,
+
+		// Request Response Info (25) (vbi:87)
+		25, 1,
+
+		// Response Info (26) (vbi:98)
+		26,
+		0, 8, 'r', 'e', 's', 'p', 'o', 'n', 's', 'e',
+
+		// Server Reference (28) (vbi:108)
+		28,
+		0, 7, 'm', 'o', 'c', 'h', 'i', '-', '2',
+
+		// Reason String (31) (vbi:117)
+		31,
+		0, 6, 'r', 'e', 'a', 's', 'o', 'n',
+
+		// Receive Maximum (33) (vbi:120)
+		33,
+		1, 244,
+
+		// Topic Alias Maximum (34) (vbi:123)
+		34,
+		3, 231,
+
+		// Topic Alias (35) (vbi:126)
+		35,
+		0, 3,
+
+		// Maximum Qos (36) (vbi:128)
+		36, 1,
+
+		// Retain Available (37) (vbi: 130)
+		37, 1,
+
+		// User Properties (38) (vbi:161)
+		38,
+		0, 5, 'h', 'e', 'l', 'l', 'o',
+		0, 6, 228, 184, 150, 231, 149, 140,
+		38,
+		0, 4, 'k', 'e', 'y', '2',
+		0, 6, 'v', 'a', 'l', 'u', 'e', '2',
+
+		// Maximum Packet Size (39) (vbi:166)
+		39,
+		0, 0, 125, 0,
+
+		// Wildcard Subscriptions Available (40)  (vbi:168)
+		40, 1,
+
+		// Subscription ID Available (41) (vbi:170)
+		41, 1,
+
+		// Shared Subscriptions Available (42) (vbi:172)
+		42, 1,
+	}
+)
+
+func init() {
+	validPacketProperties[PropPayloadFormat][Reserved] = 1
+	validPacketProperties[PropMessageExpiryInterval][Reserved] = 1
+	validPacketProperties[PropContentType][Reserved] = 1
+	validPacketProperties[PropResponseTopic][Reserved] = 1
+	validPacketProperties[PropCorrelationData][Reserved] = 1
+	validPacketProperties[PropSubscriptionIdentifier][Reserved] = 1
+	validPacketProperties[PropSessionExpiryInterval][Reserved] = 1
+	validPacketProperties[PropAssignedClientID][Reserved] = 1
+	validPacketProperties[PropServerKeepAlive][Reserved] = 1
+	validPacketProperties[PropAuthenticationMethod][Reserved] = 1
+	validPacketProperties[PropAuthenticationData][Reserved] = 1
+	validPacketProperties[PropRequestProblemInfo][Reserved] = 1
+	validPacketProperties[PropWillDelayInterval][Reserved] = 1
+	validPacketProperties[PropRequestResponseInfo][Reserved] = 1
+	validPacketProperties[PropResponseInfo][Reserved] = 1
+	validPacketProperties[PropServerReference][Reserved] = 1
+	validPacketProperties[PropReasonString][Reserved] = 1
+	validPacketProperties[PropReceiveMaximum][Reserved] = 1
+	validPacketProperties[PropTopicAliasMaximum][Reserved] = 1
+	validPacketProperties[PropTopicAlias][Reserved] = 1
+	validPacketProperties[PropMaximumQos][Reserved] = 1
+	validPacketProperties[PropRetainAvailable][Reserved] = 1
+	validPacketProperties[PropUser][Reserved] = 1
+	validPacketProperties[PropMaximumPacketSize][Reserved] = 1
+	validPacketProperties[PropWildcardSubAvailable][Reserved] = 1
+	validPacketProperties[PropSubIDAvailable][Reserved] = 1
+	validPacketProperties[PropSharedSubAvailable][Reserved] = 1
+}
+
+func TestEncodeProperties(t *testing.T) {
+	props := propertiesStruct
+	b := bytes.NewBuffer([]byte{})
+	props.Encode(Reserved, Mods{AllowResponseInfo: true}, b, 0)
+	require.Equal(t, propertiesBytes, b.Bytes())
+}
+
+func TestEncodePropertiesDisallowProblemInfo(t *testing.T) {
+	props := propertiesStruct
+	b := bytes.NewBuffer([]byte{})
+	props.Encode(Reserved, Mods{DisallowProblemInfo: true}, b, 0)
+	require.NotEqual(t, propertiesBytes, b.Bytes())
+	require.False(t, bytes.Contains(b.Bytes(), []byte{31, 0, 6}))
+	require.False(t, bytes.Contains(b.Bytes(), []byte{38, 0, 5}))
+	require.False(t, bytes.Contains(b.Bytes(), []byte{26, 0, 8}))
+}
+
+func TestEncodePropertiesDisallowResponseInfo(t *testing.T) {
+	props := propertiesStruct
+	b := bytes.NewBuffer([]byte{})
+	props.Encode(Reserved, Mods{AllowResponseInfo: false}, b, 0)
+	require.NotEqual(t, propertiesBytes, b.Bytes())
+	require.NotContains(t, b.Bytes(), []byte{8, 0, 5})
+	require.NotContains(t, b.Bytes(), []byte{9, 0, 4})
+}
+
+func TestEncodePropertiesNil(t *testing.T) {
+	type tmp struct {
+		p *Properties
+	}
+
+	pr := tmp{}
+	b := bytes.NewBuffer([]byte{})
+	pr.p.Encode(Reserved, Mods{}, b, 0)
+	require.Equal(t, []byte{}, b.Bytes())
+}
+
+func TestEncodeZeroProperties(t *testing.T) {
+	// [MQTT-2.2.2-1] If there are no properties, this MUST be indicated by including a Property Length of zero.
+	props := new(Properties)
+	b := bytes.NewBuffer([]byte{})
+	props.Encode(Reserved, Mods{AllowResponseInfo: true}, b, 0)
+	require.Equal(t, []byte{0x00}, b.Bytes())
+}
+
+func TestDecodeProperties(t *testing.T) {
+	b := bytes.NewBuffer(propertiesBytes)
+
+	props := new(Properties)
+	n, err := props.Decode(Reserved, b)
+	require.NoError(t, err)
+	require.Equal(t, 172+2, n)
+	require.EqualValues(t, propertiesStruct, *props)
+}
+
+func TestDecodePropertiesNil(t *testing.T) {
+	b := bytes.NewBuffer(propertiesBytes)
+
+	type tmp struct {
+		p *Properties
+	}
+
+	pr := tmp{}
+	n, err := pr.p.Decode(Reserved, b)
+	require.NoError(t, err)
+	require.Equal(t, 0, n)
+}
+
+func TestDecodePropertiesBadInitialVBI(t *testing.T) {
+	b := bytes.NewBuffer([]byte{255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255})
+	props := new(Properties)
+	_, err := props.Decode(Reserved, b)
+	require.Error(t, err)
+	require.ErrorIs(t, ErrMalformedVariableByteInteger, err)
+}
+
+func TestDecodePropertiesZeroLengthVBI(t *testing.T) {
+	b := bytes.NewBuffer([]byte{0})
+	props := new(Properties)
+	_, err := props.Decode(Reserved, b)
+	require.NoError(t, err)
+	require.Equal(t, props, new(Properties))
+}
+
+func TestDecodePropertiesBadKeyByte(t *testing.T) {
+	b := bytes.NewBuffer([]byte{64, 1})
+	props := new(Properties)
+	_, err := props.Decode(Reserved, b)
+	require.Error(t, err)
+	require.ErrorIs(t, err, ErrMalformedOffsetByteOutOfRange)
+}
+
+func TestDecodePropertiesInvalidForPacket(t *testing.T) {
+	b := bytes.NewBuffer([]byte{1, 99})
+	props := new(Properties)
+	_, err := props.Decode(Reserved, b)
+	require.Error(t, err)
+	require.ErrorIs(t, err, ErrProtocolViolationUnsupportedProperty)
+}
+
+func TestDecodePropertiesGeneralFailure(t *testing.T) {
+	b := bytes.NewBuffer([]byte{10, 11, 202, 212, 19})
+	props := new(Properties)
+	_, err := props.Decode(Reserved, b)
+	require.Error(t, err)
+}
+
+func TestDecodePropertiesBadSubscriptionID(t *testing.T) {
+	b := bytes.NewBuffer([]byte{10, 11, 255, 255, 255, 255, 255, 255, 255, 255})
+	props := new(Properties)
+	_, err := props.Decode(Reserved, b)
+	require.Error(t, err)
+}
+
+func TestDecodePropertiesBadUserProps(t *testing.T) {
+	b := bytes.NewBuffer([]byte{10, 38, 255, 255, 255, 255, 255, 255, 255, 255})
+	props := new(Properties)
+	_, err := props.Decode(Reserved, b)
+	require.Error(t, err)
+}
+
+func TestCopyProperties(t *testing.T) {
+	require.EqualValues(t, propertiesStruct, propertiesStruct.Copy(true))
+}
+
+func TestCopyPropertiesNoTransfer(t *testing.T) {
+	pkA := propertiesStruct
+	pkB := pkA.Copy(false)
+
+	// Properties which should never be transferred from one connection to another
+	require.Equal(t, uint16(0), pkB.TopicAlias)
+}

packets/tpackets_test.go

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2022 mochi-mqtt, mochi-co
+// SPDX-FileContributor: mochi-co
+
+package packets
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func encodeTestOK(wanted TPacketCase) bool {
+	if wanted.RawBytes == nil {
+		return false
+	}
+	if wanted.Group != "" && wanted.Group != "encode" {
+		return false
+	}
+	return true
+}
+
+func decodeTestOK(wanted TPacketCase) bool {
+	if wanted.Group != "" && wanted.Group != "decode" {
+		return false
+	}
+	return true
+}
+
+func TestTPacketCaseGet(t *testing.T) {
+	require.Equal(t, TPacketData[Connect][1], TPacketData[Connect].Get(TConnectMqtt311))
+	require.Equal(t, TPacketCase{}, TPacketData[Connect].Get(byte(128)))
+}

server/internal/circ/buffer.go

@@ -1,206 +0,0 @@
-package circ
-
-import (
-	"errors"
-	"io"
-	"sync"
-	"sync/atomic"
-)
-
-var (
-	DefaultBufferSize int = 1024 * 256 // the default size of the buffer in bytes.
-	DefaultBlockSize  int = 1024 * 8   // the default size per R/W block in bytes.
-
-	ErrOutOfRange        = errors.New("Indexes out of range")
-	ErrInsufficientBytes = errors.New("Insufficient bytes to return")
-)
-
-// buffer contains core values and methods to be included in a reader or writer.
-type Buffer struct {
-	Mu    sync.RWMutex // the buffer needs it's own mutex to work properly.
-	ID    string       // the identifier of the buffer. This is used in debug output.
-	size  int          // the size of the buffer.
-	mask  int          // a bitmask of the buffer size (size-1).
-	block int          // the size of the R/W block.
-	buf   []byte       // the bytes buffer.
-	tmp   []byte       // a temporary buffer.
-	head  int64        // the current position in the sequence - a forever increasing index.
-	tail  int64        // the committed position in the sequence - a forever increasing index.
-	rcond *sync.Cond   // the sync condition for the buffer reader.
-	wcond *sync.Cond   // the sync condition for the buffer writer.
-	done  int64        // indicates that the buffer is closed.
-	State int64        // indicates whether the buffer is reading from (1) or writing to (2).
-}
-
-// NewBuffer returns a new instance of buffer. You should call NewReader or
-// NewWriter instead of this function.
-func NewBuffer(size, block int) Buffer {
-	if size == 0 {
-		size = DefaultBufferSize
-	}
-
-	if block == 0 {
-		block = DefaultBlockSize
-	}
-
-	if size < 2*block {
-		size = 2 * block
-	}
-
-	return Buffer{
-		size:  size,
-		mask:  size - 1,
-		block: block,
-		buf:   make([]byte, size),
-		rcond: sync.NewCond(new(sync.Mutex)),
-		wcond: sync.NewCond(new(sync.Mutex)),
-	}
-}
-
-// NewBufferFromSlice returns a new instance of buffer using a
-// pre-existing byte slice.
-func NewBufferFromSlice(block int, buf []byte) Buffer {
-	l := len(buf)
-
-	if block == 0 {
-		block = DefaultBlockSize
-	}
-
-	b := Buffer{
-		size:  l,
-		mask:  l - 1,
-		block: block,
-		buf:   buf,
-		rcond: sync.NewCond(new(sync.Mutex)),
-		wcond: sync.NewCond(new(sync.Mutex)),
-	}
-
-	return b
-}
-
-// Get will return the tail and head positions of the buffer.
-// This method is for use with testing.
-func (b *Buffer) GetPos() (int64, int64) {
-	return atomic.LoadInt64(&b.tail), atomic.LoadInt64(&b.head)
-}
-
-// SetPos sets the head and tail of the buffer.
-func (b *Buffer) SetPos(tail, head int64) {
-	atomic.StoreInt64(&b.tail, tail)
-	atomic.StoreInt64(&b.head, head)
-}
-
-// Get returns the internal buffer.
-func (b *Buffer) Get() []byte {
-	b.Mu.Lock()
-	defer b.Mu.Unlock()
-	return b.buf
-}
-
-// Set writes bytes to a range of indexes in the byte buffer.
-func (b *Buffer) Set(p []byte, start, end int) error {
-	b.Mu.Lock()
-	defer b.Mu.Unlock()
-
-	if end > b.size || start > b.size {
-		return ErrOutOfRange
-	}
-
-	o := 0
-	for i := start; i < end; i++ {
-		b.buf[i] = p[o]
-		o++
-	}
-
-	return nil
-}
-
-// Index returns the buffer-relative index of an integer.
-func (b *Buffer) Index(i int64) int {
-	return b.mask & int(i)
-}
-
-// awaitEmpty will block until there is at least n bytes between
-// the head and the tail (looking forward).
-func (b *Buffer) awaitEmpty(n int) error {
-	// If the head has wrapped behind the tail, and next will overrun tail,
-	// then wait until tail has moved.
-	b.rcond.L.Lock()
-	for !b.checkEmpty(n) {
-		if atomic.LoadInt64(&b.done) == 1 {
-			b.rcond.L.Unlock()
-			return io.EOF
-		}
-		b.rcond.Wait()
-	}
-	b.rcond.L.Unlock()
-
-	return nil
-}
-
-// awaitFilled will block until there are at least n bytes between the
-// tail and the head (looking forward).
-func (b *Buffer) awaitFilled(n int) error {
-	// Because awaitCapacity prevents the head from overrunning the t
-	// able on write, we can simply ensure there is enough space
-	// the forever-incrementing tail and head integers.
-	b.wcond.L.Lock()
-	for !b.checkFilled(n) {
-		if atomic.LoadInt64(&b.done) == 1 {
-			b.wcond.L.Unlock()
-			return io.EOF
-		}
-
-		b.wcond.Wait()
-	}
-	b.wcond.L.Unlock()
-
-	return nil
-}
-
-// checkEmpty returns true if there are at least n bytes between the head and
-// the tail.
-func (b *Buffer) checkEmpty(n int) bool {
-	head := atomic.LoadInt64(&b.head)
-	next := head + int64(n)
-	tail := atomic.LoadInt64(&b.tail)
-	if next-tail > int64(b.size) {
-		return false
-	}
-
-	return true
-}
-
-// checkFilled returns true if there are at least n bytes between the tail and
-// the head.
-func (b *Buffer) checkFilled(n int) bool {
-	if atomic.LoadInt64(&b.tail)+int64(n) <= atomic.LoadInt64(&b.head) {
-		return true
-	}
-
-	return false
-}
-
-// CommitTail moves the tail position of the buffer n bytes.
-func (b *Buffer) CommitTail(n int) {
-	atomic.AddInt64(&b.tail, int64(n))
-	b.rcond.L.Lock()
-	b.rcond.Broadcast()
-	b.rcond.L.Unlock()
-}
-
-// CapDelta returns the difference between the head and tail.
-func (b *Buffer) CapDelta() int {
-	return int(atomic.LoadInt64(&b.head) - atomic.LoadInt64(&b.tail))
-}
-
-// Stop signals the buffer to stop processing.
-func (b *Buffer) Stop() {
-	atomic.StoreInt64(&b.done, 1)
-	b.rcond.L.Lock()
-	b.rcond.Broadcast()
-	b.rcond.L.Unlock()
-	b.wcond.L.Lock()
-	b.wcond.Broadcast()
-	b.wcond.L.Unlock()
-}

server/internal/circ/buffer_test.go

@@ -1,304 +0,0 @@
-package circ
-
-import (
-	//"fmt"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/require"
-)
-
-func TestNewBuffer(t *testing.T) {
-	var size int = 16
-	var block int = 4
-	buf := NewBuffer(size, block)
-
-	require.NotNil(t, buf.buf)
-	require.NotNil(t, buf.rcond)
-	require.NotNil(t, buf.wcond)
-	require.Equal(t, size, len(buf.buf))
-	require.Equal(t, size, buf.size)
-	require.Equal(t, block, buf.block)
-}
-
-func TestNewBuffer0Size(t *testing.T) {
-	buf := NewBuffer(0, 0)
-	require.NotNil(t, buf.buf)
-	require.Equal(t, DefaultBufferSize, buf.size)
-	require.Equal(t, DefaultBlockSize, buf.block)
-}
-
-func TestNewBufferUndersize(t *testing.T) {
-	buf := NewBuffer(DefaultBlockSize+10, DefaultBlockSize)
-	require.NotNil(t, buf.buf)
-	require.Equal(t, DefaultBlockSize*2, buf.size)
-	require.Equal(t, DefaultBlockSize, buf.block)
-}
-
-func TestNewBufferFromSlice(t *testing.T) {
-	b := NewBytesPool(256)
-	buf := NewBufferFromSlice(DefaultBlockSize, b.Get())
-	require.NotNil(t, buf.buf)
-	require.Equal(t, 256, cap(buf.buf))
-}
-
-func TestNewBufferFromSlice0Size(t *testing.T) {
-	b := NewBytesPool(256)
-	buf := NewBufferFromSlice(0, b.Get())
-	require.NotNil(t, buf.buf)
-	require.Equal(t, 256, cap(buf.buf))
-}
-
-func TestGetPos(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	tail, head := buf.GetPos()
-	require.Equal(t, int64(0), tail)
-	require.Equal(t, int64(0), head)
-
-	buf.tail = 3
-	buf.head = 11
-
-	tail, head = buf.GetPos()
-	require.Equal(t, int64(3), tail)
-	require.Equal(t, int64(11), head)
-}
-
-func TestGet(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	require.Equal(t, make([]byte, 16), buf.Get())
-
-	buf.buf[0] = 1
-	buf.buf[15] = 1
-	require.Equal(t, []byte{1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1}, buf.Get())
-}
-
-func TestSetPos(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	require.Equal(t, int64(0), buf.tail)
-	require.Equal(t, int64(0), buf.head)
-
-	buf.SetPos(4, 8)
-	require.Equal(t, int64(4), buf.tail)
-	require.Equal(t, int64(8), buf.head)
-}
-
-func TestSet(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	err := buf.Set([]byte{1, 1, 1, 1}, 17, 19)
-	require.Error(t, err)
-
-	err = buf.Set([]byte{1, 1, 1, 1}, 4, 8)
-	require.NoError(t, err)
-	require.Equal(t, []byte{0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0}, buf.buf)
-}
-
-func TestIndex(t *testing.T) {
-	buf := NewBuffer(1024, 4)
-	require.Equal(t, 512, buf.Index(512))
-	require.Equal(t, 0, buf.Index(1024))
-	require.Equal(t, 6, buf.Index(1030))
-	require.Equal(t, 6, buf.Index(61446))
-}
-
-func TestAwaitFilled(t *testing.T) {
-	tests := []struct {
-		tail  int64
-		head  int64
-		n     int
-		await int
-		desc  string
-	}{
-		{tail: 0, head: 4, n: 4, await: 1, desc: "OK 0, 4"},
-		{tail: 8, head: 11, n: 4, await: 1, desc: "OK 8, 11"},
-		{tail: 102, head: 103, n: 4, await: 3, desc: "OK 102, 103"},
-	}
-
-	for i, tt := range tests {
-		//fmt.Println(i)
-		buf := NewBuffer(16, 4)
-		buf.SetPos(tt.tail, tt.head)
-		o := make(chan error)
-		go func() {
-			o <- buf.awaitFilled(4)
-		}()
-
-		time.Sleep(time.Millisecond)
-		atomic.AddInt64(&buf.head, int64(tt.await))
-		buf.wcond.L.Lock()
-		buf.wcond.Broadcast()
-		buf.wcond.L.Unlock()
-
-		require.NoError(t, <-o, "Unexpected Error [i:%d] %s", i, tt.desc)
-	}
-}
-
-func TestAwaitFilledEnded(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	o := make(chan error)
-	go func() {
-		o <- buf.awaitFilled(4)
-	}()
-	time.Sleep(time.Millisecond)
-	atomic.StoreInt64(&buf.done, 1)
-	buf.wcond.L.Lock()
-	buf.wcond.Broadcast()
-	buf.wcond.L.Unlock()
-
-	require.Error(t, <-o)
-}
-
-func TestAwaitEmptyOK(t *testing.T) {
-	tests := []struct {
-		tail  int64
-		head  int64
-		await int
-		desc  string
-	}{
-		{tail: 0, head: 0, await: 0, desc: "OK 0, 0"},
-		{tail: 0, head: 5, await: 0, desc: "OK 0, 5"},
-		{tail: 0, head: 14, await: 3, desc: "OK wrap 0, 14 "},
-		{tail: 22, head: 35, await: 2, desc: "OK wrap 0, 14 "},
-		{tail: 15, head: 17, await: 7, desc: "OK 15,2"},
-		{tail: 0, head: 10, await: 2, desc: "OK 0, 10"},
-		{tail: 1, head: 15, await: 4, desc: "OK 2, 14"},
-	}
-
-	for i, tt := range tests {
-		buf := NewBuffer(16, 4)
-		buf.SetPos(tt.tail, tt.head)
-		o := make(chan error)
-		go func() {
-			o <- buf.awaitEmpty(4)
-		}()
-
-		time.Sleep(time.Millisecond)
-		atomic.AddInt64(&buf.tail, int64(tt.await))
-		buf.rcond.L.Lock()
-		buf.rcond.Broadcast()
-		buf.rcond.L.Unlock()
-
-		require.NoError(t, <-o, "Unexpected Error [i:%d] %s", i, tt.desc)
-	}
-}
-
-func TestAwaitEmptyEnded(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	buf.SetPos(1, 15)
-	o := make(chan error)
-	go func() {
-		o <- buf.awaitEmpty(4)
-	}()
-	time.Sleep(time.Millisecond)
-	atomic.StoreInt64(&buf.done, 1)
-	buf.rcond.L.Lock()
-	buf.rcond.Broadcast()
-	buf.rcond.L.Unlock()
-
-	require.Error(t, <-o)
-}
-
-func TestCheckEmpty(t *testing.T) {
-	buf := NewBuffer(16, 4)
-
-	tests := []struct {
-		head int64
-		tail int64
-		want bool
-		desc string
-	}{
-		{tail: 0, head: 0, want: true, desc: "0, 0 true"},
-		{tail: 3, head: 4, want: true, desc: "4, 3 true"},
-		{tail: 15, head: 17, want: true, desc: "15, 17(1) true"},
-		{tail: 1, head: 30, want: false, desc: "1, 30(14) false"},
-		{tail: 15, head: 30, want: false, desc: "15, 30(14) false; head has caught up to tail"},
-	}
-	for i, tt := range tests {
-		buf.SetPos(tt.tail, tt.head)
-		require.Equal(t, tt.want, buf.checkEmpty(4), "Mismatched bool wanted [i:%d] %s", i, tt.desc)
-	}
-}
-
-func TestCheckFilled(t *testing.T) {
-	buf := NewBuffer(16, 4)
-
-	tests := []struct {
-		head int64
-		tail int64
-		want bool
-		desc string
-	}{
-		{tail: 0, head: 0, want: false, desc: "0, 0 false"},
-		{tail: 0, head: 4, want: true, desc: "0, 4 true"},
-		{tail: 14, head: 16, want: false, desc: "14,16 false"},
-		{tail: 14, head: 18, want: true, desc: "14,16 true"},
-	}
-
-	for i, tt := range tests {
-		buf.SetPos(tt.tail, tt.head)
-		require.Equal(t, tt.want, buf.checkFilled(4), "Mismatched bool wanted [i:%d] %s", i, tt.desc)
-	}
-
-}
-
-func TestCommitTail(t *testing.T) {
-	tests := []struct {
-		tail  int64
-		head  int64
-		n     int
-		next  int64
-		await int
-		desc  string
-	}{
-		{tail: 0, head: 5, n: 4, next: 4, await: 0, desc: "OK 0, 4"},
-		{tail: 0, head: 5, n: 6, next: 6, await: 1, desc: "OK 0, 5"},
-	}
-
-	for i, tt := range tests {
-		buf := NewBuffer(16, 4)
-		buf.SetPos(tt.tail, tt.head)
-		go func() {
-			buf.CommitTail(tt.n)
-		}()
-
-		time.Sleep(time.Millisecond)
-		for j := 0; j < tt.await; j++ {
-			atomic.AddInt64(&buf.head, 1)
-			buf.wcond.L.Lock()
-			buf.wcond.Broadcast()
-			buf.wcond.L.Unlock()
-		}
-		require.Equal(t, tt.next, buf.tail, "Next tail mismatch [i:%d] %s", i, tt.desc)
-	}
-}
-
-/*
-func TestCommitTailEnded(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	o := make(chan error)
-	go func() {
-		o <- buf.CommitTail(5)
-	}()
-	time.Sleep(time.Millisecond)
-	atomic.StoreInt64(&buf.done, 1)
-	buf.wcond.L.Lock()
-	buf.wcond.Broadcast()
-	buf.wcond.L.Unlock()
-
-	require.Error(t, <-o)
-}
-*/
-func TestCapDelta(t *testing.T) {
-	buf := NewBuffer(16, 4)
-
-	require.Equal(t, 0, buf.CapDelta())
-
-	buf.SetPos(10, 15)
-	require.Equal(t, 5, buf.CapDelta())
-}
-
-func TestStop(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	buf.Stop()
-	require.Equal(t, int64(1), buf.done)
-}

server/internal/circ/pool.go

@@ -1,34 +0,0 @@
-package circ
-
-import (
-	"sync"
-)
-
-// BytesPool is a pool of []byte.
-type BytesPool struct {
-	pool sync.Pool
-}
-
-// NewBytesPool returns a sync.pool of []byte.
-func NewBytesPool(n int) BytesPool {
-	return BytesPool{
-		pool: sync.Pool{
-			New: func() interface{} {
-				return make([]byte, n)
-			},
-		},
-	}
-}
-
-// Get returns a pooled bytes.Buffer.
-func (b *BytesPool) Get() []byte {
-	return b.pool.Get().([]byte)
-}
-
-// Put puts the byte slice back into the pool.
-func (b *BytesPool) Put(x []byte) {
-	for i := range x {
-		x[i] = 0
-	}
-	b.pool.Put(x)
-}

server/internal/circ/pool_test.go

@@ -1,46 +0,0 @@
-package circ
-
-import (
-	"testing"
-
-	"github.com/stretchr/testify/require"
-)
-
-func TestNewBytesPool(t *testing.T) {
-	bpool := NewBytesPool(256)
-	require.NotNil(t, bpool.pool)
-}
-
-func BenchmarkNewBytesPool(b *testing.B) {
-	for n := 0; n < b.N; n++ {
-		NewBytesPool(256)
-	}
-}
-
-func TestNewBytesPoolGet(t *testing.T) {
-	bpool := NewBytesPool(256)
-	buf := bpool.Get()
-
-	require.Equal(t, make([]byte, 256), buf)
-}
-
-func BenchmarkBytesPoolGet(b *testing.B) {
-	bpool := NewBytesPool(256)
-	for n := 0; n < b.N; n++ {
-		bpool.Get()
-	}
-}
-
-func TestNewBytesPoolPut(t *testing.T) {
-	bpool := NewBytesPool(256)
-	buf := bpool.Get()
-	bpool.Put(buf)
-}
-
-func BenchmarkBytesPoolPut(b *testing.B) {
-	bpool := NewBytesPool(256)
-	buf := bpool.Get()
-	for n := 0; n < b.N; n++ {
-		bpool.Put(buf)
-	}
-}

server/internal/circ/reader.go

@@ -1,96 +0,0 @@
-package circ
-
-import (
-	"io"
-	"sync/atomic"
-)
-
-// Reader is a circular buffer for reading data from an io.Reader.
-type Reader struct {
-	Buffer
-}
-
-// NewReader returns a new Circular Reader.
-func NewReader(size, block int) *Reader {
-	b := NewBuffer(size, block)
-	b.ID = "\treader"
-	return &Reader{
-		b,
-	}
-}
-
-// NewReaderFromSlice returns a new Circular Reader using a pre-exising
-// byte slice.
-func NewReaderFromSlice(block int, p []byte) *Reader {
-	b := NewBufferFromSlice(block, p)
-	b.ID = "\treader"
-	return &Reader{
-		b,
-	}
-}
-
-// ReadFrom reads bytes from an io.Reader and commits them to the buffer when
-// there is sufficient capacity to do so.
-func (b *Reader) ReadFrom(r io.Reader) (total int64, err error) {
-	atomic.StoreInt64(&b.State, 1)
-	defer atomic.StoreInt64(&b.State, 0)
-	for {
-		if atomic.LoadInt64(&b.done) == 1 {
-			return total, nil
-		}
-
-		// Wait until there's enough capacity in the buffer before
-		// trying to read more bytes from the io.Reader.
-		err := b.awaitEmpty(b.block)
-		if err != nil {
-			// b.done is the only error condition for awaitCapacity
-			// so loop around and return properly.
-			continue
-		}
-
-		// If the block will overrun the circle end, just fill up
-		// and collect the rest on the next pass.
-		start := b.Index(atomic.LoadInt64(&b.head))
-		end := start + b.block
-		if end > b.size {
-			end = b.size
-		}
-
-		// Read into the buffer between the start and end indexes only.
-		n, err := r.Read(b.buf[start:end])
-		total += int64(n) // incr total bytes read.
-		if err != nil {
-			return total, nil
-		}
-
-		// Move the head forward however many bytes were read.
-		atomic.AddInt64(&b.head, int64(n))
-
-		b.wcond.L.Lock()
-		b.wcond.Broadcast()
-		b.wcond.L.Unlock()
-	}
-}
-
-// Read reads n bytes from the buffer, and will block until at n bytes
-// exist in the buffer to read.
-func (b *Buffer) Read(n int) (p []byte, err error) {
-	err = b.awaitFilled(n)
-	if err != nil {
-		return
-	}
-
-	tail := atomic.LoadInt64(&b.tail)
-	next := tail + int64(n)
-
-	// If the read overruns the buffer, get everything until the end
-	// and then whatever is left from the start.
-	if b.Index(tail) > b.Index(next) {
-		b.tmp = b.buf[b.Index(tail):]
-		b.tmp = append(b.tmp, b.buf[:b.Index(next)]...)
-	} else {
-		b.tmp = b.buf[b.Index(tail):b.Index(next)] // Otherwise, simple tail:next read.
-	}
-
-	return b.tmp, nil
-}

server/internal/circ/reader_test.go

@@ -1,125 +0,0 @@
-package circ
-
-import (
-	"bytes"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/require"
-)
-
-func TestNewReader(t *testing.T) {
-	var size = 16
-	var block = 4
-	buf := NewReader(size, block)
-
-	require.NotNil(t, buf.buf)
-	require.Equal(t, size, len(buf.buf))
-	require.Equal(t, size, buf.size)
-	require.Equal(t, block, buf.block)
-}
-
-func TestNewReaderFromSlice(t *testing.T) {
-	b := NewBytesPool(256)
-	buf := NewReaderFromSlice(DefaultBlockSize, b.Get())
-	require.NotNil(t, buf.buf)
-	require.Equal(t, 256, cap(buf.buf))
-}
-
-func TestReadFrom(t *testing.T) {
-	buf := NewReader(16, 4)
-
-	b4 := bytes.Repeat([]byte{'-'}, 4)
-	br := bytes.NewReader(b4)
-
-	_, err := buf.ReadFrom(br)
-	require.NoError(t, err)
-	require.Equal(t, bytes.Repeat([]byte{'-'}, 4), buf.buf[:4])
-	require.Equal(t, int64(4), buf.head)
-
-	br.Reset(b4)
-	_, err = buf.ReadFrom(br)
-	require.Equal(t, int64(8), buf.head)
-
-	br.Reset(b4)
-	_, err = buf.ReadFrom(br)
-	require.Equal(t, int64(12), buf.head)
-}
-
-func TestReadFromWrap(t *testing.T) {
-	buf := NewReader(16, 4)
-	buf.buf = bytes.Repeat([]byte{'-'}, 16)
-	buf.SetPos(8, 14)
-	br := bytes.NewReader(bytes.Repeat([]byte{'/'}, 8))
-
-	o := make(chan error)
-	go func() {
-		_, err := buf.ReadFrom(br)
-		o <- err
-	}()
-	time.Sleep(time.Millisecond * 100)
-	go func() {
-		atomic.StoreInt64(&buf.done, 1)
-		buf.rcond.L.Lock()
-		buf.rcond.Broadcast()
-		buf.rcond.L.Unlock()
-	}()
-	<-o
-	require.Equal(t, []byte{'/', '/', '/', '/', '/', '/', '-', '-', '-', '-', '-', '-', '-', '-', '/', '/'}, buf.Get())
-	require.Equal(t, int64(22), atomic.LoadInt64(&buf.head))
-	require.Equal(t, 6, buf.Index(atomic.LoadInt64(&buf.head)))
-}
-
-func TestReadOK(t *testing.T) {
-	buf := NewReader(16, 4)
-	buf.buf = []byte{'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p'}
-
-	tests := []struct {
-		tail  int64
-		head  int64
-		n     int
-		bytes []byte
-		desc  string
-	}{
-		{tail: 0, head: 4, n: 4, bytes: []byte{'a', 'b', 'c', 'd'}, desc: "0, 4 OK"},
-		{tail: 3, head: 15, n: 8, bytes: []byte{'d', 'e', 'f', 'g', 'h', 'i', 'j', 'k'}, desc: "3, 15 OK"},
-		{tail: 14, head: 15, n: 6, bytes: []byte{'o', 'p', 'a', 'b', 'c', 'd'}, desc: "14, 2 wrapped OK"},
-	}
-
-	for i, tt := range tests {
-		buf.SetPos(tt.tail, tt.head)
-		o := make(chan []byte)
-		go func() {
-			p, _ := buf.Read(tt.n)
-			o <- p
-		}()
-
-		time.Sleep(time.Millisecond)
-		atomic.StoreInt64(&buf.head, buf.head+int64(tt.n))
-
-		buf.wcond.L.Lock()
-		buf.wcond.Broadcast()
-		buf.wcond.L.Unlock()
-
-		done := <-o
-		require.Equal(t, tt.bytes, done, "Peeked bytes mismatch [i:%d] %s", i, tt.desc)
-
-	}
-}
-
-func TestReadEnded(t *testing.T) {
-	buf := NewBuffer(16, 4)
-	o := make(chan error)
-	go func() {
-		_, err := buf.Read(4)
-		o <- err
-	}()
-	time.Sleep(time.Millisecond)
-	atomic.StoreInt64(&buf.done, 1)
-	buf.wcond.L.Lock()
-	buf.wcond.Broadcast()
-	buf.wcond.L.Unlock()
-
-	require.Error(t, <-o)
-}

server/internal/circ/writer.go

@@ -1,107 +0,0 @@
-package circ
-
-import (
-	"fmt"
-	"io"
-	"sync/atomic"
-)
-
-// Writer is a circular buffer for writing data to an io.Writer.
-type Writer struct {
-	Buffer
-}
-
-// NewWriter returns a pointer to a new Circular Writer.
-func NewWriter(size, block int) *Writer {
-	b := NewBuffer(size, block)
-	b.ID = "writer"
-	return &Writer{
-		b,
-	}
-}
-
-// NewWriterFromSlice returns a new Circular Writer using a pre-exising
-// byte slice.
-func NewWriterFromSlice(block int, p []byte) *Writer {
-	b := NewBufferFromSlice(block, p)
-	b.ID = "writer"
-	return &Writer{
-		b,
-	}
-}
-
-// WriteTo writes the contents of the buffer to an io.Writer.
-func (b *Writer) WriteTo(w io.Writer) (total int, err error) {
-	atomic.StoreInt64(&b.State, 2)
-	defer atomic.StoreInt64(&b.State, 0)
-	for {
-		if atomic.LoadInt64(&b.done) == 1 && b.CapDelta() == 0 {
-			return total, io.EOF
-		}
-
-		// Read from the buffer until there is at least 1 byte to write.
-		err = b.awaitFilled(1)
-		if err != nil {
-			return
-		}
-
-		// Get all the bytes between the tail and head, wrapping if necessary.
-		tail := atomic.LoadInt64(&b.tail)
-		rTail := b.Index(tail)
-		rHead := b.Index(atomic.LoadInt64(&b.head))
-		n := b.CapDelta()
-		p := make([]byte, 0, n)
-
-		if rTail > rHead {
-			p = append(p, b.buf[rTail:]...)
-			p = append(p, b.buf[:rHead]...)
-		} else {
-			p = append(p, b.buf[rTail:rHead]...)
-		}
-
-		//fmt.Println("writing", p)
-		n, err = w.Write(p)
-		total += n
-		if err != nil {
-			fmt.Println("writing err", err)
-			return
-		}
-		//fmt.Println("written", n)
-
-		// Move the tail forward the bytes written and broadcast change.
-		atomic.StoreInt64(&b.tail, tail+int64(n))
-		b.rcond.L.Lock()
-		b.rcond.Broadcast()
-		b.rcond.L.Unlock()
-	}
-}
-
-// Write writes the buffer to the buffer p, returning the number of bytes written.
-func (b *Writer) Write(p []byte) (total int, err error) {
-	err = b.awaitEmpty(len(p))
-	if err != nil {
-		return
-	}
-
-	total = b.writeBytes(p)
-	atomic.AddInt64(&b.head, int64(total))
-	b.wcond.L.Lock()
-	b.wcond.Broadcast()
-	b.wcond.L.Unlock()
-	return
-}
-
-// writeBytes writes bytes to the buffer from the start position, and returns
-// the new head position. This function does not wait for capacity and will
-// overwrite any existing bytes.
-func (b *Writer) writeBytes(p []byte) int {
-	var o int
-	var n int
-	for i := 0; i < len(p); i++ {
-		o = b.Index(atomic.LoadInt64(&b.head) + int64(i))
-		b.buf[o] = p[i]
-		n++
-	}
-
-	return n
-}

server/internal/circ/writer_test.go

@@ -1,155 +0,0 @@
-package circ
-
-import (
-	"bufio"
-	"bytes"
-	"net"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/require"
-)
-
-func TestNewWriter(t *testing.T) {
-	var size = 16
-	var block = 4
-	buf := NewWriter(size, block)
-
-	require.NotNil(t, buf.buf)
-	require.Equal(t, size, len(buf.buf))
-	require.Equal(t, size, buf.size)
-	require.Equal(t, block, buf.block)
-}
-
-func TestNewWriterFromSlice(t *testing.T) {
-	b := NewBytesPool(256)
-	buf := NewWriterFromSlice(DefaultBlockSize, b.Get())
-	require.NotNil(t, buf.buf)
-	require.Equal(t, 256, cap(buf.buf))
-}
-
-func TestWriteTo(t *testing.T) {
-	tests := []struct {
-		tail  int64
-		head  int64
-		bytes []byte
-		await int
-		total int
-		err   error
-		desc  string
-	}{
-		{tail: 0, head: 5, bytes: []byte{'a', 'b', 'c', 'd', 'e'}, desc: "0,5 OK"},
-		{tail: 14, head: 21, bytes: []byte{'o', 'p', 'a', 'b', 'c', 'd', 'e'}, desc: "14,16(2) OK"},
-	}
-
-	for i, tt := range tests {
-		bb := []byte{'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p'}
-		buf := NewWriter(16, 4)
-		buf.Set(bb, 0, 16)
-		buf.SetPos(tt.tail, tt.head)
-
-		var b bytes.Buffer
-		w := bufio.NewWriter(&b)
-
-		nc := make(chan int)
-		go func() {
-			n, _ := buf.WriteTo(w)
-			nc <- n
-		}()
-
-		time.Sleep(time.Millisecond * 100)
-		atomic.StoreInt64(&buf.done, 1)
-		buf.wcond.L.Lock()
-		buf.wcond.Broadcast()
-		buf.wcond.L.Unlock()
-
-		w.Flush()
-		require.Equal(t, tt.bytes, b.Bytes(), "Written bytes mismatch [i:%d] %s", i, tt.desc)
-	}
-}
-
-func TestWriteToEndedFirst(t *testing.T) {
-	buf := NewWriter(16, 4)
-	buf.done = 1
-
-	var b bytes.Buffer
-	w := bufio.NewWriter(&b)
-	_, err := buf.WriteTo(w)
-	require.Error(t, err)
-}
-
-func TestWriteToBadWriter(t *testing.T) {
-	bb := []byte{'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p'}
-	buf := NewWriter(16, 4)
-	buf.Set(bb, 0, 16)
-	buf.SetPos(0, 6)
-	r, w := net.Pipe()
-
-	w.Close()
-	_, err := buf.WriteTo(w)
-	require.Error(t, err)
-	r.Close()
-}
-
-func TestWrite(t *testing.T) {
-	tests := []struct {
-		tail  int64
-		head  int64
-		rHead int64
-		bytes []byte
-		want  []byte
-		desc  string
-	}{
-		{tail: 0, head: 0, rHead: 4, bytes: []byte{'a', 'b', 'c', 'd'}, want: []byte{'a', 'b', 'c', 'd', 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}, desc: "0>4 OK"},
-		{tail: 4, head: 14, rHead: 2, bytes: []byte{'a', 'b', 'c', 'd'}, want: []byte{'c', 'd', 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 'a', 'b'}, desc: "14>2 OK"},
-	}
-
-	for i, tt := range tests {
-		buf := NewWriter(16, 4)
-		buf.SetPos(tt.tail, tt.head)
-
-		o := make(chan []interface{})
-		go func() {
-			nn, err := buf.Write(tt.bytes)
-			o <- []interface{}{nn, err}
-		}()
-
-		done := <-o
-		require.Equal(t, tt.want, buf.buf, "Wanted written mismatch [i:%d] %s", i, tt.desc)
-		require.Nil(t, done[1], "Unexpected Error [i:%d] %s", i, tt.desc)
-	}
-}
-
-func TestWriteEnded(t *testing.T) {
-	buf := NewWriter(16, 4)
-	buf.SetPos(15, 30)
-	buf.done = 1
-
-	_, err := buf.Write([]byte{'a', 'b', 'c', 'd'})
-	require.Error(t, err)
-}
-
-func TestWriteBytes(t *testing.T) {
-	tests := []struct {
-		tail  int64
-		head  int64
-		bytes []byte
-		want  []byte
-		start int
-		desc  string
-	}{
-		{tail: 0, head: 0, bytes: []byte{'a', 'b', 'c', 'd'}, want: []byte{'a', 'b', 'c', 'd', 0, 0, 0, 0}, desc: "0,4 OK"},
-		{tail: 6, head: 6, bytes: []byte{'a', 'b', 'c', 'd'}, want: []byte{'c', 'd', 0, 0, 0, 0, 'a', 'b'}, desc: "6,2 OK wrapped"},
-	}
-
-	for i, tt := range tests {
-		buf := NewWriter(8, 4)
-		buf.SetPos(tt.tail, tt.head)
-		n := buf.writeBytes(tt.bytes)
-
-		require.Equal(t, tt.want, buf.buf, "Buffer mistmatch [i:%d] %s", i, tt.desc)
-		require.Equal(t, len(tt.bytes), n)
-	}
-
-}

server/internal/clients/clients.go

@@ -1,514 +0,0 @@
-package clients
-
-import (
-	"bytes"
-	"encoding/binary"
-	"errors"
-	"fmt"
-	"net"
-	"sync"
-	"sync/atomic"
-	"time"
-
-	"github.com/rs/xid"
-
-	"github.com/mochi-co/mqtt/server/internal/circ"
-	"github.com/mochi-co/mqtt/server/internal/packets"
-	"github.com/mochi-co/mqtt/server/internal/topics"
-	"github.com/mochi-co/mqtt/server/listeners/auth"
-	"github.com/mochi-co/mqtt/server/system"
-)
-
-var (
-	// defaultKeepalive is the default connection keepalive value in seconds.
-	defaultKeepalive uint16 = 10
-
-	ErrConnectionClosed = errors.New("Connection not open")
-)
-
-// Clients contains a map of the clients known by the broker.
-type Clients struct {
-	sync.RWMutex
-	internal map[string]*Client // clients known by the broker, keyed on client id.
-}
-
-// New returns an instance of Clients.
-func New() *Clients {
-	return &Clients{
-		internal: make(map[string]*Client),
-	}
-}
-
-// Add adds a new client to the clients map, keyed on client id.
-func (cl *Clients) Add(val *Client) {
-	cl.Lock()
-	cl.internal[val.ID] = val
-	cl.Unlock()
-}
-
-// Get returns the value of a client if it exists.
-func (cl *Clients) Get(id string) (*Client, bool) {
-	cl.RLock()
-	val, ok := cl.internal[id]
-	cl.RUnlock()
-	return val, ok
-}
-
-// Len returns the length of the clients map.
-func (cl *Clients) Len() int {
-	cl.RLock()
-	val := len(cl.internal)
-	cl.RUnlock()
-	return val
-}
-
-// Delete removes a client from the internal map.
-func (cl *Clients) Delete(id string) {
-	cl.Lock()
-	delete(cl.internal, id)
-	cl.Unlock()
-}
-
-// GetByListener returns clients matching a listener id.
-func (cl *Clients) GetByListener(id string) []*Client {
-	clients := make([]*Client, 0, cl.Len())
-	cl.RLock()
-	for _, v := range cl.internal {
-		if v.Listener == id && atomic.LoadInt64(&v.State.Done) == 0 {
-			clients = append(clients, v)
-		}
-	}
-	cl.RUnlock()
-	return clients
-}
-
-// Client contains information about a client known by the broker.
-type Client struct {
-	sync.RWMutex
-	conn          net.Conn             // the net.Conn used to establish the connection.
-	r             *circ.Reader         // a reader for reading incoming bytes.
-	w             *circ.Writer         // a writer for writing outgoing bytes.
-	ID            string               // the client id.
-	AC            auth.Controller      // an auth controller inherited from the listener.
-	Subscriptions topics.Subscriptions // a map of the subscription filters a client maintains.
-	Listener      string               // the id of the listener the client is connected to.
-	Inflight      Inflight             // a map of in-flight qos messages.
-	Username      []byte               // the username the client authenticated with.
-	keepalive     uint16               // the number of seconds the connection can wait.
-	cleanSession  bool                 // indicates if the client expects a clean-session.
-	packetID      uint32               // the current highest packetID.
-	LWT           LWT                  // the last will and testament for the client.
-	State         State                // the operational state of the client.
-	system        *system.Info         // pointers to server system info.
-}
-
-// State tracks the state of the client.
-type State struct {
-	Done    int64           // atomic counter which indicates that the client has closed.
-	started *sync.WaitGroup // tracks the goroutines which have been started.
-	endedW  *sync.WaitGroup // tracks when the writer has ended.
-	endedR  *sync.WaitGroup // tracks when the reader has ended.
-	endOnce sync.Once       // only end once.
-}
-
-// NewClient returns a new instance of Client.
-func NewClient(c net.Conn, r *circ.Reader, w *circ.Writer, s *system.Info) *Client {
-	cl := &Client{
-		conn:      c,
-		r:         r,
-		w:         w,
-		system:    s,
-		keepalive: defaultKeepalive,
-		Inflight: Inflight{
-			internal: make(map[uint16]InflightMessage),
-		},
-		Subscriptions: make(map[string]byte),
-		State: State{
-			started: new(sync.WaitGroup),
-			endedW:  new(sync.WaitGroup),
-			endedR:  new(sync.WaitGroup),
-		},
-	}
-
-	cl.refreshDeadline(cl.keepalive)
-
-	return cl
-}
-
-// NewClientStub returns an instance of Client with basic initializations. This
-// method is typically called by the persistence restoration system.
-func NewClientStub(s *system.Info) *Client {
-	return &Client{
-		Inflight: Inflight{
-			internal: make(map[uint16]InflightMessage),
-		},
-		Subscriptions: make(map[string]byte),
-		State: State{
-			Done: 1,
-		},
-	}
-}
-
-// Identify sets the identification values of a client instance.
-func (cl *Client) Identify(lid string, pk packets.Packet, ac auth.Controller) {
-	cl.Listener = lid
-	cl.AC = ac
-
-	cl.ID = pk.ClientIdentifier
-	if cl.ID == "" {
-		cl.ID = xid.New().String()
-	}
-
-	cl.r.ID = cl.ID + " READER"
-	cl.w.ID = cl.ID + " WRITER"
-
-	cl.Username = pk.Username
-	cl.cleanSession = pk.CleanSession
-	cl.keepalive = pk.Keepalive
-
-	if pk.WillFlag {
-		cl.LWT = LWT{
-			Topic:   pk.WillTopic,
-			Message: pk.WillMessage,
-			Qos:     pk.WillQos,
-			Retain:  pk.WillRetain,
-		}
-	}
-
-	cl.refreshDeadline(cl.keepalive)
-}
-
-// refreshDeadline refreshes the read/write deadline for the net.Conn connection.
-func (cl *Client) refreshDeadline(keepalive uint16) {
-	if cl.conn != nil {
-		var expiry time.Time // Nil time can be used to disable deadline if keepalive = 0
-		if keepalive > 0 {
-			expiry = time.Now().Add(time.Duration(keepalive+(keepalive/2)) * time.Second)
-		}
-		cl.conn.SetDeadline(expiry)
-	}
-}
-
-// NextPacketID returns the next packet id for a client, looping back to 0
-// if the maximum ID has been reached.
-func (cl *Client) NextPacketID() uint32 {
-	i := atomic.LoadUint32(&cl.packetID)
-	if i == uint32(65535) || i == uint32(0) {
-		atomic.StoreUint32(&cl.packetID, 1)
-		return 1
-	}
-
-	return atomic.AddUint32(&cl.packetID, 1)
-}
-
-// NoteSubscription makes a note of a subscription for the client.
-func (cl *Client) NoteSubscription(filter string, qos byte) {
-	cl.Lock()
-	cl.Subscriptions[filter] = qos
-	cl.Unlock()
-}
-
-// ForgetSubscription forgests a subscription note for the client.
-func (cl *Client) ForgetSubscription(filter string) {
-	cl.Lock()
-	delete(cl.Subscriptions, filter)
-	cl.Unlock()
-}
-
-// Start begins the client goroutines reading and writing packets.
-func (cl *Client) Start() {
-	cl.State.started.Add(2)
-
-	go func() {
-		cl.State.started.Done()
-		cl.w.WriteTo(cl.conn)
-		cl.State.endedW.Done()
-		cl.Stop()
-	}()
-	cl.State.endedW.Add(1)
-
-	go func() {
-		cl.State.started.Done()
-		cl.r.ReadFrom(cl.conn)
-		cl.State.endedR.Done()
-		cl.Stop()
-	}()
-	cl.State.endedR.Add(1)
-
-	cl.State.started.Wait()
-}
-
-// Stop instructs the client to shut down all processing goroutines and disconnect.
-func (cl *Client) Stop() {
-	if atomic.LoadInt64(&cl.State.Done) == 1 {
-		return
-	}
-
-	cl.State.endOnce.Do(func() {
-		cl.r.Stop()
-		cl.w.Stop()
-		cl.State.endedW.Wait()
-
-		cl.conn.Close()
-
-		cl.State.endedR.Wait()
-		atomic.StoreInt64(&cl.State.Done, 1)
-	})
-}
-
-// readFixedHeader reads in the values of the next packet's fixed header.
-func (cl *Client) ReadFixedHeader(fh *packets.FixedHeader) error {
-	p, err := cl.r.Read(1)
-	if err != nil {
-		return err
-	}
-
-	err = fh.Decode(p[0])
-	if err != nil {
-		return err
-	}
-
-	// The remaining length value can be up to 5 bytes. Read through each byte
-	// looking for continue values, and if found increase the read. Otherwise
-	// decode the bytes that were legit.
-	buf := make([]byte, 0, 6)
-	i := 1
-	n := 2
-	for ; n < 6; n++ {
-		p, err = cl.r.Read(n)
-		if err != nil {
-			return err
-		}
-
-		buf = append(buf, p[i])
-
-		// If it's not a continuation flag, end here.
-		if p[i] < 128 {
-			break
-		}
-
-		// If i has reached 4 without a length terminator, return a protocol violation.
-		i++
-		if i == 4 {
-			return packets.ErrOversizedLengthIndicator
-		}
-	}
-
-	// Calculate and store the remaining length of the packet payload.
-	rem, _ := binary.Uvarint(buf)
-	fh.Remaining = int(rem)
-
-	// Having successfully read n bytes, commit the tail forward.
-	cl.r.CommitTail(n)
-	atomic.AddInt64(&cl.system.BytesRecv, int64(n))
-
-	return nil
-}
-
-// Read reads new packets from a client connection
-func (cl *Client) Read(h func(*Client, packets.Packet) error) error {
-	for {
-		if atomic.LoadInt64(&cl.State.Done) == 1 && cl.r.CapDelta() == 0 {
-			return nil
-		}
-
-		cl.refreshDeadline(cl.keepalive)
-		fh := new(packets.FixedHeader)
-		err := cl.ReadFixedHeader(fh)
-		if err != nil {
-			return err
-		}
-
-		pk, err := cl.ReadPacket(fh)
-		if err != nil {
-			return err
-		}
-
-		err = h(cl, pk) // Process inbound packet.
-		if err != nil {
-			return err
-		}
-	}
-}
-
-// ReadPacket reads the remaining buffer into an MQTT packet.
-func (cl *Client) ReadPacket(fh *packets.FixedHeader) (pk packets.Packet, err error) {
-	atomic.AddInt64(&cl.system.MessagesRecv, 1)
-
-	pk.FixedHeader = *fh
-	if pk.FixedHeader.Remaining == 0 {
-		return
-	}
-
-	p, err := cl.r.Read(pk.FixedHeader.Remaining)
-	if err != nil {
-		return pk, err
-	}
-	atomic.AddInt64(&cl.system.BytesRecv, int64(len(p)))
-
-	// Decode the remaining packet values using a fresh copy of the bytes,
-	// otherwise the next packet will change the data of this one.
-	px := append([]byte{}, p[:]...)
-
-	switch pk.FixedHeader.Type {
-	case packets.Connect:
-		err = pk.ConnectDecode(px)
-	case packets.Connack:
-		err = pk.ConnackDecode(px)
-	case packets.Publish:
-		err = pk.PublishDecode(px)
-		if err == nil {
-			atomic.AddInt64(&cl.system.PublishRecv, 1)
-		}
-	case packets.Puback:
-		err = pk.PubackDecode(px)
-	case packets.Pubrec:
-		err = pk.PubrecDecode(px)
-	case packets.Pubrel:
-		err = pk.PubrelDecode(px)
-	case packets.Pubcomp:
-		err = pk.PubcompDecode(px)
-	case packets.Subscribe:
-		err = pk.SubscribeDecode(px)
-	case packets.Suback:
-		err = pk.SubackDecode(px)
-	case packets.Unsubscribe:
-		err = pk.UnsubscribeDecode(px)
-	case packets.Unsuback:
-		err = pk.UnsubackDecode(px)
-	case packets.Pingreq:
-	case packets.Pingresp:
-	case packets.Disconnect:
-	default:
-		err = fmt.Errorf("No valid packet available; %v", pk.FixedHeader.Type)
-	}
-
-	cl.r.CommitTail(pk.FixedHeader.Remaining)
-
-	return
-}
-
-// WritePacket encodes and writes a packet to the client.
-func (cl *Client) WritePacket(pk packets.Packet) (n int, err error) {
-	if atomic.LoadInt64(&cl.State.Done) == 1 {
-		return 0, ErrConnectionClosed
-	}
-
-	cl.w.Mu.Lock()
-	defer cl.w.Mu.Unlock()
-
-	buf := new(bytes.Buffer)
-	switch pk.FixedHeader.Type {
-	case packets.Connect:
-		err = pk.ConnectEncode(buf)
-	case packets.Connack:
-		err = pk.ConnackEncode(buf)
-	case packets.Publish:
-		err = pk.PublishEncode(buf)
-		if err == nil {
-			atomic.AddInt64(&cl.system.PublishSent, 1)
-		}
-	case packets.Puback:
-		err = pk.PubackEncode(buf)
-	case packets.Pubrec:
-		err = pk.PubrecEncode(buf)
-	case packets.Pubrel:
-		err = pk.PubrelEncode(buf)
-	case packets.Pubcomp:
-		err = pk.PubcompEncode(buf)
-	case packets.Subscribe:
-		err = pk.SubscribeEncode(buf)
-	case packets.Suback:
-		err = pk.SubackEncode(buf)
-	case packets.Unsubscribe:
-		err = pk.UnsubscribeEncode(buf)
-	case packets.Unsuback:
-		err = pk.UnsubackEncode(buf)
-	case packets.Pingreq:
-		err = pk.PingreqEncode(buf)
-	case packets.Pingresp:
-		err = pk.PingrespEncode(buf)
-	case packets.Disconnect:
-		err = pk.DisconnectEncode(buf)
-	default:
-		err = fmt.Errorf("No valid packet available; %v", pk.FixedHeader.Type)
-	}
-	if err != nil {
-		return
-	}
-
-	n, err = cl.w.Write(buf.Bytes())
-	if err != nil {
-		return
-	}
-	atomic.AddInt64(&cl.system.BytesSent, int64(n))
-	atomic.AddInt64(&cl.system.MessagesSent, 1)
-
-	cl.refreshDeadline(cl.keepalive)
-
-	return
-}
-
-// LWT contains the last will and testament details for a client connection.
-type LWT struct {
-	Topic   string // the topic the will message shall be sent to.
-	Message []byte // the message that shall be sent when the client disconnects.
-	Qos     byte   // the quality of service desired.
-	Retain  bool   // indicates whether the will message should be retained
-}
-
-// InflightMessage contains data about a packet which is currently in-flight.
-type InflightMessage struct {
-	Packet  packets.Packet // the packet currently in-flight.
-	Sent    int64          // the last time the message was sent (for retries) in unixtime.
-	Resends int            // the number of times the message was attempted to be sent.
-}
-
-// Inflight is a map of InflightMessage keyed on packet id.
-type Inflight struct {
-	sync.RWMutex
-	internal map[uint16]InflightMessage // internal contains the inflight messages.
-}
-
-// Set stores the packet of an Inflight message, keyed on message id. Returns
-// true if the inflight message was new.
-func (i *Inflight) Set(key uint16, in InflightMessage) bool {
-	i.Lock()
-	_, ok := i.internal[key]
-	i.internal[key] = in
-	i.Unlock()
-	return !ok
-}
-
-// Get returns the value of an in-flight message if it exists.
-func (i *Inflight) Get(key uint16) (InflightMessage, bool) {
-	i.RLock()
-	val, ok := i.internal[key]
-	i.RUnlock()
-	return val, ok
-}
-
-// Len returns the size of the in-flight messages map.
-func (i *Inflight) Len() int {
-	i.RLock()
-	v := len(i.internal)
-	i.RUnlock()
-	return v
-}
-
-// GetAll returns all the in-flight messages.
-func (i *Inflight) GetAll() map[uint16]InflightMessage {
-	i.RLock()
-	defer i.RUnlock()
-	return i.internal
-}
-
-// Delete removes an in-flight message from the map. Returns true if the
-// message existed.
-func (i *Inflight) Delete(key uint16) bool {
-	i.Lock()
-	_, ok := i.internal[key]
-	delete(i.internal, key)
-	i.Unlock()
-	return ok
-}