This is an automated email from the ASF dual-hosted git repository.
popduke pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bifromq-sites.git
The following commit(s) were added to refs/heads/master by this push:
new b6f45122 Add SPI doc
b6f45122 is described below
commit b6f451221d49debf652b6b1f3f011a40d0fb1884
Author: Yonny Hao <[email protected]>
AuthorDate: Mon Dec 22 11:44:18 2025 +0800
Add SPI doc
---
docs/admin_guide/_category_.json | 2 +-
docs/benchmark/_category_.json | 2 +-
docs/contribution_guide/_category_.json | 4 ++--
docs/spi/_category_.json | 8 +++++++
docs/spi/intro.md | 40 +++++++++++++++++++++++++++++++++
5 files changed, 52 insertions(+), 4 deletions(-)
diff --git a/docs/admin_guide/_category_.json b/docs/admin_guide/_category_.json
index 42000548..80846ec7 100644
--- a/docs/admin_guide/_category_.json
+++ b/docs/admin_guide/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Administration",
- "position": 7,
+ "position": 8,
"link": {
"type": "doc",
"id": "admin_guide/overview"
diff --git a/docs/benchmark/_category_.json b/docs/benchmark/_category_.json
index 3e4d8551..4fd559c8 100644
--- a/docs/benchmark/_category_.json
+++ b/docs/benchmark/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Benchmark",
- "position": 8,
+ "position": 9,
"link": {
"type": "doc",
"id": "benchmark/overview"
diff --git a/docs/contribution_guide/_category_.json
b/docs/contribution_guide/_category_.json
index 5d59fcce..2d0bd9da 100644
--- a/docs/contribution_guide/_category_.json
+++ b/docs/contribution_guide/_category_.json
@@ -1,6 +1,6 @@
{
- "label": "Contribution",
- "position": 9,
+ "label": "Contribution Guide",
+ "position": 10,
"link": {
"type": "doc",
"id": "contribution_guide/intro"
diff --git a/docs/spi/_category_.json b/docs/spi/_category_.json
new file mode 100644
index 00000000..c854b5fd
--- /dev/null
+++ b/docs/spi/_category_.json
@@ -0,0 +1,8 @@
+{
+ "label": "SPI",
+ "position": 7,
+ "link": {
+ "type": "doc",
+ "id": "spi/intro"
+ }
+}
diff --git a/docs/spi/intro.md b/docs/spi/intro.md
new file mode 100644
index 00000000..1c8ff5f1
--- /dev/null
+++ b/docs/spi/intro.md
@@ -0,0 +1,40 @@
+---
+id: intro
+title: "SPI Overview"
+sidebar_position: 0
+---
+
+Service Provider Interfaces (SPIs) are extension points that let you customize
BifroMQ’s own runtime behavior. They share the same process and execution
context as BifroMQ, and are intended for shaping core behaviors rather than
integrating external systems.
+
+:::note Important
+
+- SPIs run inside BifroMQ’s process and share its execution context; a deep
understanding of internal workflows is required to avoid stability and
performance regressions.
+- ABI compatibility is **not guaranteed across releases**, and these
interfaces are **not published to Maven**. Keep your SPI implementation
version-aligned with the BifroMQ runtime you deploy.
+- SPIs may change or new ones may appear as the project evolves; verify
compatibility before upgrading.
+ :::
+
+## When to use SPI vs. Plugin
+
+- **SPI**: Extend/Customize BifroMQ itself (e.g., define custom MQTT message
UserProperties or add workload-specific balancing strategies) via Java’s SPI
mechanism. Runs in-process and shares BifroMQ’s context.
+- **Plugin**: Integrate BifroMQ with external systems (e.g., call an external
authentication/authorization service). Plugins run in their own ClassLoader
context and are relatively isolated.
+
+## SPI Development Tips
+
+Consult the official Java SPI documentation to understand how discovery and
registration work; the following tips highlight BifroMQ-specific considerations:
+
+- Fetch the BifroMQ source for the exact runtime version you will deploy; SPI
interfaces are not published to Maven Central.
+- Keep your SPI project and the BifroMQ source in a single IDE workspace so
you can reference the SPI modules directly without relying on published
artifacts.
+- Some SPIs only use the first discovered implementation—deploy a single
implementation for those to avoid unexpected behavior. Others can be selected
explicitly via configuration, which avoids conflicts.
+- Run and debug with the broker in that workspace (same version), adding
logs/metrics to validate behavior.
+- Rebuild and retest whenever you upgrade BifroMQ, since interfaces may change
across releases.
+
+## Available SPIs
+
+- `base-env-provider-spi`: Provide customized thread environment/context.
+- `base-kv-local-engine-spi`: Customize the local KV engine used by base-kv.
+- `base-kv-split-hinter-spi`: Influence KV partitioning/splitting strategies.
+- `base-kv-store-balancer-spi`: Introduce custom balancing strategies.
+- `bifromq-dist-worker-spi`: Introduce custom balancers to dist worker cluster.
+- `bifromq-inbox-store-spi`: Introduce custom balancers to inbox store cluster.
+- `bifromq-retain-store-spi`: Introduce custom balancers to retain store
cluster.
+- `bifromq-mqtt-server-spi`: Extend MQTT server behaviors (e.g., customized
user properties hooks).
