Add DispatcherS component documentation

docs/dispatchers.rst

@@ -1,5 +1,207 @@
+.. _dispatchers:
+
 DispatcherS
 ===========
 
+**DispatcherS** is the **CGRateS** component that handles request routing and load balancing. When enabled, it manages all requests to other CGRateS subsystems by wrapping their methods with additional features like :ref:`authorization <dispatcher-authorization>`, request routing, load balancing, broadcasting, and loop prevention.
 
-TBD
+Processing Logic
+----------------
+
+.. _dispatcher-authorization:
+
+Authorization
+~~~~~~~~~~~~~
+
+Optional step when :ref:`AttributeS <attributes>` connections are configured:
+
+- Looks for ```*apiKey``` in APIOpts (returns mandatory missing error if not present)
+- Sends key to AttributeS, which adds it as "APIKey" to the Event
+- AttributeS processes the event and adds allowed methods to APIMethods (e.g., "method1&method2&method3")
+- Checks if the requested method is in the allowed list
+- Continues only after successful authorization
+
+Dispatch
+~~~~~~~~
+
+The dispatcher processes requests through these steps:
+
+* Check for bypass conditions:
+   * Presence of ```*dispatchers: false``` in APIOpts
+   * Request source is another dispatcher and ```prevent_loops``` is enabled
+
+* Check cached routes:
+   * Search for ```*routeID``` in APIOpts
+   * If found, use cached dispatch data (tenant, profile ID, host ID)
+   * Fall back to full dispatch on network errors or timeouts
+
+* Run full dispatch sequence:
+   * Get matching dispatcher profiles
+   * Try each profile until dispatch succeeds
+
+.. _dispatcher-types:
+
+Dispatcher Types and Strategies
+-------------------------------
+
+Load Dispatchers
+~~~~~~~~~~~~~~~~
+
+Used for ratio-based request distribution. Hosts are sorted in three steps:
+
+1. Initial sorting by weight
+2. Secondary sorting by load ratio (current active requests/configured ratio), where lower ratios have priority
+3. Final sorting based on the specified strategy:
+
+   * *random: Randomizes host selection 
+   * *round_robin: Sequential host selection with weight consideration
+   * *weight: Skips final sorting, maintains weight and load-based ordering
+
+Configuration through:
+
+- ```*defaultRatio``` in StrategyParams
+- Direct ratio specification in Host configuration
+
+
+Simple Dispatchers
+~~~~~~~~~~~~~~~~~~
+
+Standard request distribution where hosts are sorted first by weight, followed by the chosen strategy (*random, *round_robin, *weight).
+
+Broadcast Dispatchers
+~~~~~~~~~~~~~~~~~~~~~
+
+Handles scenarios requiring multi-host distribution. Supports three broadcast strategies:
+
+* *broadcast: Sends to all hosts, uses first response
+* *broadcast_sync: Sends to all hosts, waits for all responses
+* *broadcast_async: Sends to all hosts without waiting (fire-and-forget)
+
+Parameters
+----------
+
+Configure the dispatcher in the **dispatchers** section of the :ref:`JSON configuration <configuration>`:
+
+enabled
+    Enables/disables the DispatcherS component. Values: <true|false>
+
+indexed_selects
+    Enables profile matching exclusively on indexes for improved performance
+
+string_indexed_fields
+    Fields used for string-based index querying
+
+prefix_indexed_fields
+    Fields used for prefix-based index querying
+
+suffix_indexed_fields
+    Fields used for suffix-based index querying
+
+nested_fields
+    Controls indexed filter matching depth. Values: <true|false>
+    - true: checks all levels
+    - false: checks only first level
+
+attributes_conns
+    Connections to :ref:`AttributeS <attributes>` for API authorization
+    - Empty: disables authorization
+    - "*internal": uses internal connection
+    - Custom connection ID
+
+any_subsystem
+    Enables matching of *any subsystem. Values: <true|false>
+
+prevent_loops
+    Prevents request loops between dispatcher nodes. Values: <true|false>
+
+DispatcherHost
+~~~~~~~~~~~~~~
+
+Defines individual dispatch destinations with the following parameters:
+
+Tenant
+    The tenant on the platform
+
+ID
+    Unique identifier for the host
+
+Address
+    Host address (use *internal for internal connections)
+
+Transport
+    Protocol used for communication (*gob, *json)
+
+ConnectAttempts
+    Number of connection attempts
+
+Reconnects
+    Maximum number of reconnection attempts
+
+MaxReconnectInterval
+    Maximum interval between reconnection attempts
+
+ConnectTimeout
+    Connection timeout (e.g., "1m")
+
+ReplyTimeout
+    Response timeout (e.g., "2m")
+
+TLS
+    TLS connection settings:
+    - ClientKey: Path to client key file
+    - ClientCertificate: Path to client certificate
+    - CaCertificate: Path to CA certificate
+
+DispatcherProfile
+~~~~~~~~~~~~~~~~~
+
+Defines routing rules and strategies. See :ref:`dispatcher-types` for available strategies.
+
+Tenant
+    The tenant on the platform
+
+ID
+    Profile identifier
+
+Subsystems
+    Target subsystems (*any for all)
+
+FilterIDs
+    List of filters for request matching
+
+ActivationInterval
+    Time interval when profile is active
+
+Strategy
+    Dispatch strategy (*weight, *random, *round_robin, *broadcast, *broadcast_sync)
+
+StrategyParameters
+    Additional strategy configuration (e.g., *default_ratio)
+
+ConnID
+    Target host identifier
+
+ConnFilterIDs
+    Filters for connection selection
+
+ConnWeight
+    Priority weight for connection selection within the profile
+
+ConnBlocker
+    Blocks connection if true
+
+ConnParameters
+    Additional connection parameters (e.g., *ratio)
+
+Weight
+    Priority weight used when selecting between multiple matching profiles
+
+Use Cases
+---------
+
+- Load balancing between multiple CGRateS nodes
+- High availability setups with automatic failover
+- Request authorization and access control
+- Broadcasting requests for data collection
+- Traffic distribution based on weight or custom metrics
+- System scaling and performance optimization