diff --git a/docs/dispatchers.rst b/docs/dispatchers.rst index 08afcf15a..4f0c37e13 100644 --- a/docs/dispatchers.rst +++ b/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 `, request routing, load balancing, broadcasting, and loop prevention. -TBD \ No newline at end of file +Processing Logic +---------------- + +.. _dispatcher-authorization: + +Authorization +~~~~~~~~~~~~~ + +Optional step when :ref:`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 `: + +enabled + Enables/disables the DispatcherS component. Values: + +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: checks all levels + - false: checks only first level + +attributes_conns + Connections to :ref:`AttributeS ` for API authorization + - Empty: disables authorization + - "*internal": uses internal connection + - Custom connection ID + +any_subsystem + Enables matching of *any subsystem. Values: + +prevent_loops + Prevents request loops between dispatcher nodes. Values: + +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