fix(sessds): Improve schema and documentation related to DS

apps/emqx/src/emqx_ds_schema.erl

@@ -28,7 +28,6 @@
 -export([fields/1, desc/1, namespace/0]).
 
 -include("emqx_schema.hrl").
--include_lib("typerefl/include/types.hrl").
 -include_lib("hocon/include/hoconsc.hrl").
 -include_lib("hocon/include/hocon_types.hrl").
 
@@ -220,11 +219,21 @@ fields(builtin_write_buffer) ->
     [
         {max_items,
             sc(
-                pos_integer(),
+                emqx_ds_buffer:size_limit(),
                 #{
                     default => 1000,
                     mapping => "emqx_durable_storage.egress_batch_size",
-                    importance => ?IMPORTANCE_HIDDEN,
+                    importance => ?IMPORTANCE_MEDIUM,
+                    desc => ?DESC(builtin_write_buffer_max_items)
+                }
+            )},
+        {max_bytes,
+            sc(
+                emqx_ds_buffer:size_limit(),
+                #{
+                    default => infinity,
+                    mapping => "emqx_durable_storage.egress_batch_bytes",
+                    importance => ?IMPORTANCE_MEDIUM,
                     desc => ?DESC(builtin_write_buffer_max_items)
                 }
             )},

apps/emqx/src/emqx_schema.erl

@@ -310,7 +310,7 @@ roots(low) ->
             sc(
                 ref("durable_sessions"),
                 #{
-                    importance => ?IMPORTANCE_HIDDEN
+                    importance => ?IMPORTANCE_MEDIUM
                 }
             )},
         {trace,
@@ -2144,7 +2144,7 @@ desc("ocsp") ->
 desc("crl_cache") ->
     "Global CRL cache options.";
 desc("durable_sessions") ->
-    "Settings governing durable sessions persistence.";
+    ?DESC(durable_sessions);
 desc(durable_storage) ->
     ?DESC(durable_storage);
 desc("client_attrs_init") ->

apps/emqx_durable_storage/src/emqx_ds_buffer.erl

@@ -35,11 +35,15 @@
 
 -include_lib("emqx_utils/include/emqx_message.hrl").
 -include_lib("snabbkaffe/include/trace.hrl").
+-include_lib("typerefl/include/types.hrl").
 
 %%================================================================================
 %% Type declarations
 %%================================================================================
 
+-type size_limit() :: pos_integer() | infinity.
+-reflect_type([size_limit/0]).
+
 -define(name(DB, SHARD), {n, l, {?MODULE, DB, SHARD}}).
 -define(via(DB, SHARD), {via, gproc, ?name(DB, SHARD)}).
 -define(flush, flush).
@@ -61,8 +65,10 @@
 -callback shard_of_operation(emqx_ds:db(), emqx_ds:operation(), topic | clientid, _Options) ->
     _Shard.
 
--callback buffer_config(emqx_ds:db(), _Shard, _State, batch_size | batch_bytes | flush_interval) ->
-    {ok, non_neg_integer() | infinity} | undefined.
+-callback buffer_config
+    (emqx_ds:db(), _Shard, _State, batch_size | batch_bytes) ->
+        {ok, size_limit()} | undefined;
+    (emqx_ds:db(), _Shard, _State, flush_interval) -> pos_integer().
 
 -optional_callbacks([buffer_config/4]).
 

rel/i18n/emqx_schema.hocon

@@ -1614,17 +1614,39 @@ resource_tags.label:
 resource_tags.desc:
 """Tags to annotate this config entry."""
 
+durable_sessions.label:
+"""Durable sessoins"""
+durable_sessions.desc:
+"""Settings related to the durable session feature."""
+
 durable_sessions_enable.label:
 """Enable session persistence"""
-
 durable_sessions_enable.desc:
 """Use durable storage for client sessions persistence.
 If enabled, sessions configured to outlive client connections, along with their corresponding messages, will be durably stored and survive broker downtime.
 
 :::warning
-This feature is currently experimental. Please don't enable it in the production environments that contain valuable data.
+Messages sent to the durable sessions are saved on disc.
+This inevitably limits the overall throughput of the system.
 :::"""
 
+session_ds_heartbeat_interval.label:
+"""Durable session heartbeat interval"""
+session_ds_heartbeat_interval.desc:
+"""Durable sessions back up their state on disc every heartbeat interval.
+
+Heartbeat interval is also taken into account during garbage collection of expired sessions.
+It is added to the session expiry time as a safety margin when precise time of session termination is not precisely known."""
+
+session_ds_idle_poll_interval.label:
+"""Durable session idle poll interval"""
+session_ds_idle_poll_interval.desc:
+"""Expiry interval for poll requests sent by durable sessions to the storage."""
+
+session_ds_message_retention_period.label:
+"""Message retenetion period"""
+session_ds_message_retention_period.desc:
+"""Broker keeps messages sent to the durable sessions for this period of time."""
 
 session_ds_session_gc_interval.label:
 """Session garbage collection interval"""