log/config.rs
1//! Configuration options for OpenData Log operations.
2//!
3//! This module defines the configuration and options structs that control
4//! the behavior of the log, including storage setup and operation parameters.
5
6use std::time::Duration;
7
8use common::StorageConfig;
9use serde::{Deserialize, Serialize};
10use serde_with::{DurationMilliSeconds, serde_as};
11
12/// Configuration for opening a [`Log`](crate::Log).
13///
14/// This struct holds all the settings needed to initialize a log instance,
15/// including storage backend configuration.
16///
17/// # Example
18///
19/// ```ignore
20/// use log::Config;
21/// use common::StorageConfig;
22///
23/// let config = Config {
24/// storage: StorageConfig::default(),
25/// segmentation: SegmentConfig::default(),
26/// };
27/// let log = LogDb::open(config).await?;
28/// ```
29#[derive(Debug, Clone, Default, Serialize, Deserialize)]
30pub struct Config {
31 /// Storage backend configuration.
32 ///
33 /// Determines where and how log data is persisted. See [`StorageConfig`]
34 /// for available options including in-memory and SlateDB backends.
35 pub storage: StorageConfig,
36
37 /// Segmentation configuration.
38 ///
39 /// Controls how the log is partitioned into segments for efficient
40 /// time-based queries and retention management.
41 #[serde(default)]
42 pub segmentation: SegmentConfig,
43}
44
45/// Configuration for log segmentation.
46///
47/// Segments partition the log into time-based chunks, enabling efficient
48/// range queries and retention management. See RFC 0002 for details.
49#[serde_as]
50#[derive(Debug, Clone, Default, Serialize, Deserialize)]
51pub struct SegmentConfig {
52 /// Interval for automatic segment sealing based on wall-clock time.
53 ///
54 /// When set, a new segment is created after the specified duration has
55 /// elapsed since the current segment was created. This enables time-based
56 /// partitioning for efficient queries and retention.
57 ///
58 /// When `None` (the default), automatic sealing is disabled and all
59 /// entries are written to segment 0 indefinitely.
60 ///
61 /// # Example
62 ///
63 /// ```ignore
64 /// use std::time::Duration;
65 /// use log::SegmentConfig;
66 ///
67 /// // Create a new segment every hour
68 /// let config = SegmentConfig {
69 /// seal_interval: Some(Duration::from_secs(3600)),
70 /// };
71 /// ```
72 #[serde_as(as = "Option<DurationMilliSeconds<u64>>")]
73 #[serde(default)]
74 pub seal_interval: Option<Duration>,
75}
76
77/// Options for write operations.
78///
79/// Controls the durability and behavior of [`LogDb::append`](crate::LogDb::append)
80/// and [`LogDb::append_with_options`](crate::LogDb::append_with_options).
81#[derive(Debug, Clone, Default)]
82pub struct WriteOptions {
83 /// Whether to wait for the write to be durable before returning.
84 ///
85 /// When `true`, the append operation will not return until the data has
86 /// been persisted to durable storage (e.g., flushed to the WAL and
87 /// acknowledged by the object store).
88 ///
89 /// When `false` (the default), the operation returns as soon as the data
90 /// is in memory, providing lower latency but risking data loss on crash.
91 pub await_durable: bool,
92}
93
94/// Options for scan operations.
95///
96/// Controls the behavior of [`LogRead::scan`](crate::LogRead::scan) and
97/// [`LogRead::scan_with_options`](crate::LogRead::scan_with_options).
98/// Additional options may be added in future versions.
99#[derive(Debug, Clone, Default)]
100pub struct ScanOptions {
101 // Reserved for future options such as:
102 // - read_level: control consistency vs performance tradeoff
103 // - cache_policy: control block cache behavior
104}
105
106/// Options for count operations.
107///
108/// Controls the behavior of [`LogRead::count`](crate::LogRead::count) and
109/// [`LogRead::count_with_options`](crate::LogRead::count_with_options).
110#[derive(Debug, Clone, Default)]
111pub struct CountOptions {
112 /// Whether to return an approximate count.
113 ///
114 /// When `true`, the count may be computed from index metadata without
115 /// reading individual entries, providing faster results at the cost
116 /// of accuracy. Useful for progress indicators and lag estimation.
117 ///
118 /// When `false` (the default), an exact count is computed by scanning
119 /// the relevant index entries.
120 pub approximate: bool,
121}
122
123/// Configuration for opening a [`LogDbReader`](crate::LogDbReader).
124///
125/// This struct holds settings for read-only log access, including storage
126/// backend configuration and automatic refresh settings.
127///
128/// # Example
129///
130/// ```ignore
131/// use log::ReaderConfig;
132/// use common::StorageConfig;
133/// use std::time::Duration;
134///
135/// let config = ReaderConfig {
136/// storage: StorageConfig::default(),
137/// refresh_interval: Duration::from_secs(1),
138/// };
139/// let reader = LogDbReader::open(config).await?;
140/// ```
141#[serde_as]
142#[derive(Debug, Clone, Serialize, Deserialize)]
143pub struct ReaderConfig {
144 /// Storage backend configuration.
145 ///
146 /// Determines where and how log data is read. See [`StorageConfig`]
147 /// for available options including in-memory and SlateDB backends.
148 pub storage: StorageConfig,
149
150 /// Interval for discovering new log data.
151 ///
152 /// The reader periodically checks for new data written by other processes
153 /// at this interval. This enables readers to see new log entries without
154 /// manual refresh calls.
155 ///
156 /// Defaults to 1 second.
157 #[serde_as(as = "DurationMilliSeconds<u64>")]
158 #[serde(default = "default_refresh_interval")]
159 pub refresh_interval: Duration,
160}
161
162fn default_refresh_interval() -> Duration {
163 Duration::from_secs(1)
164}
165
166impl Default for ReaderConfig {
167 fn default() -> Self {
168 Self {
169 storage: StorageConfig::default(),
170 refresh_interval: default_refresh_interval(),
171 }
172 }
173}