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 7a4aa2a 1. add client balancer doc 2. update admin_guide 3. fix
deploy warning
7a4aa2a is described below
commit 7a4aa2a6927326ea36f75af3c947d3cae5bba883
Author: Yonny Hao <[email protected]>
AuthorDate: Tue Jun 24 11:53:42 2025 +0800
1. add client balancer doc
2. update admin_guide
3. fix deploy warning
---
.github/workflows/ci.yml | 45 --------------
.github/workflows/deploy-staging.yml | 1 -
.../admin_guide/configuration/bifromq_sys_props.md | 72 +++++++++-------------
.../configuration/config_file_manual.md | 12 ++--
docs/admin_guide/configuration/configs_print.md | 37 +++++------
docs/benchmark/_category_.json | 8 +++
docs/benchmark/intro.md | 7 +++
docs/contribution_guide/_category_.json | 8 +++
docs/contribution_guide/intro.md | 7 +++
docs/plugin/client_balancer.md | 58 +++++++++++++++++
licenserc.toml | 32 ----------
11 files changed, 139 insertions(+), 148 deletions(-)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
deleted file mode 100644
index 88071e5..0000000
--- a/.github/workflows/ci.yml
+++ /dev/null
@@ -1,45 +0,0 @@
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements. See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership. The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied. See the License for the
-# specific language governing permissions and limitations
-# under the License.
-
-name: CI
-on:
- pull_request:
- branches: [master]
- push:
- branches: [master]
-
-# Concurrency strategy:
-# github.workflow: distinguish this workflow from others
-# github.event_name: distinguish `push` event from `pull_request` event
-# github.event.number: set to the number of the pull request if
`pull_request` event
-# github.run_id: otherwise, it's a `push` event, only cancel if we rerun the
workflow
-#
-# Reference:
-# https://docs.github.com/en/actions/using-jobs/using-concurrency
-#
https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
-concurrency:
- group: ${{ github.workflow }}-${{ github.event_name }}-${{
github.event.number || github.run_id }}
- cancel-in-progress: true
-
-jobs:
- check:
- name: Check
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- - uses: korandoru/hawkeye@v4
-# TODO: enable markdownlint & typos
diff --git a/.github/workflows/deploy-staging.yml
b/.github/workflows/deploy-staging.yml
index 42de205..9ccc712 100644
--- a/.github/workflows/deploy-staging.yml
+++ b/.github/workflows/deploy-staging.yml
@@ -42,4 +42,3 @@ jobs:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./build
publish_branch: asf-staging
- clean: true
diff --git a/docs/admin_guide/configuration/bifromq_sys_props.md
b/docs/admin_guide/configuration/bifromq_sys_props.md
index ca8261b..e7cddef 100644
--- a/docs/admin_guide/configuration/bifromq_sys_props.md
+++ b/docs/admin_guide/configuration/bifromq_sys_props.md
@@ -9,47 +9,31 @@ For example, setting `-Dmqtt_utf8_sanity_check=false`
disables the check for MQT
Below is a table listing the system properties supported by the current
version:
-| Property Key | Default Value |
Description
[...]
-|----------------------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
-| `cluster_domain_resolve_timeout_seconds` | 120 | This
parameter specifies the timeout duration for DNS resolution when constructing a
cluster using the "clusterConfig.clusterDomainName". The process involves
resolving the cluster domain to discover seed nodes that can join the cluster.
A successful resolution is marked by obtaining a non-empty set of IP addresses.
This parameter controls the maximum amount of time allowed for this DNS
resolution to complete succes [...]
-| `ingress_slowdown_direct_memory_usage` | 0.95 |
Threshold for slowing down the acceptance of ingress traffic based on direct
memory usage. When the direct memory usage exceeds this threshold, the system
will begin to slow down incoming traffic to manage resource consumption
effectively.
[...]
-| `ingress_slowdown_heap_memory_usage` | 0.9 |
Threshold for slowing down the acceptance of ingress traffic based on heap
memory usage. When the heap memory usage exceeds this threshold, the system
will initiate measures to slow down incoming traffic to prevent memory
overload.
[...]
-| `max_slowdown_timeout_seconds` | 5 |
Maximum duration (in seconds) that the slowdown mechanism is allowed to operate
before further backpressure protection measures are taken. This ensures that if
the slowdown is not sufficient to manage resource usage, additional steps will
be implemented to protect the system.
[...]
-| `mqtt_utf8_sanity_check` | false |
Enables/disables UTF8 sanity checks according to MQTT-1.5.3.
[...]
-| `max_mqtt3_client_id_length` | 65535 |
Maximum client ID length for MQTT 3 clients.
[...]
-| `max_mqtt5_client_id_length` | 65535 |
Maximum client ID length for MQTT 5 clients.
[...]
-| `session_register_num` | 1000 |
Number of concurrent session registers.
[...]
-| `data_plane_tolerable_latency_ms` | 1000L |
Tolerable latency in milliseconds for the data plane.
[...]
-| `data_plane_burst_latency_ms` | 5000L | Burst
latency in milliseconds for the data plane.
[...]
-| `control_plane_tolerable_latency_ms` | 2000L |
Tolerable latency in milliseconds for the control plane.
[...]
-| `control_plane_burst_latency_ms` | 5000L | Burst
latency in milliseconds for the control plane.
[...]
-| `dist_server_dist_worker_call_queues` | CPU cores |
Number of dist worker call queues.
[...]
-| `dist_worker_fanout_parallelism` | Max(2, CPU cores) |
Parallelism level for fanout operations.
[...]
-| `dist_worker_max_cached_subs_per_tenant` | 200_000L |
Maximum cached subscriptions per tenant.
[...]
-| `dist_worker_topic_match_expiry_seconds` | 5 |
Expiry time in seconds for topic matches.
[...]
-| `dist_worker_match_parallelism` | Max(2, CPU cores / 2) |
Parallelism level for match operations.
[...]
-| `dist_worker_fanout_split_threshold` | 100000 |
Threshold for splitting fanout operations when fanout split hinter enabled.
[...]
-| `dist_worker_split_max_cpu_usage` | 0.8 |
Maximum CPU usage threshold for splitting operations when fanout split hinter
enabled.
[...]
-| `dist_worker_load_estimation_window_seconds` | 5L | Time
window in seconds for load estimation when fanout split hinter enabled.
[...]
-| `dist_worker_split_io_nanos_limit` | 30_000L |
Nanoseconds limit for I/O operations during split when fanout split hinter
enabled.
[...]
-| `dist_worker_split_max_io_density` | 100 |
Maximum I/O density for split operations when fanout split hinter enabled.
[...]
-| `dist_worker_range_voter_count` | 3 |
Number of voters for range decisions.
[...]
-| `dist_worker_recovery_timeout_millis` | 10000L |
Timeout in milliseconds for worker recovery when recovery balancer enabled.
[...]
-| `inbox_deliverers` | 100 |
Number of inbox deliverers.
[...]
-| `inbox_fetch_queues_per_range` | Max(1, CPU cores / 4) |
Number of fetch queues per range.
[...]
-| `inbox_check_queues_per_range` | 1 |
Number of check queues per range.
[...]
-| `inbox_store_load_estimation_window_seconds` | 5L | Time
window in seconds for load estimation in inbox store.
[...]
-| `inbox_store_range_split_limit` | Max(1, CPU cores / 4) | Range
split will stop when local inbox store hits the limit.
[...]
-| `inbox_store_range_split_max_cpu_usage` | 0.8 |
Maximum CPU usage threshold for range split in inbox store.
[...]
-| `inbox_store_range_split_io_nanos_limit` | 30_000 |
Nanoseconds limit for I/O operations during range split in inbox store.
[...]
-| `inbox_store_range_split_max_io_density` | 100 |
Maximum I/O density for range split operations in inbox store.
[...]
-| `inbox_store_range_voter_count` | 1 |
Number of voters for range decisions in inbox store.
[...]
-| `inbox_store_recovery_timeout_millis` | 10000L |
Timeout in milliseconds for inbox store recovery.
[...]
-| `mqtt_deliverers_per_server` | CPU cores |
Number of MQTT deliverers per server.
[...]
-| `retain_store_range_split_limit` | Max(1, CPU cores / 4) | Range
split will stop when local retain store hits the limit.
[...]
-| `retain_store_range_split_max_cpu_usage` | 0.8 |
Maximum CPU usage threshold for range split in retain store.
[...]
-| `retain_store_range_split_io_nanos_limit` | 30_000L |
Nanoseconds limit for I/O operations during range split in retain store.
[...]
-| `retain_store_range_split_max_io_density` | 100 |
Maximum I/O density for range split operations in retain store.
[...]
-| `retain_store_range_voter_count` | 3 |
Number of voters for range decisions in retain store.
[...]
-| `retain_store_load_est_window_seconds` | 5L | Time
window in seconds for load estimation in retain store.
[...]
-| `retain_store_recovery_timeout_millis` | 10000L |
Timeout in milliseconds for retain store recovery.
[...]
\ No newline at end of file
+| Property Key | Default Value |
Description
[...]
+| --------------------------------------------- | --------------------- |
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| `client_redirect_check_interval_seconds` | 600 | The
client redirection check interval in seconds
[...]
+| `cluster_domain_resolve_timeout_seconds` | 120 | This
parameter specifies the timeout duration for DNS resolution when constructing a
cluster using the "clusterConfig.clusterDomainName". The process involves
resolving the cluster domain to discover seed nodes that can join the cluster.
A successful resolution is marked by obtaining a non-empty set of IP addresses.
This parameter controls the maximum amount of time allowed for this DNS
resolution to complete succe [...]
+| `control_plane_burst_latency_ms` | 5000L | The
max latency in milliseconds tolerated for the control plane burst.
[...]
+| `data_plane_burst_latency_ms` | 5000L | The
max latency in milliseconds tolerated for the data plane burst.
[...]
+| `dist_server_dist_worker_call_queues` | CPU cores |
Number of dist worker call queues.
[...]
+| `dist_worker_inline_fanout_threshold` | 1000 | The
threshold of the fanout to be executed in calling thread
[...]
+| `dist_worker_fanout_parallelism` | Max(2, CPU cores) |
Parallelism level for fanout operations.
[...]
+| `dist_worker_fanout_split_threshold` | 100000 |
Threshold for splitting fanout operations when fanout split hinter enabled.
[...]
+| `dist_worker_load_estimation_window_seconds` | 5L | Time
window in seconds for load estimation when fanout split hinter enabled.
[...]
+| `dist_worker_match_parallelism` | Max(2, CPU cores / 2) |
Parallelism level for match operations.
[...]
+| `dist_worker_max_cached_subs_per_tenant` | 200_000L |
Maximum cached subscriptions per tenant.
[...]
+| `dist_worker_topic_match_expiry_seconds` | 5 |
Expiry time in seconds for topic matches.
[...]
+| `inbox_check_queues_per_range` | 1 |
Number of check queues per range.
[...]
+| `inbox_deliverers` | 100 |
Number of inbox deliverers.
[...]
+| `inbox_fetch_queues_per_range` | Max(1, CPU cores / 4) |
Number of fetch queues per range.
[...]
+| `inbox_store_load_estimation_window_seconds` | 5L | Time
window in seconds for load estimation in inbox store.
[...]
+| `ingress_slowdown_direct_memory_usage` | 0.95 |
Threshold for slowing down the acceptance of ingress traffic based on direct
memory usage. When the direct memory usage exceeds this threshold, the system
will begin to slow down incoming traffic to manage resource consumption
effectively.
[...]
+| `ingress_slowdown_heap_memory_usage` | 0.9 |
Threshold for slowing down the acceptance of ingress traffic based on heap
memory usage. When the heap memory usage exceeds this threshold, the system
will initiate measures to slow down incoming traffic to prevent memory
overload.
[...]
+| `mqtt_utf8_sanity_check` | false |
Enables/disables UTF8 sanity checks according to MQTT-1.5.3.
[...]
+| `max_mqtt3_client_id_length` | 65535 |
Maximum client ID length for MQTT 3 clients.
[...]
+| `max_mqtt5_client_id_length` | 65535 |
Maximum client ID length for MQTT 5 clients.
[...]
+| `max_slowdown_timeout_seconds` | 5 |
Maximum duration (in seconds) that the slowdown mechanism is allowed to operate
before further backpressure protection measures are taken. This ensures that if
the slowdown is not sufficient to manage resource usage, additional steps will
be implemented to protect the system.
[...]
+| `mqtt_deliverers_per_server` | CPU cores |
Number of MQTT deliverers per server.
[...]
+| `persistent_session_detach_timeout_second` | 7200 | The
timeout seconds to consider persistent session is probably detached from mqtt
client.
[...]
+| `retain_store_load_estimation_window_seconds` | 5L | Time
window in seconds for load estimation in retain store.
[...]
+| `session_register_num` | 1000 |
Number of concurrent session registers.
[...]
diff --git a/docs/admin_guide/configuration/config_file_manual.md
b/docs/admin_guide/configuration/config_file_manual.md
index a82697f..602e637 100644
--- a/docs/admin_guide/configuration/config_file_manual.md
+++ b/docs/admin_guide/configuration/config_file_manual.md
@@ -11,9 +11,9 @@ The complete configuration file is defined by a set of
configuration objects, wi
## StandaloneConfig
| Configuration Name | Value
Type | Default Value | Description
|
-|----------------------------------------------------------------------|------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `bootstrap` |
Boolean | false | If the node is
responsible for cluster bootstrapping, this value should be set to true.
Otherwise, it should be set to false. Note: In cluster deployments, there must
be **exactly one** bootstrap node.
|
+| -------------------------------------------------------------------- |
---------------------- | -------------------------- |
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
| `authProviderFQN` |
String | null | Fully qualified class
name of the custom Auth Provider implementation. If not configured,
authentication and authorization will not be performed.
|
+| `clientBalancerFQN` |
String | null | Fully qualified class
name of the custom Client Balancer implementation. If not configured, no active
redirection happens.
|
| `resourceThrottlerFQN` |
String | null | Fully qualified class
name of the custom Resource Throttler implementation. If not configured,
resource limiting will not be performed.
|
| `settingProviderFQN` |
String | null | Fully qualified class
name of the custom Setting Provider implementation. If not configured, default
initial values defined in Settings will be used.
|
| `clusterConfig.env` |
String | "Test" | Cluster environment name.
Cluster nodes with different environment names are isolated from each other.
Cannot be null or an empty string.
|
@@ -90,7 +90,7 @@ SSLContextConfig is used to configure the SSL connection
parameters for the clie
If you leave SSLContextConfig or ServerSSLContextConfig set to null while the
corresponding `enable` flags are set to true, a self-signed certificate will be
generated, which is not recommended for production environments.
| Configuration Name | Value Type | Default Value | Description
|
-|--------------------|------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ------------------ | ---------- | ------------- |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
| `certFile` | String | null | The filename of the public
certificate for the client or server.
|
| `keyFile` | String | null | The filename of the
private key for the client or server.
|
| `trustCertsFile` | String | null | The filename of the root
certificate for the client or server. If null, peer certification will not be
verified, when clientAuth is OPTIONAL or REQUIRE.
|
@@ -101,7 +101,7 @@ If you leave SSLContextConfig or ServerSSLContextConfig set
to null while the co
StorageEngineConfig is used to set the configuration parameters for the data
engine and WAL engine of the built-in state service.
| Configuration Name | Value Type | Description
|
-|---------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ------------------------- | ---------- |
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
| `type` | String | Specifies the type of data engine
used in the built-in storage service. Options include: rocksdb: Provides
persistence functionality, allowing state to be recovered after a restart;
memory: No persistence, data will be lost after a restart.
|
| `dataPathRoot` | String | Effective when type is set to
rocksdb. Specifies the directory to store data files. If configured as an
absolute path, it will be directly loaded; if configured as a relative path, it
will try to load from the directory specified by the `DATA_DIR` and `user.dir`
system parameters. |
| `compactMinTombstoneKeys` | Integer | Effective when type is set to
rocksdb. The number of Tombstone keys that trigger a compaction operation.
|
@@ -114,9 +114,9 @@ StorageEngineConfig is used to set the configuration
parameters for the data eng
BalancerOptions is used to set the configuration parameters for the Balancer
of the built-in state service.
| Configuration Name | Value Type | Default Value | Description
|
-|------------------------|----------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ---------------------- | -------------- | ------------- |
------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
| `scheduleIntervalInMs` | Long | 5000 | The interval at
which the Balancer attempts to balance the load.
|
| `balancers` | List of String | | The fully
qualified names of the balancer implementations that are enabled. Different
balancer implementations can be set for different built-in storage services. |
Note: Adjusting the parameters related to StorageEngineConfig and
BalancerOptions requires an in-depth understanding of the storage engine
implementation of BifroMQ. Improper configuration may lead to abnormal behavior
of the state storage
-service.
\ No newline at end of file
+service.
diff --git a/docs/admin_guide/configuration/configs_print.md
b/docs/admin_guide/configuration/configs_print.md
index ec5e00f..9818159 100644
--- a/docs/admin_guide/configuration/configs_print.md
+++ b/docs/admin_guide/configuration/configs_print.md
@@ -17,7 +17,7 @@ The printed configuration information in the logs consists of
four main parts:
JVM parameters refer to the parameters passed to the JVM when starting BifroMQ
using the `-D` parameter. An example of the printed output is as follows:
```text
-15:21:46.890 [main] INFO c.b.b.starter.StandaloneStarter - JVM arguments:
+15:21:46.890 [main] INFO o.a.b.starter.StandaloneStarter - JVM arguments:
-Xms1045m
-Xmx4096m
-Xlog:gc:file=/usr/share/bifromq-standalone/bin/../logs/gc-%t.log:time,tid,tags:filecount=5,filesize=50m
@@ -36,15 +36,15 @@ It is important to note that the printed values here
represent the initial value
necessarily be the actual runtime values. An example of the printed output is
as follows:
```text
-15:21:46.890 [main] INFO c.b.b.starter.StandaloneStarter - Settings, which can
be modified at runtime, allowing for dynamic adjustment of BifroMQ's service
behavior per tenant. See https://bifromq.io/docs/plugin/setting_provider/
-15:21:46.890 [main] INFO c.b.b.starter.StandaloneStarter - Following is the
initial value of each setting:
-15:21:46.913 [main] INFO c.b.b.starter.StandaloneStarter - Setting:
DebugModeEnabled=false
-15:21:46.913 [main] INFO c.b.b.starter.StandaloneStarter - Setting:
MaxTopicLevelLength=40
-15:21:46.913 [main] INFO c.b.b.starter.StandaloneStarter - Setting:
MaxTopicLevels=16
-15:21:46.913 [main] INFO c.b.b.starter.StandaloneStarter - Setting:
MaxTopicLength=255
-15:21:46.913 [main] INFO c.b.b.starter.StandaloneStarter - Setting:
MaxSharedGroupMembers=200
-15:21:46.913 [main] INFO c.b.b.starter.StandaloneStarter - Setting:
MaxTopicFiltersPerInbox=100
-15:21:46.913 [main] INFO c.b.b.starter.StandaloneStarter - Setting:
MsgPubPerSec=200
+15:21:46.890 [main] INFO o.a.b.starter.StandaloneStarter - Settings, which can
be modified at runtime, allowing for dynamic adjustment of BifroMQ's service
behavior per tenant. See https://bifromq.io/docs/plugin/setting_provider/
+15:21:46.890 [main] INFO o.a.b.starter.StandaloneStarter - Following is the
initial value of each setting:
+15:21:46.913 [main] INFO o.a.b.starter.StandaloneStarter - Setting:
DebugModeEnabled=false
+15:21:46.913 [main] INFO o.a.b.starter.StandaloneStarter - Setting:
MaxTopicLevelLength=40
+15:21:46.913 [main] INFO o.a.b.starter.StandaloneStarter - Setting:
MaxTopicLevels=16
+15:21:46.913 [main] INFO o.a.b.starter.StandaloneStarter - Setting:
MaxTopicLength=255
+15:21:46.913 [main] INFO o.a.b.starter.StandaloneStarter - Setting:
MaxSharedGroupMembers=200
+15:21:46.913 [main] INFO o.a.b.starter.StandaloneStarter - Setting:
MaxTopicFiltersPerInbox=100
+15:21:46.913 [main] INFO o.a.b.starter.StandaloneStarter - Setting:
MsgPubPerSec=200
...
```
@@ -53,14 +53,12 @@ necessarily be the actual runtime values. An example of the
printed output is as
An example of the printed output is as follows:
```text
-17:21:34.067 [main] INFO c.b.b.starter.StandaloneStarter - BifroMQ system
properties:
-17:21:34.070 [main] INFO c.b.b.starter.StandaloneStarter - BifroMQSysProp:
mqtt_utf8_sanity_check=false
-17:21:34.070 [main] INFO c.b.b.starter.StandaloneStarter - BifroMQSysProp:
max_client_id_length=65535
-17:21:34.070 [main] INFO c.b.b.starter.StandaloneStarter - BifroMQSysProp:
session_register_num=1000
-17:21:34.070 [main] INFO c.b.b.starter.StandaloneStarter - BifroMQSysProp:
data_plane_tolerable_latency_ms=100
-17:21:34.070 [main] INFO c.b.b.starter.StandaloneStarter - BifroMQSysProp:
data_plane_burst_latency_ms=1000
-17:21:34.070 [main] INFO c.b.b.starter.StandaloneStarter - BifroMQSysProp:
control_plane_tolerant_latency_ms=200
-17:21:34.070 [main] INFO c.b.b.starter.StandaloneStarter - BifroMQSysProp:
control_plane_burst_latency_ms=5000
+17:21:34.067 [main] INFO o.a.b.starter.StandaloneStarter - BifroMQ system
properties:
+17:21:34.070 [main] INFO o.a.b.starter.StandaloneStarter - BifroMQSysProp:
mqtt_utf8_sanity_check=false
+17:21:34.070 [main] INFO o.a.b.starter.StandaloneStarter - BifroMQSysProp:
max_client_id_length=65535
+17:21:34.070 [main] INFO o.a.b.starter.StandaloneStarter - BifroMQSysProp:
session_register_num=1000
+17:21:34.070 [main] INFO o.a.b.starter.StandaloneStarter - BifroMQSysProp:
data_plane_burst_latency_ms=1000
+17:21:34.070 [main] INFO o.a.b.starter.StandaloneStarter - BifroMQSysProp:
control_plane_burst_latency_ms=5000
...
```
@@ -69,9 +67,8 @@ An example of the printed output is as follows:
The configuration file section will include the consolidated complete content
of the configuration file, with an example of the output as follows:
```text
-17:21:34.098 [main] INFO c.b.b.starter.StandaloneStarter - Consolidated
Config:
+17:21:34.098 [main] INFO o.a.b.starter.StandaloneStarter - Consolidated
Config:
---
-bootstrap: true
clusterConfig:
env: "Test"
host: "127.0.0.1"
diff --git a/docs/benchmark/_category_.json b/docs/benchmark/_category_.json
new file mode 100644
index 0000000..3e4d855
--- /dev/null
+++ b/docs/benchmark/_category_.json
@@ -0,0 +1,8 @@
+{
+ "label": "Benchmark",
+ "position": 8,
+ "link": {
+ "type": "doc",
+ "id": "benchmark/overview"
+ }
+}
diff --git a/docs/benchmark/intro.md b/docs/benchmark/intro.md
new file mode 100644
index 0000000..627292c
--- /dev/null
+++ b/docs/benchmark/intro.md
@@ -0,0 +1,7 @@
+---
+id: "overview"
+sidebar_position: 0
+title: "Benchmark Overview"
+---
+
+Coming Soon...
diff --git a/docs/contribution_guide/_category_.json
b/docs/contribution_guide/_category_.json
new file mode 100644
index 0000000..de642b8
--- /dev/null
+++ b/docs/contribution_guide/_category_.json
@@ -0,0 +1,8 @@
+{
+ "label": "Contribution",
+ "position": 9,
+ "link": {
+ "type": "doc",
+ "id": "contribution_guide/overview"
+ }
+}
diff --git a/docs/contribution_guide/intro.md b/docs/contribution_guide/intro.md
new file mode 100644
index 0000000..bf83027
--- /dev/null
+++ b/docs/contribution_guide/intro.md
@@ -0,0 +1,7 @@
+---
+id: "overview"
+sidebar_position: 0
+title: "Contribution Guide"
+---
+
+Coming Soon...
diff --git a/docs/plugin/client_balancer.md b/docs/plugin/client_balancer.md
index aada774..f52d6cc 100644
--- a/docs/plugin/client_balancer.md
+++ b/docs/plugin/client_balancer.md
@@ -2,3 +2,61 @@
sidebar_position: 2
title: "Client Balancer"
---
+
+The Client Balancer plugin enables BifroMQ to inject redirection strategies at
runtime, providing active control over client connections to manage load
distribution.
+
+To integrate the Client Balancer plugin into your BifroMQ deployment, include
the following Maven dependency:
+
+```xml
+<dependency>
+ <groupId>org.apache.bifromq</groupId>
+ <artifactId>bifromq-plugin-client-balancer</artifactId>
+ <version>X.Y.Z</version> <!-- Replace X.Y.Z with the latest version number
-->
+</dependency>
+```
+
+## Configuration
+
+BifroMQ operates with a single `ClientBalancer` instance. You must specify the
fully qualified class name (FQN) of your implementation in the [configuration
file](../admin_guide/configuration/config_file_manual.md):
+
+```yaml
+clientBalancerFQN: "YOUR_CLIENT_BALANCER_CLASS"
+```
+
+## Client Redirection
+
+The `ClientBalancer` interface defines a single method that is invoked by
BifroMQ to decide whether a client connection should be redirected:
+
+```java
+Optional<Redirection> needRedirect(ClientInfo clientInfo);
+```
+
+When BifroMQ determines it's time to evaluate redirection, it calls this
method. If a non-empty `Optional` is returned, the client connection will be
actively disconnected based on the returned redirection hint.
+
+The `Redirection` record carries the disconnection hint:
+
+```java
+public record Redirection(boolean permanentMove, Optional<String>
serverReference) { }
+```
+
+When the client uses the MQTT 5.0 protocol, BifroMQ maps the redirection
information to MQTT disconnect semantics:
+
+- If `permanentMove` is `true`, the client receives `Server moved (0x9D)`
reason code.
+- If `permanentMove` is `false`, the client receives `Use another server
(0x9C)` reason code.
+- If `serverReference` is present, its value is included in the `Server
Reference` field of the disconnect packet.
+
+## Redirection Evaluation Timing
+
+- **Post-authentication check**: Immediately after a client's authentication,
BifroMQ invokes `needRedirect` to determine if the connection should be
redirected.
+- **Periodic check**: For already established connections, BifroMQ
periodically invokes `needRedirect` to evaluate if a redirection is needed.
+
+The default periodic check interval is **600 seconds**. This interval can be
adjusted using the [system
property](../admin_guide/configuration/bifromq_sys_props.md):
`client_redirect_check_interval_seconds`
+
+## Performance Considerations
+
+The `ClientBalancer` executes within BifroMQ's core worker threads. Its
implementation should remain lightweight and efficient to avoid degrading
system performance.
+
+BifroMQ collects metrics to monitor the plugin's performance:
+
+- **`call.exec.timer`**: Tracks the execution duration and frequency of
`needRedirect` invocations.
+- **`call.exec.fail.count`**: Counts the number of exceptions thrown during
`needRedirect` calls.
diff --git a/licenserc.toml b/licenserc.toml
deleted file mode 100644
index dda7ce0..0000000
--- a/licenserc.toml
+++ /dev/null
@@ -1,32 +0,0 @@
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements. See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership. The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied. See the License for the
-# specific language governing permissions and limitations
-# under the License.
-
-headerPath = "Apache-2.0-ASF.txt"
-
-excludes = [
- # Website generated files
- "build",
- ".docusaurus",
-
- # Documents
- "**/*.md",
- "**/*.mdx",
-
- # Meta files
- "NOTICE",
- ".nojekyll",
-]
