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
commit f3006258fc701093f40c660226cf87ee550bd136 Author: Yonny Hao <[email protected]> AuthorDate: Tue Dec 2 15:31:58 2025 +0800 Support dynamic version in docs --- docs/admin_guide/configuration/configs_print.md | 2 +- docs/admin_guide/configuration/intro.md | 2 +- docs/admin_guide/observability/events.md | 2 +- docs/admin_guide/observability/metrics/intro.md | 2 +- docs/admin_guide/security/intro.md | 2 +- docs/get_started/faq.md | 10 +++---- .../{quick_install.md => quick_install.mdx} | 10 +++++-- docs/installation/{docker.md => docker.mdx} | 31 +++++++++----------- docs/installation/install_from_source.md | 31 -------------------- docs/installation/install_from_source.mdx | 30 ++++++++++++++++++++ .../plugin/{auth_provider.md => auth_provider.mdx} | 12 ++++---- .../{client_balancer.md => client_balancer.mdx} | 11 ++++---- .../{event_collector.md => event_collector.mdx} | 12 ++++---- docs/plugin/intro.md | 10 +++---- .../{plugin_practice.md => plugin_practice.mdx} | 33 +++++++++++----------- ...esource_throttler.md => resource_throttler.mdx} | 14 ++++----- .../setting_provider/{intro.md => intro.mdx} | 12 ++++---- docs/user_guide/basic/connect.md | 2 +- docs/user_guide/basic/intro.md | 4 +-- docs/user_guide/intro.md | 4 +-- 20 files changed, 117 insertions(+), 119 deletions(-) diff --git a/docs/admin_guide/configuration/configs_print.md b/docs/admin_guide/configuration/configs_print.md index 98181597..9bc98064 100644 --- a/docs/admin_guide/configuration/configs_print.md +++ b/docs/admin_guide/configuration/configs_print.md @@ -30,7 +30,7 @@ JVM parameters refer to the parameters passed to the JVM when starting BifroMQ u ### Setting Initial Values -For information about Settings and their initial values, refer to: [Setting Provider Plugin](../../plugin/setting_provider/intro.md). +For information about Settings and their initial values, refer to: [Setting Provider Plugin](../../plugin/setting_provider/intro.mdx). It is important to note that the printed values here represent the initial values of Setting when BifroMQ starts. These values can be modified at runtime using your custom Setting Provider Plugin, so the values printed here may not necessarily be the actual runtime values. An example of the printed output is as follows: diff --git a/docs/admin_guide/configuration/intro.md b/docs/admin_guide/configuration/intro.md index c7bbd440..339656fc 100644 --- a/docs/admin_guide/configuration/intro.md +++ b/docs/admin_guide/configuration/intro.md @@ -4,7 +4,7 @@ sidebar_position: 0 title: "Configuration Overview" --- -Based on different usage scenarios, BifroMQ divides configurations into system-level and tenant-level. System-level configurations are set at the system's startup and cannot be changed afterward. In contrast, tenant-level configurations can be dynamically adjusted during runtime as needed, and their initial values can also be customized at the system's startup. The capability for tenant-level settings requires the implementation of a custom [setting provider](../../plugin/setting_provide [...] +Based on different usage scenarios, BifroMQ divides configurations into system-level and tenant-level. System-level configurations are set at the system's startup and cannot be changed afterward. In contrast, tenant-level configurations can be dynamically adjusted during runtime as needed, and their initial values can also be customized at the system's startup. The capability for tenant-level settings requires the implementation of a custom [setting provider](../../plugin/setting_provide [...] System-level configurations are categorized based on criteria such as their common use, whether they are in an experimental phase, or whether they have not been finalized. They can be provided either through a [configuration file](config_file_manual.md) (located in the conf directory's standalone.yml) or via JVM system [properties](bifromq_sys_props.md) (in the format of -D`conf`=`value`). diff --git a/docs/admin_guide/observability/events.md b/docs/admin_guide/observability/events.md index f9c90a95..cb03453c 100644 --- a/docs/admin_guide/observability/events.md +++ b/docs/admin_guide/observability/events.md @@ -19,4 +19,4 @@ Although event objects form a crucial part of the Event Collector Plugin interfa ## Plugin Development Best Practices -For those interested in extending BifroMQ's capabilities through plugin development, including event collection, further guidance and best practices can be found in the relevant [sections](../../plugin/plugin_practice.md). +For those interested in extending BifroMQ's capabilities through plugin development, including event collection, further guidance and best practices can be found in the relevant [sections](../../plugin/plugin_practice.mdx). diff --git a/docs/admin_guide/observability/metrics/intro.md b/docs/admin_guide/observability/metrics/intro.md index f522c4bc..36f3398e 100644 --- a/docs/admin_guide/observability/metrics/intro.md +++ b/docs/admin_guide/observability/metrics/intro.md @@ -12,7 +12,7 @@ BifroMQ offers out-of-the-box support for Prometheus through its bundled [DemoPl ## Tenant-Level Metrics for Multi-Tenancy -BifroMQ introduces a set of tenant-level [metrics](tenantmetrics.md). These metrics enable the real-time collection and aggregation of data reflecting the resource usage and activity of individual tenants. When used in combination with the [Resource Throttler](../../../plugin/resource_throttler.md) plugin, tenant-level metrics facilitate effective load isolation strategies. +BifroMQ introduces a set of tenant-level [metrics](tenantmetrics.md). These metrics enable the real-time collection and aggregation of data reflecting the resource usage and activity of individual tenants. When used in combination with the [Resource Throttler](../../../plugin/resource_throttler) plugin, tenant-level metrics facilitate effective load isolation strategies. ## Advanced Diagnostics and Tuning diff --git a/docs/admin_guide/security/intro.md b/docs/admin_guide/security/intro.md index 2191ae2e..3d702d65 100644 --- a/docs/admin_guide/security/intro.md +++ b/docs/admin_guide/security/intro.md @@ -19,7 +19,7 @@ Node communication in BifroMQ occurs through two primary methods: P2P communicat ### Auth Provider Plugin -Client security in BifroMQ encompasses both authentication (verifying client identity) and authorization (granting privileges to various actions). BifroMQ employs the [auth provider plugin](../../plugin/auth_provider.md) as a unified approach to client security management. +Client security in BifroMQ encompasses both authentication (verifying client identity) and authorization (granting privileges to various actions). BifroMQ employs the [auth provider plugin](../../plugin/auth_provider) as a unified approach to client security management. ### Secure Communication Channels diff --git a/docs/get_started/faq.md b/docs/get_started/faq.md index b488793c..b105c1b4 100644 --- a/docs/get_started/faq.md +++ b/docs/get_started/faq.md @@ -37,10 +37,10 @@ BifroMQ is designed as a core middleware component to be embedded within broader - **[API](../user_guide/api/intro.md)**: Broker-side control logic, such as forcing disconnection. - **[Metrics](../admin_guide/observability/metrics/intro.md)**: Runtime metrics that can be consumed by existing monitoring systems. -- **[AuthProvider Plugin](../plugin/auth_provider.md)**: Enable customized authentication and authorizaiton -- **[ClientBalancer Plugin](../plugin/client_balancer.md)**: Implements an active clientâbalancing strategy, dynamically distributing incoming client connections across broker instances to ensure even load distribution. -- **[EventCollector Plugin](../plugin/event_collector.md)**: Emits operational events for custom Event Sourcing logic (e.g., connection counts, online/offline). -- **[ResourceThrottler Plugin](../plugin/resource_throttler.md)**: Controls tenant-level resource usage. -- **[SettingProvider Plugin](../plugin/setting_provider/intro.md)**: Adjusts tenant-level runtime settings. +- **[AuthProvider Plugin](../plugin/auth_provider)**: Enable customized authentication and authorizaiton +- **[ClientBalancer Plugin](../plugin/client_balancer)**: Implements an active clientâbalancing strategy, dynamically distributing incoming client connections across broker instances to ensure even load distribution. +- **[EventCollector Plugin](../plugin/event_collector)**: Emits operational events for custom Event Sourcing logic (e.g., connection counts, online/offline). +- **[ResourceThrottler Plugin](../plugin/resource_throttler)**: Controls tenant-level resource usage. +- **[SettingProvider Plugin](../plugin/setting_provider/intro)**: Adjusts tenant-level runtime settings. As with rule-engine support, we welcome community-driven side projects to build Web UIs, CLI tools, or other management interfaces leveraging these integration points. diff --git a/docs/get_started/quick_install.md b/docs/get_started/quick_install.mdx similarity index 86% rename from docs/get_started/quick_install.md rename to docs/get_started/quick_install.mdx index 9bcb8812..adb4adf2 100644 --- a/docs/get_started/quick_install.md +++ b/docs/get_started/quick_install.mdx @@ -3,13 +3,17 @@ sidebar_position: 1 title: "Quick Install & Verify" --- +import React from 'react'; +import CodeBlock from '@theme/CodeBlock'; +import { useDocsVersion } from '@docusaurus/plugin-content-docs/client'; + # Quick Install For a rapid setup, Docker is recommended: -```bash -docker run -d --name bifromq -p 1883:1883 apache/bifromq:4.0.0-incubating -``` +<CodeBlock language="bash"> + {`docker run -d --name bifromq -p 1883:1883 apache/bifromq:${useDocsVersion().label}`} +</CodeBlock> For further installation alternatives and comprehensive details, refer to [Installation](../installation/intro.md). diff --git a/docs/installation/docker.md b/docs/installation/docker.mdx similarity index 76% rename from docs/installation/docker.md rename to docs/installation/docker.mdx index 659b692d..6765cca7 100644 --- a/docs/installation/docker.md +++ b/docs/installation/docker.mdx @@ -3,6 +3,11 @@ sidebar_position: 1 title: "Docker" --- +import React from 'react'; +import CodeBlock from '@theme/CodeBlock'; +import { useDocsVersion } from '@docusaurus/plugin-content-docs/client'; + + ## Prerequisites * [Docker](https://www.docker.com/) is installed. @@ -12,10 +17,7 @@ title: "Docker" Run the following command, which will run Apache BifroMQ within a container as the Linux user `bifromq`. -``` -docker run -d --name bifromq -p 1883:1883 apache/bifromq:4.0.0-incubating -``` - +<CodeBlock language="bash">{`docker run -d --name bifromq -p 1883:1883 apache/bifromq:${useDocsVersion().label}`}</CodeBlock> ## Memory Constraints By default, upon Apache BifroMQ process initiation, it dynamically computes the relevant JVM parameters based on the physical memory of the hosting server. However, when launched within a containerized environment, it introspects the host @@ -24,17 +26,13 @@ machine's physical memory, potentially causing conflicts with Docker or containe To circumvent such challenges, it is advisable to proactively delimit the container's memory consumption and convey these limitations to the container runtime via environmental variables. During the startup of BifroMQ, priority is given to the calculation of JVM parameters based on the `MEM_LIMIT` environmental variable. A specific illustration is provided below: -``` -docker run -d -m 10G -e MEM_LIMIT='10737418240' --name bifromq -p 1883:1883 apache/bifromq:4.0.0-incubating -``` +<CodeBlock language="bash">{`docker run -d -m 10G -e MEM_LIMIT='10737418240'--name bifromq -p 1883:1883 apache/bifromq:${useDocsVersion().label}`}</CodeBlock> ***Note: The unit of MEM_LIMIT is in bytes.*** Going a step further, it is possible to proactively configure the JVM heap memory and directly transmit it to the container runtime for utilization by BifroMQ. A specific illustration is provided below: -``` -docker run -d -m 10G -e JVM_HEAP_OPTS='-Xms2G -Xmx4G -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=500m -XX:MaxDirectMemorySize=1G' --name bifromq -p 1883:1883 apache/bifromq:4.0.0-incubating -``` +<CodeBlock language="bash">{`docker run -d -m 10G -e JVM_HEAP_OPTS='-Xms2G -Xmx4G -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=500m -XX:MaxDirectMemorySize=1G' --name bifromq -p 1883:1883 apache/bifromq:${useDocsVersion().label}`}</CodeBlock> You can build an Apache BifroMQ cluster using Docker Compose on a single host for development and testing. Suppose you want to create a cluster with three nodes: node1, node2, and node3. The directory structure should be as follows: @@ -53,10 +51,9 @@ clusterConfig: seedEndpoints: "bifromq-node1:8899,bifromq-node2:8899,bifromq-node3:8899" ``` The `docker-compose.yml` file defines the services for the three nodes: -```yml -services: +<CodeBlock language="yaml">{`services: bifromq-node1: - image: apache/bifromq:4.0.0-incubating + image: apache/bifromq:${useDocsVersion().label} container_name: bifromq-node1 volumes: - ./node1/standalone.yml:/home/bifromq/conf/standalone.yml @@ -68,7 +65,7 @@ services: - bifromq-net bifromq-node2: - image: apache/bifromq:4.0.0-incubating + image: apache/bifromq:${useDocsVersion().label} container_name: bifromq-node2 volumes: - ./node2/standalone.yml:/home/bifromq/conf/standalone.yml @@ -80,7 +77,7 @@ services: - bifromq-net bifromq-node3: - image: apache/bifromq:4.0.0-incubating + image: apache/bifromq:${useDocsVersion().label} container_name: bifromq-node3 volumes: - ./node3/standalone.yml:/home/bifromq/conf/standalone.yml @@ -93,10 +90,8 @@ services: networks: bifromq-net: - driver: bridge -``` + driver: bridge`}</CodeBlock> To launch the cluster, run the following command: ```shell docker compose up -d ``` - diff --git a/docs/installation/install_from_source.md b/docs/installation/install_from_source.md deleted file mode 100644 index 29499f49..00000000 --- a/docs/installation/install_from_source.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_position: 4 -title: "Install from Source" ---- - -## Prerequisites - -- JDK 17+ -- Maven 3.5.0+ - -## Build - -Clone the repository to local workspace - -``` -cd <YOUR_WORKSPACE> -git clone https://github.com/apache/bifromq bifromq -``` - -Change directory to project root folder and execute following commands to build the whole project - -``` -cd bifromq -mvn wrapper:wrapper -./mvnw -U clean package -``` - -The build output are two tar.gz and one zip files under `/target/output` - -- bifromq-xxx-standalone.tar.gz // standalone deployment tar.gz for linux and mac os -- bifromq-xxx-windows-standalone.zip // standalone deployment zip for windows diff --git a/docs/installation/install_from_source.mdx b/docs/installation/install_from_source.mdx new file mode 100644 index 00000000..4a9632e9 --- /dev/null +++ b/docs/installation/install_from_source.mdx @@ -0,0 +1,30 @@ +--- +sidebar_position: 4 +title: "Install from Source" +--- + +import React from 'react'; +import CodeBlock from '@theme/CodeBlock'; +import { useDocsVersion } from '@docusaurus/plugin-content-docs/client'; + +## Prerequisites + +- JDK 17+ +- Maven 3.5.0+ + +## Build + +Clone the repository to local workspace + +<CodeBlock language="bash">{`cd <YOUR_WORKSPACE> +git clone --branch ${useDocsVersion()?.label?.trim()} https://github.com/apache/bifromq bifromq`}</CodeBlock> + +<CodeBlock language="bash">{`cd bifromq +./mvnw -v +./mvnw -U clean verify -DskipTests -Pbuild-release`}</CodeBlock> + +The build output consists of several archive files with sha512 checksum located under /target/output + +- {`apache-bifromq-${useDocsVersion()?.label?.trim()}-src.tar.gz`} +- {`apache-bifromq-${useDocsVersion()?.label?.trim()}.tar.gz`} +- {`apache-bifromq-${useDocsVersion()?.label?.trim()}-windows.zip`} diff --git a/docs/plugin/auth_provider.md b/docs/plugin/auth_provider.mdx similarity index 98% rename from docs/plugin/auth_provider.md rename to docs/plugin/auth_provider.mdx index c55ddec6..3e746675 100644 --- a/docs/plugin/auth_provider.md +++ b/docs/plugin/auth_provider.mdx @@ -3,16 +3,16 @@ sidebar_position: 1 title: "Auth Provider" --- -The Auth Provider plugin enhances BifroMQ by integrating authentication and authorization functionalities for MQTT clients and Pub/Sub operations. The plugin's interface is detailed in the following Maven module: +import CodeBlock from '@theme/CodeBlock'; +import {useDocsVersion} from '@docusaurus/plugin-content-docs/client'; -```xml +The Auth Provider plugin enhances BifroMQ by integrating authentication and authorization functionalities for MQTT clients and Pub/Sub operations. The plugin's interface is detailed in the following Maven module: -<dependency> +<CodeBlock language="xml">{`<dependency> <groupId>org.apache.bifromq</groupId> <artifactId>bifromq-plugin-auth-provider</artifactId> - <version>X.Y.Z</version> <!--replace X.Y.Z with the latest version number--> -</dependency> -``` + <version>${useDocsVersion().label}</version> +</dependency>`}</CodeBlock> BifroMQ operates with only one instance of the Auth Provider at any given time. The specific class to be loaded can be configured in [configuration file](../admin_guide/configuration/config_file_manual.md) by specifying its Fully Qualified Name (FQN): diff --git a/docs/plugin/client_balancer.md b/docs/plugin/client_balancer.mdx similarity index 92% rename from docs/plugin/client_balancer.md rename to docs/plugin/client_balancer.mdx index f52d6cc3..abd69f2c 100644 --- a/docs/plugin/client_balancer.md +++ b/docs/plugin/client_balancer.mdx @@ -3,17 +3,18 @@ sidebar_position: 2 title: "Client Balancer" --- +import CodeBlock from '@theme/CodeBlock'; +import {useDocsVersion} from '@docusaurus/plugin-content-docs/client'; + 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> +<CodeBlock language="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> -``` + <version>${useDocsVersion().label}</version> +</dependency>`}</CodeBlock> ## Configuration diff --git a/docs/plugin/event_collector.md b/docs/plugin/event_collector.mdx similarity index 92% rename from docs/plugin/event_collector.md rename to docs/plugin/event_collector.mdx index 0f2ac793..a8097064 100644 --- a/docs/plugin/event_collector.md +++ b/docs/plugin/event_collector.mdx @@ -3,16 +3,16 @@ sidebar_position: 3 title: "Event Collector" --- -The Event Collector plugin is designed to capture a variety of events that occur during the running of BifroMQ. The interface for this plugin is defined in the following Maven module: +import CodeBlock from '@theme/CodeBlock'; +import {useDocsVersion} from '@docusaurus/plugin-content-docs/client'; -```xml +The Event Collector plugin is designed to capture a variety of events that occur during the running of BifroMQ. The interface for this plugin is defined in the following Maven module: -<dependency> +<CodeBlock language="xml">{`<dependency> <groupId>org.apache.bifromq</groupId> <artifactId>bifromq-plugin-event-collector</artifactId> - <version>X.Y.Z</version> <!--replace X.Y.Z with the latest version number--> -</dependency> -``` + <version>${useDocsVersion().label}</version> +</dependency>`}</CodeBlock> Upon startup, BifroMQ scans the plugins directory and loads all available EventCollector implementations. It is recommended that each EventCollector focuses only on a simple specific task by utilizing the EventType feature to filter out events that are not relevant to their intended purpose. diff --git a/docs/plugin/intro.md b/docs/plugin/intro.md index e601eccd..77d50e53 100644 --- a/docs/plugin/intro.md +++ b/docs/plugin/intro.md @@ -6,11 +6,11 @@ title: "Plugin Overview" The plugin mechanism is a primary way for BifroMQ to deeply integrate with business systems. Currently, BifroMQ exposes five types of plugin extension interfaces to cater to different usage scenarios: -- **[Auth Provider](auth_provider.md)**: Integrates authentication and topic Pub/Sub authorization logic. -- **[Client Balancer](client_balancer.md)**: Inject your customized client balancing strategy in cooporative way. -- **[Event Collector](event_collector.md)**: Collects runtime events to implement various event-driven business logic. -- **[Resource Throttler](resource_throttler.md)**: Dynamically controls resource usage at the tenant level. -- **[Setting Provider](setting_provider/intro.md)**: Dynamically adjusts tenant-specific MQTT protocol settings. +- **[Auth Provider](auth_provider)**: Integrates authentication and topic Pub/Sub authorization logic. +- **[Client Balancer](client_balancer)**: Inject your customized client balancing strategy in cooporative way. +- **[Event Collector](event_collector)**: Collects runtime events to implement various event-driven business logic. +- **[Resource Throttler](resource_throttler)**: Dynamically controls resource usage at the tenant level. +- **[Setting Provider](setting_provider/intro)**: Dynamically adjusts tenant-specific MQTT protocol settings. ## Plugin Development diff --git a/docs/plugin/plugin_practice.md b/docs/plugin/plugin_practice.mdx similarity index 82% rename from docs/plugin/plugin_practice.md rename to docs/plugin/plugin_practice.mdx index c9114adf..a1b699c2 100644 --- a/docs/plugin/plugin_practice.md +++ b/docs/plugin/plugin_practice.mdx @@ -3,33 +3,32 @@ sidebar_position: 6 title: "Plugin Practice and Notice" --- +import CodeBlock from '@theme/CodeBlock'; +import { useDocsVersion } from '@docusaurus/plugin-content-docs/client'; + + This article outlines some practices and considerations when developing BifroMQ plugins. ## Start a BifroMQ Plugin Project Quickly -To jump start your BifroMQ plugin development, execute the following Maven command: +To jump start your BifroMQ plugin development, execute the following Maven command (the version placeholders automatically use the current docs version): -``` -mvn archetype:generate \ - -DarchetypeGroupId=org.apache.bifromq \ - -DarchetypeArtifactId=bifromq-plugin-archetype \ - -DarchetypeVersion=<BIFROMQ_VERSION> \ - -DgroupId=<YOUR_GROUP_ID> \ - -DartifactId=<YOUR_ARTIFACT_ID> \ - -Dversion=<YOUR_PROJECT_VERSION> \ - -DpluginName=<YOUR_PLUGIN_CLASS_NAME> \ - -DpluginContextName=<YOUR_PLUGIN_CONTEXT_CLASS_NAME> \ - -DbifromqVersion=<BIFROMQ_VERSION> \ - -DinteractiveMode=false -``` +<CodeBlock language="bash">{`mvn archetype:generate \\ + -DarchetypeGroupId=org.apache.bifromq \\ + -DarchetypeArtifactId=bifromq-plugin-archetype \\ + -DarchetypeVersion=${useDocsVersion()?.label} \\ + -DgroupId=<YOUR_GROUP_ID> \\ + -DartifactId=<YOUR_ARTIFACT_ID> \\ + -Dversion=<YOUR_PROJECT_VERSION> \\ + -DpluginName=<YOUR_PLUGIN_CLASS_NAME> \\ + -DpluginContextName=<YOUR_PLUGIN_CONTEXT_CLASS_NAME> \\ + -DbifromqVersion=${useDocsVersion()?.label} \\ + -DinteractiveMode=false`}</CodeBlock> Replace `<YOUR_GROUP_ID>`, `<YOUR_ARTIFACT_ID>`, `<YOUR_PROJECT_VERSION>`, `<YOUR_PLUGIN_CLASS_NAME>`, and `< YOUR_PLUGIN_CONTEXT_CLASS_NAME>` with your specific details. This command generates a ready-to-build multi-module project structured for BifroMQ plugin development. -**Important Note**: The archetype version should be 3.2.0 or higher as the archetype is compatible starting from version -3.2.0. Ensure that `<BIFROMQ_VERSION>` is set accordingly. - In addition to the foundational code framework for plugin development, the generated BifroMQ plugin project also includes the following features: - PluginContext: Defines the plugin context to facilitate the transfer of necessary runtime information. diff --git a/docs/plugin/resource_throttler.md b/docs/plugin/resource_throttler.mdx similarity index 97% rename from docs/plugin/resource_throttler.md rename to docs/plugin/resource_throttler.mdx index ffef0fa9..2a7b5c1f 100644 --- a/docs/plugin/resource_throttler.md +++ b/docs/plugin/resource_throttler.mdx @@ -3,6 +3,9 @@ sidebar_position: 4 title: "Resource Throttler" --- +import CodeBlock from '@theme/CodeBlock'; +import {useDocsVersion} from '@docusaurus/plugin-content-docs/client'; + In BifroMQ's multi-tenant architecture, tenants share resources provided by a single cluster instance. To prevent any single tenant from overusing resources and impacting others, it is crucial to control each tenant's resource usage globally at runtime. It is important to note that the ability to achieve load isolation among tenants through resource limitations presupposes the availability of surplus resources in the cluster during peak business periods. @@ -11,14 +14,11 @@ terms of quantity and rate, including Gauge, Counter, and Summary metrics. The interface for the plugin is defined in the following Maven module: -```xml - -<dependency> +<CodeBlock language="xml">{`<dependency> <groupId>org.apache.bifromq</groupId> <artifactId>bifromq-plugin-resource-throttler</artifactId> - <version>X.Y.Z</version> <!--replace X.Y.Z with the latest version number--> -</dependency> -``` + <version>${useDocsVersion().label}</version> +</dependency>`}</CodeBlock> BifroMQ allows only one instance of the Resource Throttler to run at a time. The specific implementation class to be loaded must be specified in the [configuration file](../admin_guide/configuration/config_file_manual.md) by its Fully Qualified Name (FQN): @@ -34,7 +34,7 @@ public boolean hasResource(String tenantId, TenantResourceType type); ``` This method is called synchronously on BifroMQ's worker thread and must be implemented efficiently to avoid impacting BifroMQ performance. A return value of false triggers a limiting action, and a ResourceThrottling event is generated and -reported to the [Event Collector](event_collector.md). +reported to the [Event Collector](event_collector). Here are the resource types defined in `TenantResourceType`: diff --git a/docs/plugin/setting_provider/intro.md b/docs/plugin/setting_provider/intro.mdx similarity index 96% rename from docs/plugin/setting_provider/intro.md rename to docs/plugin/setting_provider/intro.mdx index 7fe54dfe..1c26fd74 100644 --- a/docs/plugin/setting_provider/intro.md +++ b/docs/plugin/setting_provider/intro.mdx @@ -4,19 +4,19 @@ sidebar_position: 0 title: "Setting Provider" --- +import CodeBlock from '@theme/CodeBlock'; +import {useDocsVersion} from '@docusaurus/plugin-content-docs/client'; + BifroMQ defines a category of [Tenant-level Settings](1_tenantsetting.md) that can be modified at runtime, allowing for dynamic adjustment of BifroMQ's service behavior per tenant. The purpose of the Setting Provider Plugin is to supply custom values for these settings at runtime. The Plugin's interface is defined in the following Maven module: -```xml - -<dependency> +<CodeBlock language="xml">{`<dependency> <groupId>org.apache.bifromq</groupId> <artifactId>bifromq-plugin-setting-provider</artifactId> - <version>X.Y.Z</version> <!--replace X.Y.Z with latest version number--> -</dependency> -``` + <version>${useDocsVersion().label}</version> +</dependency>`}</CodeBlock> BifroMQ allows only a single instance of the Setting Provider to run at a time. You can configure the specific implementation class to be loaded through a configuration file by specifying its fully qualified name (FQN) using the following key: diff --git a/docs/user_guide/basic/connect.md b/docs/user_guide/basic/connect.md index 7450f5f9..632607ba 100644 --- a/docs/user_guide/basic/connect.md +++ b/docs/user_guide/basic/connect.md @@ -20,4 +20,4 @@ Use the IP address or domain name corresponding to the launched service. Below a By default, without an AuthProvider plugin, BifroMQ does not enforce authentication or authorization. However, you can assign a connection to a specific tenant by specifying the username in the format `<TenantId>/<UserName>`. If you omit the tenant prefix, the connection will be assigned to the default `"DevOnly"` tenant. -For full authentication and authorization support, please refer to the [AuthProvider Plugin](../../plugin/auth_provider.md). +For full authentication and authorization support, please refer to the [AuthProvider Plugin](../../plugin/auth_provider). diff --git a/docs/user_guide/basic/intro.md b/docs/user_guide/basic/intro.md index 9b7824d2..276437f6 100644 --- a/docs/user_guide/basic/intro.md +++ b/docs/user_guide/basic/intro.md @@ -8,9 +8,9 @@ BifroMQ provides extensive MQTT protocol support for IoT applications and servic 1. **Comprehensive Protocol Support**: BifroMQ supports MQTT versions 3.1, 3.1.1, and 5.0, compatible with all third-party clients that utilize these protocol versions. This ensures users can seamlessly integrate BifroMQ into their existing systems, offering a smooth experience for developers and administrators. -2. **Tenant-Specific Configurations**: BifroMQ allows for protocol-related [settings](../../plugin/setting_provider/1_tenantsetting.md) to be customized for each tenant, catering to the specific needs and application scenarios of each tenant. +2. **Tenant-Specific Configurations**: BifroMQ allows for protocol-related [settings](../../plugin/setting_provider/1_tenantsetting) to be customized for each tenant, catering to the specific needs and application scenarios of each tenant. -3. **Dynamic Adjustment via Plugins**: BifroMQ supports dynamic adjustments of protocol settings through the use of [setting provider plugins](../../plugin/setting_provider/intro.md), offering flexibility and adaptability in rapidly changing business operations. +3. **Dynamic Adjustment via Plugins**: BifroMQ supports dynamic adjustments of protocol settings through the use of [setting provider plugins](../../plugin/setting_provider/intro), offering flexibility and adaptability in rapidly changing business operations. 4. **Interoperability Between Protocol Versions**: BifroMQ supports message exchange between sessions established with different MQTT protocol versions within the same tenant, ensuring seamless communication between devices and clients on different protocol versions. diff --git a/docs/user_guide/intro.md b/docs/user_guide/intro.md index b3d97fe9..9346e2e3 100644 --- a/docs/user_guide/intro.md +++ b/docs/user_guide/intro.md @@ -17,10 +17,10 @@ functionalities into a wide range of business systems, particularly those geared tenant namespace. MQTT connections within the same tenant namespace can publish and subscribe to messages amongst each other, while connections across different tenant namespaces remain isolated, enhancing security and data privacy. 3. **Tenant Lifecycle Management by Integrators**: Unlike some systems that manage tenant lifecycles internally, BifroMQ delegates the definition and management of tenants to the integrating business. This is achieved by implementing - an [Auth Provider Plugin](../plugin/auth_provider.md), where the business specifies the **_tenantId_** for each connection during the authentication process. This model supports a wide range of business scenarios, + an [Auth Provider Plugin](../plugin/auth_provider), where the business specifies the **_tenantId_** for each connection during the authentication process. This model supports a wide range of business scenarios, including the use of a single, "global" tenant namespace for businesses not requiring multi-tenancy features. 4. **Resource and Load Isolation per Tenant**: Beyond logical isolation of MQTT sessions and message publication/subscription, BifroMQ uses tenant spaces as boundaries for resource and load isolation. This capability is facilitated - by [Tenant Metrics](../admin_guide/observability/metrics/tenantmetrics.md) and the [Resource Throttler Plugin](../plugin/resource_throttler.md), ensuring efficient resource utilization and system stability. + by [Tenant Metrics](../admin_guide/observability/metrics/tenantmetrics.md) and the [Resource Throttler Plugin](../plugin/resource_throttler), ensuring efficient resource utilization and system stability. 5. **Optimized Tenant Capability with Minimal Resource Overhead**: BifroMQ is specifically designed for multi-tenancy, yet the multi-tenant capability incurs a certain level of resource overhead. However, this overhead does not need to be a concern in the vast majority of multi-tenant business scenarios. It is important to note, though, that scaling the BifroMQ cluster horizontally cannot achieve an infinite increase in the number of tenants served simultaneously within the cluster. Ther [...]
