aven_core/sync/
wire.rs

1use std::collections::HashSet;
2
3use anyhow::{Context, Result, bail};
4use serde::{Deserialize, Serialize};
5use serde_json::Value;
6
7use crate::attachments::validation::{
8    MAX_BLOB_BYTES, validate_alt_text, validate_blob_size, validate_dimensions, validate_filename,
9    validate_media_type,
10};
11use crate::change_log::op_type;
12use crate::ids::{BASE32, MetadataFieldId, ProjectId, TaskId, WorkspaceId};
13use crate::task_fields::TaskField;
14
15mod changes;
16mod recurrence;
17#[cfg(test)]
18mod test_support;
19#[cfg(test)]
20mod tests;
21
22pub const SYNC_PROTOCOL_VERSION: u32 = 18;
23const MAX_CHANGE_PAYLOAD_BYTES: usize = 64 * 1024;
24
25pub(crate) fn serialize_change_payload(payload: &Value) -> Result<String> {
26    let serialized = serde_json::to_string(payload)?;
27    if serialized.len() > MAX_CHANGE_PAYLOAD_BYTES {
28        return Err(crate::error::CoreError::validation(format!(
29            "error invalid-sync-change payload-too-large limit={MAX_CHANGE_PAYLOAD_BYTES}"
30        ))
31        .into());
32    }
33    Ok(serialized)
34}
35
36pub fn sync_server_url_is_valid(server: &str) -> bool {
37    url::Url::parse(server)
38        .as_ref()
39        .is_ok_and(sync_server_url_is_valid_url)
40}
41
42fn sync_server_url_is_valid_url(url: &url::Url) -> bool {
43    matches!(url.scheme(), "http" | "https")
44        && url.host_str().is_some()
45        && url.username().is_empty()
46        && url.password().is_none()
47        && url.query().is_none()
48        && url.fragment().is_none()
49}
50
51#[derive(Debug, Clone, Serialize, Deserialize)]
52pub struct ChangeWire {
53    pub change_id: String,
54    pub client_id: String,
55    pub local_seq: i64,
56    pub entity_type: String,
57    pub entity_id: String,
58    pub field: Option<String>,
59    pub op_type: String,
60    pub payload: Value,
61    pub base_version: Option<String>,
62    pub created_at: String,
63    pub server_seq: Option<i64>,
64}
65
66pub const MAX_MOVE_TASKS: usize = 256;
67
68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69#[serde(deny_unknown_fields)]
70pub(crate) struct MoveTaskMetadataSnapshot {
71    pub(crate) field_id: MetadataFieldId,
72    pub(crate) key: String,
73    pub(crate) value: Option<String>,
74    pub(crate) version: Option<String>,
75}
76
77#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
78#[serde(deny_unknown_fields)]
79pub(crate) struct MoveTaskSnapshot {
80    pub(crate) task_id: TaskId,
81    pub(crate) labels: Vec<String>,
82    pub(crate) metadata: Vec<MoveTaskMetadataSnapshot>,
83}
84
85#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
86#[serde(deny_unknown_fields)]
87pub(crate) struct MoveDependencySnapshot {
88    pub(crate) task_id: TaskId,
89    pub(crate) depends_on_task_id: TaskId,
90    pub(crate) created_at: String,
91}
92
93#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
94#[serde(deny_unknown_fields)]
95pub(crate) struct MoveRelatedSnapshot {
96    pub(crate) task_a_id: TaskId,
97    pub(crate) task_b_id: TaskId,
98    pub(crate) linked: bool,
99    pub(crate) last_change_id: String,
100}
101
102#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
103#[serde(deny_unknown_fields)]
104pub(crate) struct MoveEpicSnapshot {
105    pub(crate) child_task_id: TaskId,
106    pub(crate) epic_task_id: TaskId,
107    pub(crate) created_at: String,
108}
109
110#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
111#[serde(deny_unknown_fields)]
112pub(crate) struct MoveTasksPayload {
113    pub(crate) source_workspace_id: WorkspaceId,
114    pub(crate) target_workspace_id: WorkspaceId,
115    pub(crate) project_id: ProjectId,
116    pub(crate) project_key: String,
117    pub(crate) project_name: String,
118    pub(crate) project_prefix: String,
119    pub(crate) tasks: Vec<MoveTaskSnapshot>,
120    pub(crate) dependencies: Vec<MoveDependencySnapshot>,
121    pub(crate) related: Vec<MoveRelatedSnapshot>,
122    pub(crate) epics: Vec<MoveEpicSnapshot>,
123}
124
125impl MoveTasksPayload {
126    pub(crate) fn from_change(change: &ChangeWire) -> Result<Self> {
127        changes::validate_move_tasks(change)
128    }
129}
130
131#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
132pub(crate) struct AttachmentAddPayload {
133    pub(crate) workspace_id: String,
134    pub(crate) workspace_key: String,
135    pub(crate) attachment_id: String,
136    pub(crate) sha256: String,
137    pub(crate) byte_size: i64,
138    pub(crate) media_type: String,
139    pub(crate) filename: Option<String>,
140    pub(crate) alt_text: Option<String>,
141    pub(crate) width: Option<i64>,
142    pub(crate) height: Option<i64>,
143    pub(crate) created_at: String,
144}
145
146impl AttachmentAddPayload {
147    pub(crate) fn from_change(change: &ChangeWire) -> Result<Self> {
148        validate_attachment_change_envelope(change, op_type::ATTACHMENT_ADD)?;
149        required_workspace_payload(&change.payload)?;
150        let attachment_id = required_string_payload("attachment_id", &change.payload)?;
151        ensure_sync_id("attachment_id", &attachment_id)?;
152        let sha256 = required_string_payload("sha256", &change.payload)?;
153        validate_sha256_for_sync(&sha256)?;
154        let byte_size = required_i64_payload("byte_size", &change.payload)?;
155        validate_blob_size_for_sync(byte_size)?;
156        let media_type = required_string_payload("media_type", &change.payload)?;
157        map_attachment_validation(validate_media_type(&media_type))?;
158        let filename = optional_string_payload("filename", &change.payload)?;
159        map_attachment_validation(validate_filename(filename.as_deref()))?;
160        let alt_text = optional_string_payload("alt_text", &change.payload)?;
161        map_attachment_validation(validate_alt_text(alt_text.as_deref()))?;
162        let width = optional_i64_payload("width", &change.payload)?;
163        let height = optional_i64_payload("height", &change.payload)?;
164        map_attachment_validation(validate_dimensions(width, height))?;
165        required_timestamp_payload("created_at", &change.payload)?;
166        deserialize_attachment_payload(&change.payload)
167    }
168}
169
170#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
171pub(crate) struct AttachmentDeletePayload {
172    pub(crate) workspace_id: String,
173    pub(crate) workspace_key: String,
174    pub(crate) attachment_id: String,
175    pub(crate) deleted_at: String,
176}
177
178impl AttachmentDeletePayload {
179    pub(crate) fn from_change(change: &ChangeWire) -> Result<Self> {
180        validate_attachment_change_envelope(change, op_type::ATTACHMENT_DELETE)?;
181        required_workspace_payload(&change.payload)?;
182        let attachment_id = required_string_payload("attachment_id", &change.payload)?;
183        ensure_sync_id("attachment_id", &attachment_id)?;
184        required_timestamp_payload("deleted_at", &change.payload)?;
185        deserialize_attachment_payload(&change.payload)
186    }
187}
188
189fn deserialize_attachment_payload<T>(payload: &Value) -> Result<T>
190where
191    T: serde::de::DeserializeOwned,
192{
193    serde_json::from_value(payload.clone())
194        .map_err(|error| anyhow::anyhow!("error invalid-sync-change payload {error}"))
195}
196
197fn validate_attachment_change_envelope(change: &ChangeWire, expected_op_type: &str) -> Result<()> {
198    if change.op_type != expected_op_type {
199        bail!("error invalid-sync-change op_type={}", change.op_type);
200    }
201    ensure_entity_type(change, "task")?;
202    ensure_sync_id("entity_id", &change.entity_id)?;
203    if change.field.as_deref() != Some("attachments") {
204        bail!("error invalid-sync-change field=attachments");
205    }
206    if !change.payload.is_object() {
207        bail!("error invalid-sync-change payload expected-object");
208    }
209    serialize_change_payload(&change.payload)?;
210    Ok(())
211}
212
213#[cfg(any(test, feature = "test-support"))]
214pub fn validate_pushed_change(change: &ChangeWire) -> Result<()> {
215    validate_local_change_shape(change)?;
216    super::protocol::validate_change(SYNC_PROTOCOL_VERSION, change)
217}
218
219/// Largest local sequence a change may carry. Installations number their own
220/// writes upward from one and adopt the largest applied remote value, so the
221/// bound keeps every replica's next local sequence far from overflow.
222pub(crate) const MAX_LOCAL_SEQ: i64 = 1 << 53;
223
224pub(crate) fn validate_local_change_shape(change: &ChangeWire) -> Result<()> {
225    ensure_non_empty("change_id", &change.change_id)?;
226    ensure_non_empty("client_id", &change.client_id)?;
227    ensure_non_empty("entity_id", &change.entity_id)?;
228    ensure_non_empty("op_type", &change.op_type)?;
229    ensure_non_empty("entity_type", &change.entity_type)?;
230    ensure_sync_id("change_id", &change.change_id)?;
231    if change.server_seq.is_some() {
232        bail!("error invalid-sync-change server_seq client-supplied");
233    }
234    if !(0..=MAX_LOCAL_SEQ).contains(&change.local_seq) {
235        bail!("error invalid-sync-change local_seq out-of-range");
236    }
237    if !change.payload.is_object() {
238        bail!("error invalid-sync-change payload expected-object");
239    }
240    serialize_change_payload(&change.payload)?;
241
242    match change.op_type.as_str() {
243        op_type::MOVE_TASKS => {
244            changes::validate_move_tasks(change)?;
245        }
246        op_type::PUBLISH_DEVICE_LABEL => changes::validate_publish_device_label(change)?,
247        op_type::CREATE_WORKSPACE => changes::validate_create_workspace(change)?,
248        op_type::SET_WORKSPACE_FIELD => changes::validate_set_workspace_field(change)?,
249        op_type::CREATE_PROJECT => changes::validate_create_project(change)?,
250        op_type::SET_PROJECT_METADATA => changes::validate_set_project_metadata(change)?,
251        op_type::CREATE_LABEL => changes::validate_create_label(change)?,
252        op_type::CREATE_METADATA_FIELD => changes::validate_create_metadata_field(change)?,
253        op_type::SET_METADATA_FIELD => changes::validate_set_metadata_field(change)?,
254        op_type::SET_TASK_METADATA | op_type::REMOVE_TASK_METADATA => {
255            changes::validate_task_metadata(change)?
256        }
257        op_type::CREATE_TASK => changes::validate_create_task(change)?,
258        op_type::SET_FIELD | op_type::RESOLVE_FIELD => changes::validate_task_field(change)?,
259        op_type::LABEL_ADD | op_type::LABEL_REMOVE => changes::validate_label_change(change)?,
260        op_type::NOTE_ADD => changes::validate_note_add(change)?,
261        op_type::DEPENDENCY_ADD | op_type::DEPENDENCY_REMOVE => {
262            changes::validate_dependency_change(change)?
263        }
264        op_type::RELATED_ADD | op_type::RELATED_REMOVE => changes::validate_related_change(change)?,
265        op_type::EPIC_LINK_ADD | op_type::EPIC_LINK_REMOVE => {
266            changes::validate_epic_link_change(change)?
267        }
268        op_type::PROJECT_DELETE => changes::validate_project_delete(change)?,
269        op_type::SET_LABEL_NAME => changes::validate_set_label_name(change)?,
270        op_type::LABEL_DELETE => changes::validate_label_delete(change)?,
271        op_type::NOTE_EDIT => changes::validate_note_edit(change)?,
272        op_type::LABEL_RESTORE => changes::validate_label_restore(change)?,
273        op_type::NOTE_DELETE => changes::validate_note_delete(change)?,
274        op_type::SET_RECURRENCE_METADATA | op_type::REMOVE_RECURRENCE_METADATA => {
275            changes::validate_recurrence_metadata(change)?
276        }
277        op_type::CREATE_RECURRENCE_SERIES => recurrence::validate_recurrence_create(change)?,
278        op_type::UPDATE_RECURRENCE_TEMPLATE => recurrence::validate_recurrence_template(change)?,
279        op_type::PROJECT_RECURRENCE_OCCURRENCE => {
280            recurrence::validate_recurrence_projection(change)?
281        }
282        op_type::RESOLVE_RECURRENCE_OCCURRENCE => recurrence::validate_recurrence_outcome(change)?,
283        op_type::SET_RECURRENCE_STATE | op_type::STOP_RECURRENCE_SERIES => {
284            recurrence::validate_recurrence_state(change)?
285        }
286        op_type::OPEN_RECURRENCE_PAUSE => recurrence::validate_recurrence_pause(change, true)?,
287        op_type::CLOSE_RECURRENCE_PAUSE => recurrence::validate_recurrence_pause(change, false)?,
288        op_type::ATTACHMENT_ADD => {
289            AttachmentAddPayload::from_change(change)?;
290        }
291        op_type::ATTACHMENT_DELETE => {
292            AttachmentDeletePayload::from_change(change)?;
293        }
294        _ => bail!("error invalid-sync-change op_type={}", change.op_type),
295    }
296    Ok(())
297}
298
299fn validate_sha256_for_sync(value: &str) -> Result<()> {
300    if value.len() == 64
301        && value
302            .bytes()
303            .all(|byte| byte.is_ascii_digit() || matches!(byte, b'a'..=b'f'))
304    {
305        Ok(())
306    } else {
307        bail!("error invalid-sync-change invalid-sha256");
308    }
309}
310
311fn validate_blob_size_for_sync(byte_size: i64) -> Result<()> {
312    let Ok(bytes) = usize::try_from(byte_size) else {
313        bail!("error invalid-sync-change error invalid-attachment-size bytes={byte_size}");
314    };
315    if bytes == 0 || bytes > MAX_BLOB_BYTES {
316        bail!("error invalid-sync-change error invalid-attachment-size bytes={byte_size}");
317    }
318    map_attachment_validation(validate_blob_size(bytes))
319}
320
321fn map_attachment_validation(result: Result<()>) -> Result<()> {
322    result.map_err(|err| anyhow::anyhow!("error invalid-sync-change {err}"))
323}
324
325fn validate_sync_task_field_value(field: TaskField, value: &str) -> Result<()> {
326    field
327        .validate_value(value)
328        .map_err(|err| anyhow::anyhow!("error invalid-sync-change {err}"))
329}
330
331fn ensure_entity_type(change: &ChangeWire, expected: &str) -> Result<()> {
332    if change.entity_type == expected {
333        Ok(())
334    } else {
335        bail!(
336            "error invalid-sync-change op_type={} entity_type={} expected={}",
337            change.op_type,
338            change.entity_type,
339            expected
340        )
341    }
342}
343
344fn ensure_non_empty(name: &str, value: &str) -> Result<()> {
345    if value.trim().is_empty() {
346        bail!("error invalid-sync-change {name} empty");
347    }
348    Ok(())
349}
350
351fn ensure_sync_id(name: &str, value: &str) -> Result<()> {
352    if value.len() == 16 && value.bytes().all(|byte| BASE32.contains(&byte)) {
353        Ok(())
354    } else {
355        bail!("error invalid-sync-change {name} invalid-id");
356    }
357}
358
359fn ensure_project_id(name: &str, value: &str) -> Result<()> {
360    if value.parse::<ProjectId>().is_ok() {
361        Ok(())
362    } else {
363        bail!("error invalid-sync-change {name} invalid-id");
364    }
365}
366
367fn required_string_payload(key: &str, payload: &Value) -> Result<String> {
368    payload
369        .get(key)
370        .and_then(Value::as_str)
371        .map(str::to_string)
372        .with_context(|| format!("error invalid-sync-change payload.{key} missing"))
373}
374
375fn required_i64_payload(key: &str, payload: &Value) -> Result<i64> {
376    match payload.get(key) {
377        Some(Value::Number(value)) => value
378            .as_i64()
379            .with_context(|| format!("error invalid-sync-change payload.{key} invalid")),
380        Some(Value::Null) | None => bail!("error invalid-sync-change payload.{key} missing"),
381        Some(_) => bail!("error invalid-sync-change payload.{key} invalid"),
382    }
383}
384
385fn required_timestamp_payload(key: &str, payload: &Value) -> Result<String> {
386    let value = required_string_payload(key, payload)?;
387    validate_timestamp_value(&format!("payload.{key}"), &value)?;
388    Ok(value)
389}
390
391fn validate_timestamp_value(label: &str, value: &str) -> Result<()> {
392    if value.ends_with('Z') && chrono::DateTime::parse_from_rfc3339(value).is_ok() {
393        Ok(())
394    } else {
395        bail!("error invalid-sync-change {label} invalid-timestamp");
396    }
397}
398
399fn required_workspace_payload(payload: &Value) -> Result<()> {
400    let id = required_string_payload("workspace_id", payload)?;
401    if id.parse::<WorkspaceId>().is_err() {
402        bail!("error invalid-sync-change workspace_id invalid-id");
403    }
404    required_string_payload("workspace_key", payload)?;
405    Ok(())
406}
407
408fn optional_workspace_payload(payload: &Value) -> Result<()> {
409    if payload.get("workspace_id").is_none() && payload.get("workspace_key").is_none() {
410        return Ok(());
411    }
412    required_workspace_payload(payload)
413}
414
415fn optional_string_payload(key: &str, payload: &Value) -> Result<Option<String>> {
416    match payload.get(key) {
417        Some(Value::String(value)) => Ok(Some(value.clone())),
418        Some(Value::Null) | None => Ok(None),
419        Some(_) => bail!("error invalid-sync-change payload.{key} invalid"),
420    }
421}
422
423fn optional_i64_payload(key: &str, payload: &Value) -> Result<Option<i64>> {
424    match payload.get(key) {
425        Some(Value::Number(value)) => value
426            .as_i64()
427            .map(Some)
428            .with_context(|| format!("error invalid-sync-change payload.{key} invalid")),
429        Some(Value::Null) | None => Ok(None),
430        Some(_) => bail!("error invalid-sync-change payload.{key} invalid"),
431    }
432}
433
434fn optional_bool_payload(key: &str, payload: &Value) -> Result<Option<bool>> {
435    match payload.get(key) {
436        Some(Value::Bool(value)) => Ok(Some(*value)),
437        Some(Value::Null) | None => Ok(None),
438        Some(_) => bail!("error invalid-sync-change payload.{key} invalid"),
439    }
440}
441
442fn string_array_payload(key: &str, payload: &Value) -> Result<Vec<String>> {
443    payload
444        .get(key)
445        .and_then(Value::as_array)
446        .with_context(|| format!("error invalid-sync-change payload.{key} invalid"))?
447        .iter()
448        .map(|value| {
449            value
450                .as_str()
451                .map(str::to_string)
452                .with_context(|| format!("error invalid-sync-change payload.{key} invalid"))
453        })
454        .collect()
455}
456
457fn optional_string_array_payload(key: &str, payload: &Value) -> Result<()> {
458    match payload.get(key) {
459        Some(Value::Array(values))
460            if values
461                .iter()
462                .all(|value| value.as_str().is_some_and(|value| !value.trim().is_empty())) =>
463        {
464            Ok(())
465        }
466        Some(Value::Null) | None => Ok(()),
467        Some(_) => bail!("error invalid-sync-change payload.{key} invalid"),
468    }
469}
470
471fn ensure_metadata_field_id(name: &str, value: &str) -> Result<()> {
472    value
473        .parse::<MetadataFieldId>()
474        .map(|_| ())
475        .map_err(|_| anyhow::anyhow!("error invalid-sync-change {name} invalid-id"))
476}
477
478fn validate_metadata_key_payload(key: &str, payload: &Value) -> Result<String> {
479    let value = required_string_payload(key, payload)?;
480    let normalized = crate::metadata::normalize_metadata_key(&value)
481        .map_err(|_| anyhow::anyhow!("error invalid-sync-change payload.{key} invalid"))?;
482    if normalized != value {
483        bail!("error invalid-sync-change payload.{key} noncanonical");
484    }
485    Ok(value)
486}
487
488fn validate_metadata_value_payload(key: &str, payload: &Value) -> Result<String> {
489    let value = required_string_payload(key, payload)?;
490    if value.len() > crate::metadata::MAX_METADATA_VALUE_BYTES {
491        bail!("error invalid-sync-change payload.{key} too-large");
492    }
493    Ok(value)
494}
495
496fn validate_metadata_array_payload(payload: &Value) -> Result<()> {
497    let Some(values) = payload.get("metadata") else {
498        return Ok(());
499    };
500    let values = values
501        .as_array()
502        .context("error invalid-sync-change payload.metadata invalid")?;
503    if values.len() > crate::metadata::MAX_METADATA_VALUES {
504        bail!("error invalid-sync-change payload.metadata too-many");
505    }
506    let mut ids = HashSet::new();
507    let mut keys = HashSet::new();
508    let mut total_bytes = 0usize;
509    for value in values {
510        let object = value
511            .as_object()
512            .context("error invalid-sync-change payload.metadata invalid")?;
513        let field_id = required_string_payload("field_id", value)?;
514        ensure_metadata_field_id("metadata.field_id", &field_id)?;
515        let key = validate_metadata_key_payload("key", value)?;
516        let metadata_value = validate_metadata_value_payload("value", value)?;
517        if !ids.insert(field_id) || !keys.insert(key) {
518            bail!("error invalid-sync-change payload.metadata duplicate");
519        }
520        if object.len() != 3 {
521            bail!("error invalid-sync-change payload.metadata invalid");
522        }
523        total_bytes = total_bytes.saturating_add(metadata_value.len());
524    }
525    if total_bytes > crate::metadata::MAX_METADATA_TOTAL_BYTES {
526        bail!("error invalid-sync-change payload.metadata too-large");
527    }
528    Ok(())
529}
aven_core/sync/wire.rs

aven_core/sync/
wire.rs
