sylvia_iot_broker/models/
device_route.rs

1//! Traits and structs for device routes.
2
3use std::error::Error as StdError;
4
5use async_trait::async_trait;
6use chrono::{DateTime, Utc};
7
8/// The item content.
9#[derive(Debug, PartialEq)]
10pub struct DeviceRoute {
11    pub route_id: String,
12    pub unit_id: String,
13    pub unit_code: String, // Application's unit code.
14    pub application_id: String,
15    pub application_code: String,
16    pub device_id: String,
17    pub network_id: String,
18    pub network_code: String,
19    pub network_addr: String,
20    pub profile: String,
21    pub created_at: DateTime<Utc>,
22    pub modified_at: DateTime<Utc>,
23}
24
25// The device route cache item for uplink data.
26#[derive(Clone)]
27pub struct DeviceRouteCacheUlData {
28    pub app_mgr_keys: Vec<String>,
29}
30
31// The device route cache item for downlink data.
32// All None or all Some.
33#[derive(Clone)]
34pub struct DeviceRouteCacheDlData {
35    pub net_mgr_key: String,
36    pub network_id: String,
37    pub network_addr: String,
38    pub device_id: String,
39    pub profile: String,
40}
41
42/// The sort keys for the list operation.
43pub enum SortKey {
44    CreatedAt,
45    ModifiedAt,
46    ApplicationCode,
47    NetworkCode,
48    NetworkAddr,
49}
50
51/// The sort condition for the list operation.
52pub struct SortCond {
53    pub key: SortKey,
54    pub asc: bool,
55}
56
57/// The list operation options.
58pub struct ListOptions<'a> {
59    /// The query conditions.
60    pub cond: &'a ListQueryCond<'a>,
61    /// The data offset.
62    pub offset: Option<u64>,
63    /// The maximum number to query.
64    pub limit: Option<u64>,
65    /// The sort conditions.
66    pub sort: Option<&'a [SortCond]>,
67    /// The maximum number items one time the `list()` returns.
68    ///
69    /// Use cursors until reaching `limit` or all data.
70    pub cursor_max: Option<u64>,
71}
72
73/// The query condition to get item(s).
74#[derive(Default)]
75pub struct QueryCond<'a> {
76    pub route_id: Option<&'a str>,
77    pub unit_id: Option<&'a str>,
78    pub application_id: Option<&'a str>,
79    pub network_id: Option<&'a str>,
80    pub device_id: Option<&'a str>,
81    pub network_addrs: Option<&'a Vec<&'a str>>,
82}
83
84/// The query condition for the list operation.
85#[derive(Default)]
86pub struct ListQueryCond<'a> {
87    /// To get the specified device route.
88    pub route_id: Option<&'a str>,
89    /// To get device routes of the specified unit.
90    pub unit_id: Option<&'a str>,
91    /// To get device routes of the specified unit code.
92    pub unit_code: Option<&'a str>,
93    /// To get device routes of the specified application.
94    pub application_id: Option<&'a str>,
95    /// To get device routes of the specified application code.
96    pub application_code: Option<&'a str>,
97    /// To get device routes of the specified network.
98    pub network_id: Option<&'a str>,
99    /// To get device routes of the specified network code.
100    pub network_code: Option<&'a str>,
101    /// To get device routes of the specified network address.
102    pub network_addr: Option<&'a str>,
103    /// To get devices of the specified network addresses.
104    pub network_addrs: Option<&'a Vec<&'a str>>,
105    /// To get device routes of the specified device.
106    pub device_id: Option<&'a str>,
107}
108
109/// The query condition for the get cache operation.
110pub struct GetCacheQueryCond<'a> {
111    /// To get device routes of the specified network unit code.
112    pub unit_code: &'a str,
113    /// To get device routes of the specified network code.
114    pub network_code: &'a str,
115    /// To get device routes of the specified network address.
116    pub network_addr: &'a str,
117}
118
119/// The query condition for the delete cache operation.
120pub struct DelCacheQueryCond<'a> {
121    /// To delete device routes of the specified network unit code. Empty for public network.
122    pub unit_code: &'a str,
123    /// To delete device routes of the specified network code.
124    pub network_code: Option<&'a str>,
125    /// To delete device routes of the specified network address.
126    pub network_addr: Option<&'a str>,
127}
128
129/// The query condition for the get (public network) downlink data cache operation.
130pub struct GetCachePubQueryCond<'a> {
131    /// To get device routes of the specified device's unit ID.
132    pub unit_id: &'a str,
133    /// To get device routes of the specified device ID.
134    pub device_id: &'a str,
135}
136
137/// The query condition for the delete (public network) downlink data cache operation.
138pub struct DelCachePubQueryCond<'a> {
139    /// To delete device routes of the specified device unit ID.
140    pub unit_id: &'a str,
141    /// To delete device routes of the specified device ID.
142    pub device_id: Option<&'a str>,
143}
144
145/// The query condition for the update operation.
146pub struct UpdateQueryCond<'a> {
147    /// The specified device.
148    pub device_id: &'a str,
149}
150
151/// The update fields by using [`Some`]s.
152#[derive(Default)]
153pub struct Updates<'a> {
154    pub modified_at: Option<DateTime<Utc>>,
155    pub profile: Option<&'a str>,
156}
157
158/// Model operations.
159#[async_trait]
160pub trait DeviceRouteModel: Sync {
161    /// To create and initialize the table/collection.
162    async fn init(&self) -> Result<(), Box<dyn StdError>>;
163
164    /// To get item count for the query condition.
165    ///
166    /// **Note**: this may take a long time.
167    async fn count(&self, cond: &ListQueryCond) -> Result<u64, Box<dyn StdError>>;
168
169    /// To get item list. The maximum number of returned items will be controlled by the
170    /// `cursor_max` of the list option.
171    ///
172    /// For the first time, `cursor` MUST use `None`. If one cursor is returned, it means that
173    /// there are more items to get. Use the returned cursor to get more data items.
174    ///
175    /// **Note**: using cursors is recommended to prevent exhausting memory.
176    async fn list(
177        &self,
178        opts: &ListOptions,
179        cursor: Option<Box<dyn Cursor>>,
180    ) -> Result<(Vec<DeviceRoute>, Option<Box<dyn Cursor>>), Box<dyn StdError>>;
181
182    /// To get an item.
183    ///
184    /// **Note**: this is only used for function test.
185    async fn get(&self, route_id: &str) -> Result<Option<DeviceRoute>, Box<dyn StdError>>;
186
187    /// To add an item.
188    async fn add(&self, route: &DeviceRoute) -> Result<(), Box<dyn StdError>>;
189
190    /// To add items in bulk. Duplicate items will be skipped without errors.
191    async fn add_bulk(&self, devices: &Vec<DeviceRoute>) -> Result<(), Box<dyn StdError>>;
192
193    /// To delete one or more items.
194    async fn del(&self, cond: &QueryCond) -> Result<(), Box<dyn StdError>>;
195
196    /// To update one or more items.
197    async fn update(
198        &self,
199        cond: &UpdateQueryCond,
200        updates: &Updates,
201    ) -> Result<(), Box<dyn StdError>>;
202}
203
204/// The operations for cursors.
205///
206/// All functions are private to let programs to pass them as arguments directly without any
207/// operation.
208#[async_trait]
209pub trait Cursor: Send {
210    async fn try_next(&mut self) -> Result<Option<DeviceRoute>, Box<dyn StdError>>;
211
212    fn offset(&self) -> u64;
213}
214
215/// Cache operations.
216#[async_trait]
217pub trait DeviceRouteCache: Sync {
218    /// To clear all device routes.
219    async fn clear(&self) -> Result<(), Box<dyn StdError>>;
220
221    /// To get device route for the uplink data.
222    async fn get_uldata(
223        &self,
224        device_id: &str,
225    ) -> Result<Option<DeviceRouteCacheUlData>, Box<dyn StdError>>;
226
227    /// To set device route for the uplink data.
228    async fn set_uldata(
229        &self,
230        device_id: &str,
231        value: Option<&DeviceRouteCacheUlData>,
232    ) -> Result<(), Box<dyn StdError>>;
233
234    /// To delete device route for the uplink data.
235    async fn del_uldata(&self, device_id: &str) -> Result<(), Box<dyn StdError>>;
236
237    /// To get device route for the downlink data.
238    async fn get_dldata(
239        &self,
240        cond: &GetCacheQueryCond,
241    ) -> Result<Option<DeviceRouteCacheDlData>, Box<dyn StdError>>;
242
243    /// To set device route for the downlink data.
244    async fn set_dldata(
245        &self,
246        cond: &GetCacheQueryCond,
247        value: Option<&DeviceRouteCacheDlData>,
248    ) -> Result<(), Box<dyn StdError>>;
249
250    /// To delete device route for the downlink data.
251    async fn del_dldata(&self, cond: &DelCacheQueryCond) -> Result<(), Box<dyn StdError>>;
252
253    /// To get device route for the (public network) downlink data.
254    async fn get_dldata_pub(
255        &self,
256        cond: &GetCachePubQueryCond,
257    ) -> Result<Option<DeviceRouteCacheDlData>, Box<dyn StdError>>;
258
259    /// To set device route for the (public network) downlink data.
260    async fn set_dldata_pub(
261        &self,
262        cond: &GetCachePubQueryCond,
263        value: Option<&DeviceRouteCacheDlData>,
264    ) -> Result<(), Box<dyn StdError>>;
265
266    /// To delete device route for the (public network) downlink data.
267    async fn del_dldata_pub(&self, cond: &DelCachePubQueryCond) -> Result<(), Box<dyn StdError>>;
268}
sylvia_iot_broker/models/device_route.rs

sylvia_iot_broker/models/
device_route.rs
