Skip to main content

subc_control/
activity.rs

1//! Additive activity ledger bodies, dispatched separately from the exhaustive
2//! client control enums by their `op` tag.
3
4use std::path::PathBuf;
5
6use serde::{Deserialize, Deserializer, Serialize};
7use serde_json::{Map, Value};
8use subc_protocol::Principal;
9
10use crate::ops;
11
12/// Advertised in HELLO_ACK and server.describe before activity operations are used.
13pub const ACTIVITY_LEDGER_CAPABILITY: &str = "activity-ledger/v1";
14
15pub const ACTIVITY_KIND_FORBIDDEN: &str = "activity_kind_forbidden";
16pub const ACTIVITY_ACTOR_UNKNOWN: &str = "activity_actor_unknown";
17pub const ACTIVITY_RATE_LIMITED: &str = "activity_rate_limited";
18pub const ACTIVITY_READ_FORBIDDEN: &str = "activity_read_forbidden";
19pub const ACTIVITY_TOO_LARGE: &str = "activity_too_large";
20pub const ACTIVITY_MALFORMED: &str = "activity_malformed";
21pub const ACTIVITY_UNAVAILABLE: &str = "activity_unavailable";
22pub const ACTIVITY_CURSOR_INCARNATION_MISMATCH: &str = "activity_cursor_incarnation_mismatch";
23pub const ACTIVITY_CURSOR_TOO_OLD: &str = "activity_cursor_too_old";
24pub const ACTIVITY_SUBSCRIBER_LAGGED: &str = "activity_subscriber_lagged";
25
26/// A live-feed position. Query continuation positions are sequence numbers only.
27#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
28pub struct ActivityCursor {
29    pub daemon_incarnation: String,
30    pub seq: u64,
31}
32
33/// A short typed pointer, never a secret value.
34#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
35#[serde(deny_unknown_fields)]
36pub struct ActivitySubject {
37    #[serde(rename = "type")]
38    pub subject_type: String,
39    pub id: String,
40}
41
42/// Verified identity stamped by the daemon, not supplied by a recording module.
43#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
44pub struct ActivityActor {
45    pub principal: Principal,
46    #[serde(default, skip_serializing_if = "Option::is_none")]
47    pub scope_owner: Option<Principal>,
48    #[serde(default, skip_serializing_if = "Option::is_none")]
49    pub agent_id: Option<String>,
50    #[serde(default, skip_serializing_if = "Option::is_none")]
51    pub run_id: Option<String>,
52    #[serde(default, skip_serializing_if = "Option::is_none")]
53    pub flow_id: Option<String>,
54    #[serde(default, skip_serializing_if = "Option::is_none")]
55    pub project_root: Option<PathBuf>,
56    /// Canonical folder from the route's scope, not the caller's bind identity.
57    #[serde(default, skip_serializing_if = "Option::is_none")]
58    pub workdir: Option<PathBuf>,
59    /// Entorhinal project id from the scope; attribution only.
60    #[serde(default, skip_serializing_if = "Option::is_none")]
61    pub project_id: Option<String>,
62}
63
64/// One durably appended event. `prev` is reserved for a future hash chain and is
65/// deliberately absent from this format. Identity is (daemon_incarnation, seq),
66/// and entries are ordered by seq rather than by their wall-clock timestamps.
67#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
68pub struct ActivityEntry {
69    pub seq: u64,
70    pub at_ms: u64,
71    pub daemon_incarnation: String,
72    pub module: String,
73    pub kind: String,
74    pub summary: String,
75    #[serde(default, skip_serializing_if = "Option::is_none")]
76    pub subject: Option<ActivitySubject>,
77    pub details: Map<String, Value>,
78    pub actor: ActivityActor,
79}
80
81/// A route binding owned by the recording module, checked at this epoch.
82#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
83#[serde(deny_unknown_fields)]
84pub struct ActivityRoute {
85    pub channel: u16,
86    pub epoch: u32,
87}
88
89/// A live scope owned by the recording module, checked at this epoch.
90#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
91#[serde(deny_unknown_fields)]
92pub struct ActivityScope {
93    #[serde(rename = "ref")]
94    pub scope_ref: String,
95    pub epoch: u64,
96}
97
98/// Exactly one citation from which the daemon resolves the actor.
99#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
100#[serde(rename_all = "snake_case")]
101pub enum ActivityOn {
102    Route(ActivityRoute),
103    Scope(ActivityScope),
104}
105
106// Serde's struct `tag` adds an op during serialization but does not validate it
107// during deserialization. A private tagged enum validates the op without adding
108// variants to the public client control enums or exposing an editable op field.
109macro_rules! activity_body {
110    ($(#[$doc:meta])* $name:ident, $op:path, $wire_name:literal,
111     $(#[$wire_meta:meta])* { $( $(#[$field_meta:meta])* pub $field:ident: $ty:ty, )* }) => {
112        $(#[$doc])*
113        #[derive(Debug, Clone, Serialize, PartialEq)]
114        #[serde(tag = "op", rename = $wire_name)]
115        pub struct $name {
116            $( $(#[$field_meta])* pub $field: $ty, )*
117        }
118
119        impl $name {
120            pub const OP: &'static str = $op;
121        }
122
123        impl<'de> Deserialize<'de> for $name {
124            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
125            where D: Deserializer<'de> {
126                #[derive(Deserialize)]
127                #[serde(tag = "op")]
128                $(#[$wire_meta])*
129                enum Wire {
130                    #[serde(rename = $wire_name)]
131                    Body { $( $(#[$field_meta])* $field: $ty, )* },
132                }
133                let Wire::Body { $( $field, )* } = Wire::deserialize(deserializer)?;
134                Ok(Self { $( $field, )* })
135            }
136        }
137    };
138}
139
140fn deserialize_details<'de, D>(deserializer: D) -> Result<Option<Map<String, Value>>, D::Error>
141where
142    D: Deserializer<'de>,
143{
144    Map::deserialize(deserializer).map(Some)
145}
146
147activity_body! {
148/// Report an event. Shape checking lives here; kind, size, ownership and rate
149/// validation remain the daemon's responsibility. There is no actor field.
150ActivityRecordRequest, ops::ACTIVITY_RECORD, "activity.record",
151#[serde(deny_unknown_fields)] {
152    pub kind: String,
153    pub summary: String,
154    #[serde(default, skip_serializing_if = "Option::is_none")]
155    pub subject: Option<ActivitySubject>,
156    #[serde(default, skip_serializing_if = "Option::is_none")]
157    #[serde(deserialize_with = "deserialize_details")]
158    pub details: Option<Map<String, Value>>,
159    #[serde(default, skip_serializing_if = "Option::is_none")]
160    pub on: Option<ActivityOn>,
161}
162
163}
164
165activity_body! {
166/// Sent only after the assigned sequence has been durably appended.
167ActivityRecordResponse, ops::ACTIVITY_RECORD, "activity.record", {
168    pub seq: u64,
169}
170
171}
172
173activity_body! {
174/// Filter a newest-first scan. `cursor` is exclusive: only lower seqs follow it.
175ActivityQueryRequest, ops::ACTIVITY_QUERY, "activity.query", {
176    #[serde(default, skip_serializing_if = "Option::is_none")]
177    pub agent: Option<String>,
178    #[serde(default, skip_serializing_if = "Option::is_none")]
179    pub project: Option<PathBuf>,
180    #[serde(default, skip_serializing_if = "Option::is_none")]
181    pub module: Option<String>,
182    #[serde(default, skip_serializing_if = "Option::is_none")]
183    pub kind: Option<String>,
184    #[serde(default, skip_serializing_if = "Option::is_none")]
185    pub since_ms: Option<u64>,
186    #[serde(default, skip_serializing_if = "Option::is_none")]
187    pub until_ms: Option<u64>,
188    pub limit: u32,
189    #[serde(default, skip_serializing_if = "Option::is_none")]
190    pub cursor: Option<u64>,
191}
192
193}
194
195activity_body! {
196/// A page plus the current incarnation's head at scan capture, even on an empty
197/// page. Subscribe from head to move from the scan to live entries without a gap.
198ActivityQueryResponse, ops::ACTIVITY_QUERY, "activity.query", {
199    pub entries: Vec<ActivityEntry>,
200    #[serde(default, skip_serializing_if = "Option::is_none")]
201    pub cursor: Option<u64>,
202    pub head: ActivityCursor,
203}
204
205}
206
207activity_body! {
208/// Replay after since and remain open for live entries. A refused or lagged feed
209/// ends with an Error frame carrying one of the activity refusal-code constants.
210ActivitySubscribeRequest, ops::ACTIVITY_SUBSCRIBE, "activity.subscribe", {
211    #[serde(default, skip_serializing_if = "Option::is_none")]
212    pub since: Option<ActivityCursor>,
213}
214
215}
216
217activity_body! {
218/// One successful append delivered on the subscription's correlation id. There
219/// is no separate acknowledgement; each response is one streamed entry.
220ActivitySubscribeResponse, ops::ACTIVITY_SUBSCRIBE, "activity.subscribe", {
221    pub entry: ActivityEntry,
222}
223
224}