nautilus_common/generators/
position_id.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use core::fmt::NumBuffer;
17use std::{
18    cell::RefCell,
19    collections::HashMap,
20    fmt::{Debug, Write},
21    rc::Rc,
22};
23
24use jiff::{Timestamp, tz::Offset};
25use nautilus_model::identifiers::{PositionId, StrategyId, TraderId};
26
27use crate::clock::Clock;
28
29const DATETIME_TAG_LEN: usize = 15; // "YYYYMMDD-HHMMSS"
30// Reserve for strategy_tag + "-" + decimal count + optional "F" past the cached fixed prefix
31const STRATEGY_AND_COUNT_RESERVE: usize = 32;
32
33#[repr(C)]
34pub struct PositionIdGenerator {
35    clock: Rc<RefCell<dyn Clock>>,
36    trader_id: TraderId,
37    counts: HashMap<StrategyId, usize>,
38    trader_tag: String,
39    buf: String,
40    fixed_prefix_len: usize,
41    epoch_second: u64,
42    count_buf: NumBuffer<usize>,
43}
44
45impl Debug for PositionIdGenerator {
46    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
47        f.debug_struct(stringify!(PositionIdGenerator))
48            .field("trader_id", &self.trader_id)
49            .field("counts", &self.counts)
50            .field("trader_tag", &self.trader_tag)
51            .field("buf", &self.buf)
52            .field("fixed_prefix_len", &self.fixed_prefix_len)
53            .field("epoch_second", &self.epoch_second)
54            .finish_non_exhaustive()
55    }
56}
57
58impl PositionIdGenerator {
59    /// Creates a new [`PositionIdGenerator`] instance.
60    #[must_use]
61    pub fn new(trader_id: TraderId, clock: Rc<RefCell<dyn Clock>>) -> Self {
62        let trader_tag = trader_id.get_tag().to_string();
63        let buf = String::with_capacity(
64            "P-".len()
65                + DATETIME_TAG_LEN
66                + "-".len()
67                + trader_tag.len()
68                + "-".len()
69                + STRATEGY_AND_COUNT_RESERVE,
70        );
71
72        Self {
73            clock,
74            trader_id,
75            counts: HashMap::new(),
76            trader_tag,
77            buf,
78            fixed_prefix_len: 0,
79            epoch_second: u64::MAX,
80            count_buf: NumBuffer::new(),
81        }
82    }
83
84    pub fn set_count(&mut self, count: usize, strategy_id: StrategyId) {
85        self.counts.insert(strategy_id, count);
86    }
87
88    pub fn reset(&mut self) {
89        self.counts.clear();
90    }
91
92    #[must_use]
93    pub fn count(&self, strategy_id: StrategyId) -> usize {
94        *self.counts.get(&strategy_id).unwrap_or(&0)
95    }
96
97    pub fn generate(&mut self, strategy_id: StrategyId, flipped: bool) -> PositionId {
98        let next_count = self.count(strategy_id) + 1;
99        self.set_count(next_count, strategy_id);
100
101        let timestamp_ms = self.clock.borrow().timestamp_ms();
102        self.refresh_fixed_prefix(timestamp_ms);
103
104        self.buf.truncate(self.fixed_prefix_len);
105        self.buf.push_str(strategy_id.get_tag());
106        self.buf.push('-');
107        self.buf
108            .push_str(next_count.format_into(&mut self.count_buf));
109
110        if flipped {
111            self.buf.push('F');
112        }
113
114        PositionId::from(self.buf.as_str())
115    }
116
117    #[inline]
118    fn refresh_fixed_prefix(&mut self, timestamp_ms: u64) {
119        let epoch_second = timestamp_ms / 1_000;
120        if epoch_second == self.epoch_second {
121            return;
122        }
123
124        write_fixed_prefix(&mut self.buf, &self.trader_tag, epoch_second);
125        self.fixed_prefix_len = self.buf.len();
126        self.epoch_second = epoch_second;
127    }
128}
129
130fn write_fixed_prefix(buf: &mut String, trader_tag: &str, epoch_second: u64) {
131    let now_utc = Offset::UTC.to_datetime(
132        Timestamp::from_second(
133            i64::try_from(epoch_second).expect("seconds timestamp should fit i64"),
134        )
135        .expect("seconds timestamp should be within valid range"),
136    );
137
138    buf.clear();
139
140    write!(
141        buf,
142        "P-{:04}{:02}{:02}-{:02}{:02}{:02}-{trader_tag}-",
143        now_utc.year(),
144        now_utc.month(),
145        now_utc.day(),
146        now_utc.hour(),
147        now_utc.minute(),
148        now_utc.second(),
149    )
150    .expect("writing to String should not fail");
151}
152
153#[cfg(test)]
154mod tests {
155    use std::{cell::RefCell, rc::Rc};
156
157    use nautilus_core::UnixNanos;
158    use nautilus_model::{
159        identifiers::{PositionId, StrategyId, TraderId},
160        stubs::TestDefault,
161    };
162    use rstest::rstest;
163
164    use crate::{clock::TestClock, generators::position_id::PositionIdGenerator};
165
166    fn get_position_id_generator() -> PositionIdGenerator {
167        PositionIdGenerator::new(
168            TraderId::test_default(),
169            Rc::new(RefCell::new(TestClock::new())),
170        )
171    }
172
173    #[rstest]
174    fn test_generate_position_id_one_strategy() {
175        let mut generator = get_position_id_generator();
176        let result1 = generator.generate(StrategyId::from("S-001"), false);
177        let result2 = generator.generate(StrategyId::from("S-001"), false);
178
179        assert_eq!(result1, PositionId::from("P-19700101-000000-001-001-1"));
180        assert_eq!(result2, PositionId::from("P-19700101-000000-001-001-2"));
181    }
182
183    #[rstest]
184    fn test_generate_position_id_uses_final_strategy_tag() {
185        let mut generator = get_position_id_generator();
186        let result = generator.generate(StrategyId::from("ExampleStrategy-XNAS-T01"), false);
187
188        assert_eq!(result, PositionId::from("P-19700101-000000-001-T01-1"));
189    }
190
191    #[rstest]
192    fn test_generate_position_id_multiple_strategies() {
193        let mut generator = get_position_id_generator();
194        let result1 = generator.generate(StrategyId::from("S-001"), false);
195        let result2 = generator.generate(StrategyId::from("S-002"), false);
196        let result3 = generator.generate(StrategyId::from("S-002"), false);
197
198        assert_eq!(result1, PositionId::from("P-19700101-000000-001-001-1"));
199        assert_eq!(result2, PositionId::from("P-19700101-000000-001-002-1"));
200        assert_eq!(result3, PositionId::from("P-19700101-000000-001-002-2"));
201    }
202
203    #[rstest]
204    fn test_generate_position_id_with_flipped_appends_correctly() {
205        let mut generator = get_position_id_generator();
206        let result1 = generator.generate(StrategyId::from("S-001"), false);
207        let result2 = generator.generate(StrategyId::from("S-002"), true);
208        let result3 = generator.generate(StrategyId::from("S-001"), true);
209
210        assert_eq!(result1, PositionId::from("P-19700101-000000-001-001-1"));
211        assert_eq!(result2, PositionId::from("P-19700101-000000-001-002-1F"));
212        assert_eq!(result3, PositionId::from("P-19700101-000000-001-001-2F"));
213    }
214
215    #[rstest]
216    fn test_generate_persists_fixed_prefix_in_buffer_within_same_second() {
217        let mut generator = get_position_id_generator();
218
219        let result1 = generator.generate(StrategyId::from("S-001"), false);
220        let fixed_prefix = "P-19700101-000000-001-";
221        let capacity_after_first = generator.buf.capacity();
222
223        assert_eq!(result1, PositionId::from("P-19700101-000000-001-001-1"));
224        assert_eq!(generator.fixed_prefix_len, fixed_prefix.len());
225        assert_eq!(&generator.buf[..generator.fixed_prefix_len], fixed_prefix);
226
227        let result2 = generator.generate(StrategyId::from("S-001"), false);
228
229        assert_eq!(result2, PositionId::from("P-19700101-000000-001-001-2"));
230        assert_eq!(generator.fixed_prefix_len, fixed_prefix.len());
231        assert_eq!(&generator.buf[..generator.fixed_prefix_len], fixed_prefix);
232        assert_eq!(generator.buf.capacity(), capacity_after_first);
233    }
234
235    #[rstest]
236    fn test_generate_capacity_stable_across_strategies_same_second() {
237        let mut generator = get_position_id_generator();
238
239        // Prime the buffer; subsequent calls must not reallocate while strategies fit
240        // within STRATEGY_AND_COUNT_RESERVE.
241        generator.generate(StrategyId::from("S-001"), false);
242        let capacity_after_warmup = generator.buf.capacity();
243
244        for tag in ["S-002", "S-003", "STRATEGY-LONGER-001"] {
245            generator.generate(StrategyId::from(tag), false);
246        }
247
248        assert_eq!(generator.buf.capacity(), capacity_after_warmup);
249    }
250
251    #[rstest]
252    fn test_generate_refreshes_persistent_fixed_prefix_when_second_changes() {
253        let clock = Rc::new(RefCell::new(TestClock::new()));
254        let mut generator = PositionIdGenerator::new(TraderId::test_default(), clock.clone());
255
256        let result1 = generator.generate(StrategyId::from("S-001"), false);
257        clock.borrow_mut().set_time(UnixNanos::from(1_000_000_000));
258        let result2 = generator.generate(StrategyId::from("S-001"), false);
259
260        assert_eq!(result1, PositionId::from("P-19700101-000000-001-001-1"));
261        assert_eq!(result2, PositionId::from("P-19700101-000001-001-001-2"));
262        assert_eq!(generator.epoch_second, 1);
263        assert_eq!(
264            &generator.buf[..generator.fixed_prefix_len],
265            "P-19700101-000001-001-"
266        );
267    }
268
269    #[rstest]
270    fn test_get_count_when_strategy_id_has_not_been_used() {
271        let generator = get_position_id_generator();
272        let result = generator.count(StrategyId::from("S-001"));
273
274        assert_eq!(result, 0);
275    }
276
277    #[rstest]
278    fn set_count_with_valid_strategy() {
279        let mut generator = get_position_id_generator();
280        generator.set_count(7, StrategyId::from("S-001"));
281        let result = generator.count(StrategyId::from("S-001"));
282
283        assert_eq!(result, 7);
284    }
285
286    #[rstest]
287    fn test_reset() {
288        let mut generator = get_position_id_generator();
289        generator.generate(StrategyId::from("S-001"), false);
290        generator.generate(StrategyId::from("S-001"), false);
291        generator.reset();
292        let result = generator.generate(StrategyId::from("S-001"), false);
293
294        assert_eq!(result, PositionId::from("P-19700101-000000-001-001-1"));
295    }
296}
nautilus_common/generators/position_id.rs

nautilus_common/generators/
position_id.rs
