Struct BrokerLimits 

pub struct BrokerLimits {
    pub buckets: HashMap<BucketId, BucketCfg>,
    pub route: HashMap<MethodId, Vec<BucketId>>,
    pub conns: ConnQuota,
}

The full limit policy of one broker user: token buckets, routes and connection quotas.

Normally read from the [broker] section of a limits file by from_toml_str or from_toml_section, then handed to BrokerLimiter::new.

Limits belong to the broker user (the token or account), not to a connector. Build one BrokerLimiter per user and share it between all connectors of that user. Two limiters for one broker limit would each allow the full rate, so together they would exceed the quota the broker gave.

Examples

use brokapi_runtime::BrokerLimits;

let raw = r#"
[demo.buckets.orders]
rate = 10
per = "1s"
burst = 3

[demo.route]
PlaceOrder = ["orders"]

[demo.conns]
max_conns = 2
max_subs_per_conn = 50
supports_multiplex = false
"#;
let limits = BrokerLimits::from_toml_str(raw)?;
assert_eq!(limits.buckets["orders"].burst, 3);
assert_eq!(limits.buckets_for("PlaceOrder"), vec!["orders".to_string()]);

Fields

buckets: HashMap<BucketId, BucketCfg>

The token buckets by name.

route: HashMap<MethodId, Vec<BucketId>>

For each method name, the buckets one call spends from (one token from each). A bucket named here that is missing from buckets is a configuration error found at BrokerLimiter::acquire.

conns: ConnQuota

Connection and subscription quotas.

Implementations

impl BrokerLimits

pub fn from_toml_str(raw: &str) -> Result<Self, ConfigError>

Reads a limits file that holds exactly one broker section.

The file layout is one top-level table per broker, with buckets, route and conns below it: [bcs.buckets.global], [bcs.route], [bcs.conns]. A per value is an integer followed by ms, s, m, h or d ("250ms", "1s", "24h"). Zero, fractions ("1.5s"), other units ("1w") and spaces inside ("1 s") are refused. buckets and route must be present. Keys the parser does not know are ignored (an older file with dedicated_command_conns still reads), so a misspelled optional key is silently lost.

Use from_toml_section for a file that holds several brokers.

Errors

Returns [brokapi_core::ConfigError::Message] when the text is not valid TOML, when a required key is missing or has the wrong type, when per cannot be parsed, or when the file has zero or several broker sections.

Examples

use brokapi_runtime::BrokerLimits;

let raw = r#"
[demo.buckets.global]
rate = 100
per = "1s"
burst = 20
[demo.route]
"*" = ["global"]
[demo.conns]
max_conns = 4
max_subs_per_conn = 50
supports_multiplex = false
"#;
let limits = BrokerLimits::from_toml_str(raw)?;
assert_eq!(limits.conns.max_conns, 4);

// An unsupported duration unit is a configuration error, not a silent default.
let bad = raw.replace("\"1s\"", "\"1w\"");
assert!(BrokerLimits::from_toml_str(&bad).is_err());

// Two broker sections: pick one with `from_toml_section`.
let two = format!("{raw}\n{}", raw.replace("demo", "other"));
assert!(BrokerLimits::from_toml_str(&two).is_err());
assert!(BrokerLimits::from_toml_section(&two, "other").is_ok());

pub fn from_toml_section(raw: &str, section: &str) -> Result<Self, ConfigError>

Reads one named broker section (for example "tbank") of a limits file.

Other sections are parsed too, so they must be valid, but they are not returned. The format is the same as in from_toml_str.

Errors

Returns [brokapi_core::ConfigError::Message] for invalid TOML or an invalid section, and when the file has no [section].

Examples

use brokapi_runtime::BrokerLimits;

let raw = r#"
[a.buckets.g]
rate = 1
per = "1s"
burst = 1
[a.route]
"*" = ["g"]
[a.conns]
max_conns = 1
max_subs_per_conn = 1
supports_multiplex = false
"#;
assert!(BrokerLimits::from_toml_section(raw, "a").is_ok());
assert!(BrokerLimits::from_toml_section(raw, "b").is_err());

pub fn from_toml_path(path: &str) -> Result<Self, ConfigError>

Reads a limits file from disk. The file must hold exactly one broker section.

Same as from_toml_str after reading the file.

Errors

Returns [brokapi_core::ConfigError::Message] when the file cannot be read (the message names the path), and for every reason from_toml_str lists.

Examples

use brokapi_runtime::BrokerLimits;

let err = BrokerLimits::from_toml_path("/definitely/not/here.toml").unwrap_err();
assert!(err.to_string().contains("/definitely/not/here.toml"));

pub fn buckets_for(&self, method: &str) -> Vec<BucketId>

The buckets a call to method spends from: its own route, else the DEFAULT_ROUTE route, else none.

The ids come back sorted and without repeats. This is the order in which BrokerLimiter::acquire takes the tokens. The ids are not checked against buckets.

Examples

use std::collections::HashMap;
use brokapi_runtime::{BrokerLimits, ConnQuota, DEFAULT_ROUTE};

let limits = BrokerLimits {
    buckets: HashMap::new(),
    route: HashMap::from([
        ("PlaceOrder".to_string(), vec!["orders".to_string(), "global".to_string()]),
        (DEFAULT_ROUTE.to_string(), vec!["global".to_string()]),
    ]),
    conns: ConnQuota::default(),
};
assert_eq!(limits.buckets_for("PlaceOrder"), ["global", "orders"]);
assert_eq!(limits.buckets_for("SomethingNew"), ["global"]);

Trait Implementations

impl Clone for BrokerLimits

fn clone(&self) -> BrokerLimits

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BrokerLimits

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for BrokerLimits

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for BrokerLimits

fn eq(&self, other: &BrokerLimits) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for BrokerLimits