Skip to main content

laser_wire/
clients.rs

1use serde::{Deserialize, Serialize};
2
3/// The discovery read request (`AGDX_GET_CLIENTS_METADATA`). Filtered and
4/// paginated, because a busy server may hold thousands of connections and a
5/// caller must not have to pull them all at once. The server orders connections
6/// by `client_id`, applies the filters, skips past `after_client_id`, and returns
7/// up to `limit` entries plus a cursor when more remain.
8#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
9#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
10pub struct ClientMetadataQuery {
11    pub v: u32,
12    /// Only return connections that advertised metadata. The common case for
13    /// discovery, where unannounced connections are noise.
14    #[serde(default, skip_serializing_if = "is_false")]
15    pub with_metadata_only: bool,
16    /// Only return connections authenticated as this principal.
17    #[serde(default, skip_serializing_if = "Option::is_none")]
18    pub user_id: Option<u32>,
19    /// Pagination cursor: return only connections whose `client_id` is strictly
20    /// greater than this. `None` starts from the beginning.
21    #[serde(default, skip_serializing_if = "Option::is_none")]
22    pub after_client_id: Option<u32>,
23    /// Max entries to return. Clamped server-side to the page cap.
24    pub limit: u32,
25}
26
27fn is_false(value: &bool) -> bool {
28    !*value
29}
30
31/// One connection's discovery record: the connection identity the streaming
32/// server holds plus the opaque metadata the client advertised. A LaserData-owned
33/// type, deliberately distinct from the upstream Apache Iggy `ClientInfo` (which
34/// stays byte-identical so an Apache Iggy SDK keeps working against LaserData
35/// Cloud). The metadata is opaque: an agent advertises its card, a regular app
36/// sets any blob the consumer interprets.
37#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
38#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
39pub struct ClientMetadata {
40    pub client_id: u32,
41    #[serde(default, skip_serializing_if = "Option::is_none")]
42    pub user_id: Option<u32>,
43    /// Transport code (1 Tcp, 2 Quic, 3 Http, 4 WebSocket), the same dictionary
44    /// the upstream binding uses.
45    pub transport: u8,
46    pub address: String,
47    pub consumer_groups_count: u32,
48    #[cfg_attr(
49        feature = "schemars",
50        schemars(schema_with = "crate::encoding::opt_bytes_schema")
51    )]
52    #[serde(
53        default,
54        skip_serializing_if = "Option::is_none",
55        with = "crate::encoding::opt_bin_bytes"
56    )]
57    pub metadata: Option<Vec<u8>>,
58}
59
60/// The reply to `AGDX_GET_CLIENTS_METADATA`: one page of connections with their
61/// advertised metadata, plus `next_cursor` (the last `client_id` in the page) when
62/// more connections remain, so the caller pages by passing it as the next
63/// `after_client_id`. `None` means the last page.
64#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
65#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
66pub struct ClientMetadataList {
67    pub clients: Vec<ClientMetadata>,
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub next_cursor: Option<u32>,
70}
71
72#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
73#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
74pub struct ProducerPresence {
75    pub producer_presence_version: u32,
76    pub observed_at_millis: u64,
77    pub expires_after_millis: u64,
78    pub producers: Vec<ProducerStatistics>,
79}
80
81#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
82#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
83pub struct ProducerStatistics {
84    pub instance_id: String,
85    pub stream: String,
86    pub topic: String,
87    pub first_activity_millis: u64,
88    pub last_activity_millis: u64,
89    pub submitted_records: u64,
90    pub submitted_payload_bytes: u64,
91    pub confirmed_records: Option<u64>,
92    pub confirmed_payload_bytes: Option<u64>,
93    pub retries: Option<u64>,
94    pub failed_calls: u64,
95    pub last_success_millis: Option<u64>,
96    pub latency: ProducerLatency,
97}
98
99#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
100#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
101pub struct ProducerLatency {
102    pub samples: u64,
103    pub p50_micros: Option<u64>,
104    pub p99_micros: Option<u64>,
105    pub p999_micros: Option<u64>,
106}