Skip to main content

relay_config/
redis.rs

1use relay_redis::RedisConfigOptions;
2use serde::{Deserialize, Serialize};
3
4/// For small setups, `2 x limits.max_thread_count` does not leave enough headroom.
5/// In this case, we fall back to the old default.
6pub(crate) const DEFAULT_MIN_MAX_CONNECTIONS: u32 = 24;
7
8/// Additional configuration options for a redis client.
9#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
10#[serde(default)]
11pub struct PartialRedisConfigOptions {
12    /// Maximum number of connections managed by the pool.
13    ///
14    /// Defaults to 2x `limits.max_thread_count` or a minimum of 24.
15    #[serde(skip_serializing_if = "Option::is_none")]
16    pub max_connections: Option<u32>,
17    /// Sets the idle timeout used by the pool, in seconds.
18    ///
19    /// The idle timeout defines the maximum time a connection will be kept in the pool if unused.
20    pub idle_timeout: u64,
21    /// Sets the maximum time in seconds to wait when establishing a new Redis connection.
22    ///
23    /// If a connection cannot be established within this duration, it is considered a failure.
24    /// Applies when the pool needs to grow or create fresh connections.
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub create_timeout: Option<u64>,
27    /// Sets the maximum time in seconds to validate an existing connection when it is recycled.
28    ///
29    /// Recycling involves checking whether an idle connection is still alive before reuse.
30    /// If validation exceeds this timeout, the connection is discarded and a new fetch from the pool
31    /// is attempted.
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub recycle_timeout: Option<u64>,
34    /// Sets the maximum time, in seconds, that a caller is allowed to wait
35    /// when requesting a connection from the pool.
36    ///
37    /// If a connection does not become available within this period, the attempt
38    /// will fail with a timeout error. This setting helps prevent indefinite
39    /// blocking when the pool is exhausted.
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub wait_timeout: Option<u64>,
42    /// Sets the maximum time in seconds to wait for a result when sending a Redis command.
43    ///
44    /// If a command exceeds this timeout, the connection will be recycled.
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub response_timeout: Option<u64>,
47}
48
49impl Default for PartialRedisConfigOptions {
50    fn default() -> Self {
51        Self {
52            max_connections: None,
53            idle_timeout: 60,
54            create_timeout: Some(3),
55            recycle_timeout: Some(2),
56            wait_timeout: None,
57            response_timeout: Some(30),
58        }
59    }
60}
61
62/// Configuration for connecting a redis client.
63#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
64#[serde(untagged)]
65enum RedisConfigFromFile {
66    /// Connect to a Redis cluster.
67    Cluster {
68        /// List of `redis://` urls to use in cluster mode.
69        ///
70        /// This can also be a single node which is configured in cluster mode.
71        cluster_nodes: Vec<String>,
72
73        /// Additional configuration options for the redis client and a connections pool.
74        #[serde(flatten)]
75        options: PartialRedisConfigOptions,
76    },
77
78    /// Connect to a single Redis instance.
79    ///
80    /// Contains the `redis://` url to the node.
81    Single(String),
82
83    /// Connect to a single Redis instance.
84    ///
85    /// Allows to provide more configuration options, e.g. `max_connections`.
86    SingleWithOpts {
87        /// Contains the `redis://` url to the node.
88        server: String,
89
90        /// Additional configuration options for the redis client and a connections pool.
91        #[serde(flatten)]
92        options: PartialRedisConfigOptions,
93    },
94}
95
96/// Redis configuration.
97#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
98#[serde(untagged)]
99pub enum RedisConfig {
100    /// Connect to a Redis Cluster.
101    Cluster {
102        /// Redis nodes urls of the cluster.
103        cluster_nodes: Vec<String>,
104        /// Options of the Redis config.
105        #[serde(flatten)]
106        options: PartialRedisConfigOptions,
107    },
108    /// Write to multiple Redis instances, results are returned from the first.
109    MultiWrite {
110        /// Configurations for the Redis instances.
111        configs: Vec<RedisConfig>,
112    },
113    /// Connect to a single Redis instance.
114    Single(SingleRedisConfig),
115}
116
117/// Struct that can serialize a string to a single Redis connection.
118///
119/// This struct is needed for backward compatibility.
120#[derive(Clone, Debug, Serialize, Deserialize, Eq, PartialEq)]
121#[serde(untagged)]
122pub enum SingleRedisConfig {
123    #[doc(hidden)]
124    Simple(String),
125    #[doc(hidden)]
126    Detailed {
127        #[doc(hidden)]
128        server: String,
129        #[doc(hidden)]
130        #[serde(flatten)]
131        options: PartialRedisConfigOptions,
132    },
133}
134
135impl RedisConfig {
136    /// Creates a new Redis config for a single Redis instance with default settings.
137    pub fn single(server: String) -> Self {
138        RedisConfig::Single(SingleRedisConfig::Detailed {
139            server,
140            options: Default::default(),
141        })
142    }
143}
144
145impl From<RedisConfigFromFile> for RedisConfig {
146    fn from(value: RedisConfigFromFile) -> Self {
147        match value {
148            RedisConfigFromFile::Cluster {
149                cluster_nodes,
150                options,
151            } => Self::Cluster {
152                cluster_nodes,
153                options,
154            },
155            RedisConfigFromFile::Single(server) => Self::Single(SingleRedisConfig::Detailed {
156                server,
157                options: Default::default(),
158            }),
159            RedisConfigFromFile::SingleWithOpts { server, options } => {
160                Self::Single(SingleRedisConfig::Detailed { server, options })
161            }
162        }
163    }
164}
165
166/// Configurations for the various Redis pools used by Relay.
167#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
168#[serde(untagged)]
169pub enum RedisConfigs {
170    /// All pools should be configured the same way.
171    Unified(RedisConfig),
172    /// Individual configurations for each pool.
173    Individual {
174        /// Configuration for the `project_configs` pool.
175        project_configs: Box<RedisConfig>,
176        /// Configuration for the `quotas` pool.
177        quotas: Box<RedisConfig>,
178    },
179}
180
181/// Reference to the [`RedisConfig`] with the final [`RedisConfigOptions`].
182#[derive(Clone, Debug)]
183pub enum RedisConfigRef<'a> {
184    /// Connect to a Redis Cluster.
185    Cluster {
186        /// Reference to the Redis nodes urls of the cluster.
187        cluster_nodes: &'a Vec<String>,
188        /// Options of the Redis config.
189        options: RedisConfigOptions,
190    },
191    /// Write to multiple Redis instances, results are returned from the first.
192    MultiWrite {
193        /// Configurations for the Redis instances.
194        configs: Vec<RedisConfigRef<'a>>,
195    },
196    /// Connect to a single Redis instance.
197    Single {
198        /// Reference to the Redis node url.
199        server: &'a String,
200        /// Options of the Redis config.
201        options: RedisConfigOptions,
202    },
203}
204
205/// Helper struct bundling connections and options for the various Redis pools.
206#[allow(clippy::large_enum_variant)]
207#[derive(Clone, Debug)]
208pub enum RedisConfigsRef<'a> {
209    /// Use one pool for everything.
210    Unified(RedisConfigRef<'a>),
211    /// Use an individual pool for each use case.
212    Individual {
213        /// Configuration for the `project_configs` pool.
214        project_configs: RedisConfigRef<'a>,
215        /// Configuration for the `quotas` pool.
216        quotas: RedisConfigRef<'a>,
217    },
218}
219
220fn build_redis_config_options(
221    options: &PartialRedisConfigOptions,
222    default_connections: u32,
223) -> RedisConfigOptions {
224    let max_connections = options.max_connections.unwrap_or(default_connections);
225
226    RedisConfigOptions {
227        max_connections,
228        idle_timeout: options.idle_timeout,
229        create_timeout: options.create_timeout,
230        recycle_timeout: options.recycle_timeout,
231        wait_timeout: options.wait_timeout,
232        response_timeout: options.response_timeout,
233    }
234}
235
236/// Builds a [`RedisConfigsRef`] given a [`RedisConfig`].
237///
238/// The returned config contains more options for setting up Redis.
239pub(super) fn build_redis_config(
240    config: &RedisConfig,
241    default_connections: u32,
242) -> RedisConfigRef<'_> {
243    match config {
244        RedisConfig::Cluster {
245            cluster_nodes,
246            options,
247        } => RedisConfigRef::Cluster {
248            cluster_nodes,
249            options: build_redis_config_options(options, default_connections),
250        },
251        RedisConfig::MultiWrite { configs } => RedisConfigRef::MultiWrite {
252            configs: configs
253                .iter()
254                .map(|c| build_redis_config(c, default_connections))
255                .collect(),
256        },
257        RedisConfig::Single(SingleRedisConfig::Detailed { server, options }) => {
258            RedisConfigRef::Single {
259                server,
260                options: build_redis_config_options(options, default_connections),
261            }
262        }
263        RedisConfig::Single(SingleRedisConfig::Simple(server)) => RedisConfigRef::Single {
264            server,
265            options: Default::default(),
266        },
267    }
268}
269
270/// Builds a [`RedisConfigsRef`] given a [`RedisConfigs`].
271///
272/// The returned configs contain more options for setting up Redis.
273pub(super) fn build_redis_configs(
274    configs: &RedisConfigs,
275    cpu_concurrency: u32,
276    pool_concurrency: u32,
277) -> RedisConfigsRef<'_> {
278    // Project configurations are estimated to need around or less of `cpu_concurrency`
279    // connections, double this value for some extra headroom.
280    //
281    // For smaller setups give some extra headroom through `DEFAULT_MIN_MAX_CONNECTIONS`.
282    let project_connections = std::cmp::max(cpu_concurrency * 2, DEFAULT_MIN_MAX_CONNECTIONS);
283    // The total concurrency for rate limiting/processing is the total pool concurrency
284    // calculated by `cpu_concurrency * pool_concurrency`.
285    //
286    // No need to consider `DEFAULT_MIN_MAX_CONNECTIONS`, as these numbers are accurate.
287    let total_pool_concurrency = cpu_concurrency * pool_concurrency;
288
289    match configs {
290        RedisConfigs::Unified(cfg) => {
291            // A unified pool needs enough connections for project configs and enough to satisfy
292            // the processing pool.
293            let default_connections = total_pool_concurrency + project_connections;
294            let config = build_redis_config(cfg, default_connections);
295            RedisConfigsRef::Unified(config)
296        }
297        RedisConfigs::Individual {
298            project_configs,
299            quotas,
300        } => {
301            let project_configs = build_redis_config(project_configs, project_connections);
302            let quotas = build_redis_config(quotas, total_pool_concurrency);
303            RedisConfigsRef::Individual {
304                project_configs,
305                quotas,
306            }
307        }
308    }
309}
310
311#[cfg(test)]
312mod tests {
313    use insta::assert_json_snapshot;
314
315    use super::*;
316
317    #[test]
318    fn test_redis_single_opts() {
319        let yaml = r#"
320server: "redis://127.0.0.1:6379"
321max_connections: 42
322connection_timeout: 5
323"#;
324
325        let config: RedisConfig = serde_yaml::from_str(yaml)
326            .expect("Parsed processing redis config: single with options");
327
328        assert_eq!(
329            config,
330            RedisConfig::Single(SingleRedisConfig::Detailed {
331                server: "redis://127.0.0.1:6379".to_owned(),
332                options: PartialRedisConfigOptions {
333                    max_connections: Some(42),
334                    ..Default::default()
335                }
336            })
337        );
338    }
339
340    #[test]
341    fn test_redis_single_opts_unified() {
342        let yaml = r#"
343server: "redis://127.0.0.1:6379"
344max_connections: 42
345connection_timeout: 5
346"#;
347
348        let config: RedisConfigs = serde_yaml::from_str(yaml)
349            .expect("Parsed processing redis config: single with options");
350
351        assert_eq!(
352            config,
353            RedisConfigs::Unified(RedisConfig::Single(SingleRedisConfig::Detailed {
354                server: "redis://127.0.0.1:6379".to_owned(),
355                options: PartialRedisConfigOptions {
356                    max_connections: Some(42),
357                    ..Default::default()
358                }
359            }))
360        );
361    }
362
363    #[test]
364    fn test_redis_individual() {
365        let yaml = r#"
366project_configs:
367    server: "redis://127.0.0.1:6379"
368    max_connections: 42
369quotas:
370    cluster_nodes:
371        - "redis://127.0.0.1:6379"
372        - "redis://127.0.0.2:6379"
373    max_connections: 17
374"#;
375
376        let configs: RedisConfigs = serde_yaml::from_str(yaml)
377            .expect("Parsed processing redis configs: single with options");
378
379        let expected = RedisConfigs::Individual {
380            project_configs: Box::new(RedisConfig::Single(SingleRedisConfig::Detailed {
381                server: "redis://127.0.0.1:6379".to_owned(),
382                options: PartialRedisConfigOptions {
383                    max_connections: Some(42),
384                    ..Default::default()
385                },
386            })),
387            quotas: Box::new(RedisConfig::Cluster {
388                cluster_nodes: vec![
389                    "redis://127.0.0.1:6379".to_owned(),
390                    "redis://127.0.0.2:6379".to_owned(),
391                ],
392                options: PartialRedisConfigOptions {
393                    max_connections: Some(17),
394                    ..Default::default()
395                },
396            }),
397        };
398
399        assert_eq!(configs, expected);
400    }
401
402    #[test]
403    fn test_redis_single_serialize() {
404        let config = RedisConfig::Single(SingleRedisConfig::Detailed {
405            server: "redis://127.0.0.1:6379".to_owned(),
406            options: PartialRedisConfigOptions {
407                max_connections: Some(42),
408                ..Default::default()
409            },
410        });
411
412        assert_json_snapshot!(config, @r#"
413        {
414          "server": "redis://127.0.0.1:6379",
415          "max_connections": 42,
416          "idle_timeout": 60,
417          "create_timeout": 3,
418          "recycle_timeout": 2,
419          "response_timeout": 30
420        }
421        "#);
422    }
423
424    #[test]
425    fn test_redis_single_serialize_unified() {
426        let configs = RedisConfigs::Unified(RedisConfig::Single(SingleRedisConfig::Detailed {
427            server: "redis://127.0.0.1:6379".to_owned(),
428            options: PartialRedisConfigOptions {
429                max_connections: Some(42),
430                ..Default::default()
431            },
432        }));
433
434        assert_json_snapshot!(configs, @r#"
435        {
436          "server": "redis://127.0.0.1:6379",
437          "max_connections": 42,
438          "idle_timeout": 60,
439          "create_timeout": 3,
440          "recycle_timeout": 2,
441          "response_timeout": 30
442        }
443        "#);
444    }
445
446    #[test]
447    fn test_redis_single_opts_default() {
448        let yaml = r#"
449server: "redis://127.0.0.1:6379"
450"#;
451
452        let config: RedisConfig = serde_yaml::from_str(yaml)
453            .expect("Parsed processing redis config: single with options");
454
455        assert_eq!(
456            config,
457            RedisConfig::Single(SingleRedisConfig::Detailed {
458                server: "redis://127.0.0.1:6379".to_owned(),
459                options: Default::default()
460            })
461        );
462    }
463
464    // To make sure that we have backwards compatibility and still support the redis configuration
465    // when the single `redis://...` address is provided.
466    #[test]
467    fn test_redis_single() {
468        let yaml = r#"
469"redis://127.0.0.1:6379"
470"#;
471
472        let config: RedisConfig = serde_yaml::from_str(yaml)
473            .expect("Parsed processing redis config: single with options");
474
475        assert_eq!(
476            config,
477            RedisConfig::Single(SingleRedisConfig::Simple(
478                "redis://127.0.0.1:6379".to_owned()
479            ))
480        );
481    }
482
483    #[test]
484    fn test_redis_cluster_nodes_opts() {
485        let yaml = r#"
486cluster_nodes:
487    - "redis://127.0.0.1:6379"
488    - "redis://127.0.0.2:6379"
489max_connections: 10
490"#;
491
492        let config: RedisConfig = serde_yaml::from_str(yaml)
493            .expect("Parsed processing redis config: single with options");
494
495        assert_eq!(
496            config,
497            RedisConfig::Cluster {
498                cluster_nodes: vec![
499                    "redis://127.0.0.1:6379".to_owned(),
500                    "redis://127.0.0.2:6379".to_owned()
501                ],
502                options: PartialRedisConfigOptions {
503                    max_connections: Some(10),
504                    ..Default::default()
505                },
506            }
507        );
508    }
509
510    #[test]
511    fn test_redis_cluster_nodes_opts_unified() {
512        let yaml = r#"
513cluster_nodes:
514    - "redis://127.0.0.1:6379"
515    - "redis://127.0.0.2:6379"
516max_connections: 20
517"#;
518
519        let config: RedisConfigs = serde_yaml::from_str(yaml)
520            .expect("Parsed processing redis config: single with options");
521
522        assert_eq!(
523            config,
524            RedisConfigs::Unified(RedisConfig::Cluster {
525                cluster_nodes: vec![
526                    "redis://127.0.0.1:6379".to_owned(),
527                    "redis://127.0.0.2:6379".to_owned()
528                ],
529                options: PartialRedisConfigOptions {
530                    max_connections: Some(20),
531                    ..Default::default()
532                },
533            })
534        );
535    }
536
537    #[test]
538    fn test_redis_multi_write() {
539        let yaml = r#"
540configs:
541    - cluster_nodes:
542          - "redis://127.0.0.1:6379"
543          - "redis://127.0.0.2:6379"
544      max_connections: 42
545    - server: "redis://127.0.0.3:6379"
546      max_connections: 84
547"#;
548
549        let config: RedisConfig = serde_yaml::from_str(yaml)
550            .expect("Parsed processing redis config: multi write with options");
551
552        assert_eq!(
553            config,
554            RedisConfig::MultiWrite {
555                configs: vec![
556                    RedisConfig::Cluster {
557                        cluster_nodes: vec![
558                            "redis://127.0.0.1:6379".to_owned(),
559                            "redis://127.0.0.2:6379".to_owned()
560                        ],
561                        options: PartialRedisConfigOptions {
562                            max_connections: Some(42),
563                            ..Default::default()
564                        },
565                    },
566                    RedisConfig::Single(SingleRedisConfig::Detailed {
567                        server: "redis://127.0.0.3:6379".to_owned(),
568                        options: PartialRedisConfigOptions {
569                            max_connections: Some(84),
570                            ..Default::default()
571                        },
572                    }),
573                ],
574            }
575        );
576    }
577
578    #[test]
579    fn test_redis_cluster_serialize() {
580        let config = RedisConfig::Cluster {
581            cluster_nodes: vec![
582                "redis://127.0.0.1:6379".to_owned(),
583                "redis://127.0.0.2:6379".to_owned(),
584            ],
585            options: PartialRedisConfigOptions {
586                max_connections: Some(42),
587                ..Default::default()
588            },
589        };
590
591        assert_json_snapshot!(config, @r#"
592        {
593          "cluster_nodes": [
594            "redis://127.0.0.1:6379",
595            "redis://127.0.0.2:6379"
596          ],
597          "max_connections": 42,
598          "idle_timeout": 60,
599          "create_timeout": 3,
600          "recycle_timeout": 2,
601          "response_timeout": 30
602        }
603        "#);
604    }
605
606    #[test]
607    fn test_redis_cluster_serialize_unified() {
608        let configs = RedisConfigs::Unified(RedisConfig::Cluster {
609            cluster_nodes: vec![
610                "redis://127.0.0.1:6379".to_owned(),
611                "redis://127.0.0.2:6379".to_owned(),
612            ],
613            options: PartialRedisConfigOptions {
614                max_connections: Some(42),
615                ..Default::default()
616            },
617        });
618
619        assert_json_snapshot!(configs, @r#"
620        {
621          "cluster_nodes": [
622            "redis://127.0.0.1:6379",
623            "redis://127.0.0.2:6379"
624          ],
625          "max_connections": 42,
626          "idle_timeout": 60,
627          "create_timeout": 3,
628          "recycle_timeout": 2,
629          "response_timeout": 30
630        }
631        "#);
632    }
633
634    #[test]
635    fn test_redis_serialize_individual() {
636        let configs = RedisConfigs::Individual {
637            project_configs: Box::new(RedisConfig::Single(SingleRedisConfig::Detailed {
638                server: "redis://127.0.0.1:6379".to_owned(),
639                options: PartialRedisConfigOptions {
640                    max_connections: Some(42),
641                    ..Default::default()
642                },
643            })),
644            quotas: Box::new(RedisConfig::Cluster {
645                cluster_nodes: vec![
646                    "redis://127.0.0.1:6379".to_owned(),
647                    "redis://127.0.0.2:6379".to_owned(),
648                ],
649                options: PartialRedisConfigOptions {
650                    max_connections: Some(84),
651                    ..Default::default()
652                },
653            }),
654        };
655
656        assert_json_snapshot!(configs, @r#"
657        {
658          "project_configs": {
659            "server": "redis://127.0.0.1:6379",
660            "max_connections": 42,
661            "idle_timeout": 60,
662            "create_timeout": 3,
663            "recycle_timeout": 2,
664            "response_timeout": 30
665          },
666          "quotas": {
667            "cluster_nodes": [
668              "redis://127.0.0.1:6379",
669              "redis://127.0.0.2:6379"
670            ],
671            "max_connections": 84,
672            "idle_timeout": 60,
673            "create_timeout": 3,
674            "recycle_timeout": 2,
675            "response_timeout": 30
676          }
677        }
678        "#);
679    }
680}