Skip to main content

che_rest/
sync.rs

1//! Authenticated synchronization endpoints and journal-aware ViewSet CRUD.
2use std::sync::Arc;
3
4use axum::{
5    Extension, Json,
6    http::{HeaderMap, StatusCode},
7    response::{IntoResponse, Response},
8};
9use che_orm::{
10    Model, ModelSerializer, ModelWriteSerializer, OrmError, Uuid, ValidatedWrite, WriteMode,
11};
12use che_sync::{AccessPolicy, Registry, SyncModel, SyncServer, protocol::*};
13use serde_json::{Value, json};
14
15use crate::{
16    ApiSchema, ApiSchemaDefinition, AppError, AppResult, AppState, CurrentPrincipal,
17    ExtensionContext, MutationHook, OperationSpec, Permission, RestQuerySet, ViewAction, ViewSet,
18    ViewSetExtension,
19    rest::extensions::{MutationBackend, MutationFuture},
20};
21
22pub use che_sync;
23mod objects;
24use objects::ObjectPolicyFactory;
25pub use objects::{ObjectSyncEndpoints, object_schema_module};
26
27/// Immutable HTTP request data owned by the REST adapter. This shape also reads
28/// requests submitted by earlier protocol-2 clients without re-encoding them.
29#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
30pub struct RestModelWrite {
31    pub model: String,
32    pub resource: String,
33    pub record_id: Uuid,
34    pub operation_id: Uuid,
35    pub replica_id: Uuid,
36    #[serde(with = "decimal_revision")]
37    pub base_revision: i64,
38    pub schema_version: u32,
39    pub kind: che_sync::model_log::ChangeKind,
40    pub body: Value,
41    #[serde(default)]
42    pub json_null_fields: Vec<String>,
43}
44
45mod decimal_revision {
46    use serde::{Deserialize, Deserializer, Serializer, de::Error};
47    pub fn serialize<S: Serializer>(value: &i64, serializer: S) -> Result<S::Ok, S::Error> {
48        serializer.serialize_str(&value.to_string())
49    }
50    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<i64, D::Error> {
51        #[derive(Deserialize)]
52        #[serde(untagged)]
53        enum Decimal {
54            Text(String),
55            Integer(i64),
56        }
57        match Decimal::deserialize(deserializer)? {
58            Decimal::Text(value) => value.parse().map_err(D::Error::custom),
59            Decimal::Integer(value) => Ok(value),
60        }
61    }
62}
63
64/// One immutable sync operation encoded as an ordinary serializer JSON write.
65pub struct RestSyncRequest {
66    pub method: axum::http::Method,
67    pub entity_id: Uuid,
68    pub headers: HeaderMap,
69    pub body: Value,
70}
71
72impl RestSyncRequest {
73    pub fn new<M, S>(request: PushRequest) -> Result<Self, OrmError>
74    where
75        M: SyncModel,
76        S: ModelSerializer<Model = M>,
77    {
78        if request.protocol_version != PROTOCOL_VERSION || request.operation.mutations.len() != 1 {
79            return Err(OrmError::Configuration(
80                "REST sync requires one mutation".into(),
81            ));
82        }
83        let mutation = &request.operation.mutations[0];
84        if mutation.model != M::SYNC_NAME || mutation.schema_version != M::SYNC_VERSION {
85            return Err(OrmError::Configuration("REST sync model mismatch".into()));
86        }
87        let schema = M::schema();
88        let mappings = M::registered_fields();
89        let mut body = serde_json::Map::new();
90        if let Some(changes) = &mutation.changes {
91            for (name, value) in changes {
92                let mapping = mappings
93                    .iter()
94                    .find(|field| field.name == name && field.writable)
95                    .ok_or_else(|| {
96                        OrmError::Configuration(format!("unwritable sync field {name}"))
97                    })?;
98                let column = schema
99                    .columns
100                    .iter()
101                    .find(|column| column.name == mapping.column)
102                    .unwrap();
103                let field = S::fields()
104                    .iter()
105                    .find(|field| {
106                        !field.read_only
107                            && if field.related_model.is_some() {
108                                field.source == column.name
109                            } else {
110                                field.source == column.field_name
111                            }
112                    })
113                    .ok_or_else(|| {
114                        OrmError::Configuration(format!(
115                            "sync field {name} has no writable serializer field"
116                        ))
117                    })?;
118                let value = match value {
119                    che_sync::protocol::Value::Integer(value) => json!(value.to_string()),
120                    che_sync::protocol::Value::Real(value) => json!(value),
121                    che_sync::protocol::Value::Text(value) => json!(value),
122                    che_sync::protocol::Value::Binary(value) => json!(value),
123                    che_sync::protocol::Value::Boolean(value) => json!(value),
124                    che_sync::protocol::Value::Uuid(value) => json!(value),
125                    che_sync::protocol::Value::Null => Value::Null,
126                    che_sync::protocol::Value::DateTime(value) => json!(
127                        value
128                            .format(&che_orm::time::format_description::well_known::Rfc3339)
129                            .map_err(|error| OrmError::Configuration(error.to_string()))?
130                    ),
131                };
132                body.insert(field.name.into(), value);
133            }
134        }
135        let method = if mutation.changes.is_none() {
136            axum::http::Method::DELETE
137        } else if mutation.base_revision == 0 {
138            axum::http::Method::POST
139        } else {
140            axum::http::Method::PATCH
141        };
142        let mut headers = HeaderMap::new();
143        for (name, value) in [
144            ("x-sync-protocol", request.protocol_version.to_string()),
145            ("x-sync-replica", request.replica_id.to_string()),
146            ("idempotency-key", request.operation.id.to_string()),
147            ("if-match", format!("\"{}\"", mutation.base_revision)),
148            ("x-sync-entity", mutation.id.to_string()),
149            ("x-sync-version", mutation.schema_version.to_string()),
150            ("x-sync-scope", request.scope),
151        ] {
152            headers.insert(
153                axum::http::HeaderName::from_static(name),
154                value
155                    .parse()
156                    .map_err(|_| OrmError::Configuration("invalid REST sync header".into()))?,
157            );
158        }
159        Ok(Self {
160            method,
161            entity_id: mutation.id,
162            headers,
163            body: if mutation.changes.is_none() {
164                Value::Null
165            } else {
166                Value::Object(body)
167            },
168        })
169    }
170}
171
172pub(crate) trait SyncLifecycle: Send + Sync {
173    fn path(&self) -> &'static str;
174    fn scope(&self, state: &AppState, principal: &CurrentPrincipal) -> AppResult<String>;
175    fn actions(&self) -> Vec<String>;
176    fn prepare_delete<'a>(
177        &'a self,
178        state: &'a AppState,
179        entity: &'a Entity,
180    ) -> MutationFuture<'a, std::collections::BTreeMap<String, Value>>;
181    fn model_logs(&self) -> bool;
182    fn committed(
183        &self,
184        state: &AppState,
185        principal: Option<&CurrentPrincipal>,
186        old: Option<&Entity>,
187        entity: &Entity,
188        payload: &EffectPayload,
189        action_id: &str,
190    ) -> AppResult<()>;
191}
192
193struct Lifecycle<V: SyncViewSet>
194where
195    V::Model: SyncModel,
196{
197    viewset: V,
198    hooks: Vec<Arc<dyn MutationHook<V>>>,
199    model_logs: bool,
200}
201
202fn materialize<M: SyncModel>(entity: &Entity) -> AppResult<M> {
203    let record = entity.record.as_ref().ok_or(AppError::NotFound)?;
204    let fields = M::registered_fields();
205    let values = M::schema()
206        .columns
207        .iter()
208        .map(|column| {
209            let field = fields
210                .iter()
211                .find(|field| field.column == column.name)
212                .ok_or_else(|| AppError::BadRequest("unmapped sync column".into()))?;
213            let value = record
214                .get(field.name)
215                .ok_or_else(|| AppError::BadRequest("incomplete canonical record".into()))?;
216            Ok(database_value(value))
217        })
218        .collect::<AppResult<Vec<_>>>()?;
219    M::from_row(&che_orm::Row::new(values)).map_err(|e| AppError::Orm(e.into()))
220}
221
222impl<V: SyncViewSet> SyncLifecycle for Lifecycle<V>
223where
224    V::Model: SyncModel,
225{
226    fn path(&self) -> &'static str {
227        self.viewset.path()
228    }
229    fn scope(&self, state: &AppState, principal: &CurrentPrincipal) -> AppResult<String> {
230        if self.model_logs {
231            Ok(che_sync::model_log::MODEL_LOG_SCOPE.into())
232        } else {
233            self.viewset.sync_scope(state, principal)
234        }
235    }
236    fn actions(&self) -> Vec<String> {
237        self.hooks
238            .iter()
239            .filter(|hook| hook.backend().is_none())
240            .map(|hook| hook.id().to_owned())
241            .chain(std::iter::once("@signal".into()))
242            .collect()
243    }
244    fn model_logs(&self) -> bool {
245        self.model_logs
246    }
247    fn prepare_delete<'a>(
248        &'a self,
249        state: &'a AppState,
250        entity: &'a Entity,
251    ) -> MutationFuture<'a, std::collections::BTreeMap<String, Value>> {
252        Box::pin(async move {
253            let model = materialize::<V::Model>(entity)?;
254            let mut values = std::collections::BTreeMap::new();
255            for hook in &self.hooks {
256                values.insert(
257                    hook.id().into(),
258                    hook.prepare_delete_async(state, &model).await?,
259                );
260            }
261            Ok(values)
262        })
263    }
264    fn committed(
265        &self,
266        state: &AppState,
267        principal: Option<&CurrentPrincipal>,
268        old: Option<&Entity>,
269        entity: &Entity,
270        payload: &EffectPayload,
271        action_id: &str,
272    ) -> AppResult<()> {
273        let (payload, write_action) = match payload {
274            EffectPayload::Handler {
275                version: 2,
276                value,
277                action,
278            } => (value.as_ref(), *action),
279            EffectPayload::Handler { .. } => {
280                return Err(AppError::BadRequest(
281                    "unsupported effect payload version".into(),
282                ));
283            }
284            EffectPayload::Current {
285                values: Some(_), ..
286            }
287            | EffectPayload::Legacy(Some(_)) => {
288                return Err(AppError::BadRequest(
289                    "legacy positional cleanup requires explicit payload migration".into(),
290                ));
291            }
292            EffectPayload::Current {
293                values: None,
294                action,
295            } => (None, *action),
296            EffectPayload::Legacy(None) => (None, None),
297        };
298        if action_id != "@signal" && !self.hooks.iter().any(|hook| hook.id() == action_id) {
299            return Err(AppError::BadRequest(format!(
300                "effect handler {action_id} is not installed"
301            )));
302        }
303        let action = if entity.record.is_none() {
304            {
305                let payload = payload.unwrap_or(&Value::Null);
306                for hook in &self.hooks {
307                    if hook.id() == action_id {
308                        hook.after_delete(state, payload)?;
309                    }
310                }
311            }
312            crate::ViewAction::Delete
313        } else {
314            let model = materialize::<V::Model>(entity)?;
315            let action = if let Some(action) = write_action {
316                action
317            } else if old.is_none_or(|old| old.revision == 0) {
318                crate::ViewAction::Create
319            } else {
320                crate::ViewAction::Patch
321            };
322            for hook in &self.hooks {
323                if hook.id() == action_id {
324                    hook.after_commit(state, principal, action, &model)?;
325                }
326            }
327            action
328        };
329        if action_id == "@signal"
330            && self.viewset.signal_access(action).is_some()
331            && let Some(signal) = self.viewset.signal_name(action)
332        {
333            state.signals().publish(signal, json!({"id": entity.id}));
334        }
335        Ok(())
336    }
337}
338
339/// Each ViewSet serves its model and automatically includes its FK parents.
340/// The registry describes the related models needed for dependency/cascade
341/// capture; it does not combine their outgoing queues or cursors.
342/// Scope and principal are derived from authenticated context, never JSON.
343/// Ordinary reads must use a queryset/permission matching the same access rules.
344pub trait SyncViewSet: ViewSet
345where
346    Self::Model: SyncModel,
347{
348    fn sync_registry(&self) -> AppResult<Registry>;
349    fn sync_scope(&self, _state: &AppState, _principal: &CurrentPrincipal) -> AppResult<String> {
350        Ok(che_sync::model_log::MODEL_LOG_SCOPE.into())
351    }
352    fn sync_policy(&self) -> Arc<dyn AccessPolicy> {
353        Arc::new(che_sync::AllowAll)
354    }
355}
356
357/// Install in `ViewSet::configure`. Also replaces CRUD persistence so changes
358/// and the sync journal commit atomically. Sync tables must already be migrated.
359#[derive(Clone)]
360pub struct SyncEndpoints<V> {
361    viewset: V,
362    body_limit: usize,
363    model_logs: bool,
364    object_access: Option<ObjectPolicyFactory>,
365}
366
367impl<V> SyncEndpoints<V> {
368    pub fn new(viewset: V) -> Self {
369        Self {
370            viewset,
371            body_limit: 2 * 1024 * 1024,
372            model_logs: false,
373            object_access: None,
374        }
375    }
376
377    pub fn body_limit(mut self, bytes: usize) -> Self {
378        self.body_limit = bytes;
379        self
380    }
381}
382
383/// Whole-model synchronization through ordinary REST writes and a dedicated
384/// per-model GET journal. No workspace or scope header is accepted/required.
385#[derive(Clone)]
386pub struct ModelSyncEndpoints<V>(SyncEndpoints<V>);
387impl<V> ModelSyncEndpoints<V> {
388    pub fn new(viewset: V) -> Self {
389        let mut endpoints = SyncEndpoints::new(viewset);
390        endpoints.model_logs = true;
391        Self(endpoints)
392    }
393}
394impl<V: SyncViewSet> ViewSetExtension<V> for ModelSyncEndpoints<V>
395where
396    V::Model: SyncModel,
397{
398    const ID: &'static str = "model-sync";
399    fn install(self, context: &mut ExtensionContext<'_, V>) -> AppResult<()> {
400        self.0.install(context)
401    }
402}
403
404async fn server<V: SyncViewSet>(
405    viewset: &V,
406    state: &AppState,
407    principal: Option<&CurrentPrincipal>,
408) -> AppResult<SyncServer>
409where
410    V::Model: SyncModel,
411{
412    server_for(viewset, state, principal, false).await
413}
414
415/// Image adapters use this handle for ordinary CAS writes; they never accept
416/// client sync payloads or bypass the image action's own authorization.
417pub(crate) async fn model_media_state<V: SyncViewSet>(
418    viewset: &V,
419    state: &AppState,
420    principal: Option<&CurrentPrincipal>,
421) -> AppResult<AppState>
422where
423    V::Model: SyncModel,
424{
425    let server = server_for(viewset, state, principal, true).await?;
426    Ok(state.clone().with_database(server.database().clone()))
427}
428
429async fn server_for<V: SyncViewSet>(
430    viewset: &V,
431    state: &AppState,
432    principal: Option<&CurrentPrincipal>,
433    model_logs: bool,
434) -> AppResult<SyncServer>
435where
436    V::Model: SyncModel,
437{
438    server_with_objects(viewset, state, principal, model_logs, None).await
439}
440async fn server_with_objects<V: SyncViewSet>(
441    viewset: &V,
442    state: &AppState,
443    principal: Option<&CurrentPrincipal>,
444    model_logs: bool,
445    objects: Option<&ObjectPolicyFactory>,
446) -> AppResult<SyncServer>
447where
448    V::Model: SyncModel,
449{
450    let principal =
451        principal.ok_or_else(|| AppError::Unauthorized("authentication required".into()))?;
452    let scope = if model_logs {
453        che_sync::model_log::MODEL_LOG_SCOPE.into()
454    } else {
455        viewset.sync_scope(state, principal)?
456    };
457    let identity = principal.auth_user().id.to_string();
458    let policy = match objects {
459        Some(factory) => (factory)(state.clone(), principal.clone())?.0,
460        None => viewset.sync_policy(),
461    };
462    policy
463        .authorize_scope(&identity, &scope)
464        .map_err(|error| match error {
465            OrmError::Configuration(reason) => AppError::Forbidden(reason),
466            other => AppError::Orm(other),
467        })?;
468    let server = if model_logs {
469        SyncServer::open_model_logs(
470            state.database().clone(),
471            viewset.sync_registry()?,
472            identity,
473            policy,
474        )
475        .await
476    } else {
477        SyncServer::open(
478            state.database().clone(),
479            viewset.sync_registry()?,
480            scope,
481            identity,
482            policy,
483        )
484        .await
485    };
486    server
487        .map_err(sync_error)?
488        .for_model::<V::Model>()
489        .map_err(sync_error)
490}
491
492fn sync_error(error: OrmError) -> AppError {
493    match error {
494        OrmError::Configuration(reason) => AppError::BadRequest(reason),
495        OrmError::QueryBuild(error) => AppError::BadRequest(format!("{error:?}")),
496        other => AppError::Orm(other),
497    }
498}
499
500impl<V: SyncViewSet> ViewSetExtension<V> for SyncEndpoints<V>
501where
502    V::Model: SyncModel,
503{
504    const ID: &'static str = "sync";
505
506    fn install(self, context: &mut ExtensionContext<'_, V>) -> AppResult<()> {
507        if V::Permission::default().object_scoped() && self.object_access.is_none() {
508            return Err(AppError::BadRequest("object permissions require an object-delivery sync protocol; existing sync endpoints expose whole-model data".into()));
509        }
510        if self.body_limit == 0 {
511            return Err(AppError::BadRequest(
512                "sync body limit must be positive".into(),
513            ));
514        }
515        self.viewset.sync_registry()?.check_model::<V::Model>()?;
516        let sync_fields = V::Model::registered_fields();
517        for field in V::Serializer::fields()
518            .iter()
519            .filter(|field| !field.read_only)
520        {
521            let schema = V::Model::schema();
522            let column = schema.columns.iter().find(|column| {
523                if field.related_model.is_some() {
524                    column.name == field.source
525                } else {
526                    column.field_name == field.source
527                }
528            });
529            if let Some(column) = column
530                && sync_fields
531                    .iter()
532                    .any(|sync| sync.column == column.name && !sync.writable)
533            {
534                return Err(AppError::BadRequest(format!(
535                    "serializer field {} must be read-only: its sync column is server-owned",
536                    field.name
537                )));
538            }
539        }
540        let schema = V::Model::schema();
541        for sync in sync_fields.iter().filter(|field| field.writable) {
542            let column = schema
543                .columns
544                .iter()
545                .find(|column| column.name == sync.column)
546                .ok_or_else(|| {
547                    AppError::BadRequest(format!("unknown sync column {}", sync.column))
548                })?;
549            let mappings = V::Serializer::fields()
550                .iter()
551                .filter(|field| {
552                    !field.read_only
553                        && if field.related_model.is_some() {
554                            field.source == column.name
555                        } else {
556                            field.source == column.field_name
557                        }
558                })
559                .count();
560            if mappings != 1 {
561                return Err(AppError::BadRequest(format!(
562                    "sync model {} field {} requires exactly one writable serializer mapping (found {mappings})",
563                    V::Model::SYNC_NAME,
564                    sync.name,
565                )));
566            }
567        }
568        let prefix = self.viewset.path().trim_matches('/').replace('/', "_");
569        if self.object_access.is_some() {
570            objects::install_route(&self, context)?;
571            return context.mutation_hook(self);
572        }
573        if self.model_logs {
574            context.route("sync/changes", |route| {
575                route.get(
576                    model_changes::<V>,
577                    OperationSpec::new(format!("{prefix}_sync_changes"))
578                        .authenticated()
579                        .response::<che_sync::protocol::model_log::ModelChanges>(StatusCode::OK)
580                        .client("sync", "changes"),
581                )
582            })?;
583            return context.mutation_hook(self);
584        }
585        let spec = |action: &str| {
586            OperationSpec::new(format!("{prefix}_sync_{action}"))
587                .authenticated()
588                .body_limit(self.body_limit)
589                .error(StatusCode::BAD_REQUEST)
590                .error(StatusCode::UNAUTHORIZED)
591                .error(StatusCode::FORBIDDEN)
592        };
593        context.route("sync/pull", |route| {
594            route.post(
595                pull::<V>,
596                spec("pull")
597                    .client("sync", "pull")
598                    .request::<PullRequest>()
599                    .response::<PullResult>(StatusCode::OK),
600            )
601        })?;
602        context.route("sync/snapshot", |route| {
603            route.get(
604                snapshot::<V>,
605                spec("snapshot")
606                    .client("sync", "snapshot")
607                    .response::<Snapshot>(StatusCode::OK),
608            )
609        })?;
610        context.mutation_hook(self)
611    }
612}
613
614async fn commit_rest<V: SyncViewSet>(
615    state: &AppState,
616    viewset: &V,
617    principal: &CurrentPrincipal,
618    server: &SyncServer,
619    request: PushRequest,
620    identity: String,
621    action: ViewAction,
622) -> AppResult<PushResult>
623where
624    V::Model: SyncModel,
625{
626    let registry = viewset.sync_registry()?;
627    let before = server.prepare_push(&request).await.map_err(sync_error)?;
628    let handlers = state
629        .sync_lifecycle
630        .read()
631        .expect("sync lifecycle lock")
632        .clone();
633    let mut prepared = Vec::new();
634    for entity in registry.deleted_in_operation(&before, &request.operation)? {
635        if let Some(lifecycles) = handlers.get(&entity.model) {
636            for lifecycle in lifecycles {
637                if lifecycle.scope(state, principal)? == request.scope {
638                    let values = lifecycle.prepare_delete(state, &entity).await?;
639                    prepared.push((entity.model.clone(), entity.id, lifecycle.clone(), values));
640                }
641            }
642        }
643    }
644    let scope = request.scope.clone();
645    let mut effects = Vec::new();
646    for entity in &before {
647        if let Some(lifecycles) = handlers.get(&entity.model) {
648            for lifecycle in lifecycles {
649                if lifecycle.scope(state, principal)? != scope {
650                    continue;
651                }
652                let values = prepared
653                    .iter()
654                    .find(|(model, id, handler, _)| {
655                        model == &entity.model
656                            && *id == entity.id
657                            && Arc::ptr_eq(handler, lifecycle)
658                    })
659                    .map(|(_, _, _, values)| values);
660                for effect_action in lifecycle.actions() {
661                    effects.push(che_sync::PreparedEffect {
662                        model: entity.model.clone(),
663                        entity_id: entity.id,
664                        handler: lifecycle.path().into(),
665                        action: effect_action.clone(),
666                        payload: serde_json::to_string(&EffectPayload::Handler {
667                            version: 2,
668                            value: values
669                                .and_then(|values| values.get(&effect_action))
670                                .cloned(),
671                            action: (entity.model == V::Model::SYNC_NAME
672                                && lifecycle.path() == viewset.path())
673                            .then_some(action),
674                        })?,
675                    });
676                }
677            }
678        }
679    }
680    let result = server
681        .write_prepared_request(request, before.clone(), effects, identity)
682        .await
683        .map_err(sync_error)?;
684    retry_effects(state, principal, server, &scope).await;
685    Ok(result)
686}
687
688// Read the legacy payload shape too: pending effects survive upgrades.
689#[derive(serde::Serialize, serde::Deserialize)]
690#[serde(untagged)]
691pub(crate) enum EffectPayload {
692    Handler {
693        version: u32,
694        value: Option<Value>,
695        action: Option<ViewAction>,
696    },
697    Current {
698        values: Option<Vec<Value>>,
699        action: Option<ViewAction>,
700    },
701    Legacy(Option<Vec<Value>>),
702}
703
704/// Retry all per-model effects from a trusted background worker, including
705/// effects whose initiating user no longer sends requests. Handler callbacks
706/// receive no live authentication credential; persisted payloads own context.
707pub async fn retry_model_effects(state: &AppState) -> AppResult<usize> {
708    let _guard = state.sync_effects_lock.lock().await;
709    let handlers = state
710        .sync_lifecycle
711        .read()
712        .expect("sync lifecycle lock")
713        .clone();
714    let rows = state
715        .database()
716        .query_sql(
717            "SELECT id, payload FROM _sync_effects WHERE scope = $1 ORDER BY id",
718            vec![che_orm::DatabaseValue::Text(
719                che_sync::model_log::MODEL_LOG_SCOPE.into(),
720            )],
721        )
722        .await?;
723    let mut completed = 0;
724    for row in rows {
725        let result = async {
726            let effect: che_sync::PostCommitEffect = serde_json::from_str(
727                &row.get::<String>(1)
728                    .map_err(|error| AppError::Orm(error.into()))?,
729            )?;
730            let handler = handlers
731                .get(&effect.entity.model)
732                .and_then(|handlers| {
733                    handlers.iter().find(|handler| {
734                        handler.model_logs() && handler.path() == effect.prepared.handler
735                    })
736                })
737                .ok_or_else(|| AppError::BadRequest("effect handler is not installed".into()))?;
738            let payload = serde_json::from_str(&effect.prepared.payload)?;
739            handler.committed(
740                state,
741                None,
742                effect.previous.as_ref(),
743                &effect.entity,
744                &payload,
745                &effect.prepared.action,
746            )?;
747            state
748                .database()
749                .execute_sql(
750                    "DELETE FROM _sync_effects WHERE id = $1 AND scope = $2",
751                    vec![
752                        che_orm::DatabaseValue::Text(effect.id.to_string()),
753                        che_orm::DatabaseValue::Text(che_sync::model_log::MODEL_LOG_SCOPE.into()),
754                    ],
755                )
756                .await?;
757            Ok::<_, AppError>(())
758        }
759        .await;
760        match result {
761            Ok(()) => completed += 1,
762            Err(error) => eprintln!("model effect deferred: {error}"),
763        }
764    }
765    Ok(completed)
766}
767
768async fn retry_effects(
769    state: &AppState,
770    principal: &CurrentPrincipal,
771    server: &SyncServer,
772    scope: &str,
773) {
774    if let Err(error) = flush_effects(state, principal, server, scope).await {
775        eprintln!("sync effects deferred: {error}");
776    }
777}
778
779async fn flush_effects(
780    state: &AppState,
781    principal: &CurrentPrincipal,
782    server: &SyncServer,
783    scope: &str,
784) -> AppResult<()> {
785    let handlers = state
786        .sync_lifecycle
787        .read()
788        .expect("sync lifecycle lock")
789        .clone();
790    let _effects_guard = state.sync_effects_lock.lock().await;
791    for effect in server.pending_effects().await? {
792        if let Some(lifecycle) = handlers.get(&effect.entity.model).and_then(|handlers| {
793            handlers
794                .iter()
795                .find(|handler| handler.path() == effect.prepared.handler)
796        }) {
797            let result = async {
798                if lifecycle.scope(state, principal)? != scope {
799                    return Ok(());
800                }
801                let payload = serde_json::from_str::<EffectPayload>(&effect.prepared.payload)?;
802                lifecycle.committed(
803                    state,
804                    Some(principal),
805                    effect.previous.as_ref(),
806                    &effect.entity,
807                    &payload,
808                    &effect.prepared.action,
809                )?;
810                server.acknowledge_effect(effect.id).await?;
811                Ok::<_, AppError>(())
812            }
813            .await;
814            if let Err(error) = result {
815                eprintln!("sync effect {} deferred: {error}", effect.id);
816            }
817        }
818    }
819    Ok(())
820}
821
822async fn pull<V: SyncViewSet>(
823    Extension(state): Extension<AppState>,
824    Extension(viewset): Extension<V>,
825    who: Option<Extension<CurrentPrincipal>>,
826    Json(request): Json<PullRequest>,
827) -> AppResult<Json<PullResult>>
828where
829    V::Model: SyncModel,
830{
831    let server = server(&viewset, &state, who.as_ref().map(|p| &p.0)).await?;
832    Ok(Json(server.pull(request).await.map_err(sync_error)?))
833}
834
835async fn snapshot<V: SyncViewSet>(
836    Extension(state): Extension<AppState>,
837    Extension(viewset): Extension<V>,
838    who: Option<Extension<CurrentPrincipal>>,
839) -> AppResult<Json<Snapshot>>
840where
841    V::Model: SyncModel,
842{
843    let server = server(&viewset, &state, who.as_ref().map(|p| &p.0)).await?;
844    Ok(Json(server.snapshot().await.map_err(sync_error)?))
845}
846
847async fn model_changes<V: SyncViewSet>(
848    Extension(state): Extension<AppState>,
849    Extension(viewset): Extension<V>,
850    who: Option<Extension<CurrentPrincipal>>,
851    axum::extract::Query(params): axum::extract::Query<std::collections::HashMap<String, String>>,
852) -> AppResult<Json<che_sync::protocol::model_log::ModelChanges>>
853where
854    V::Model: SyncModel,
855{
856    let principal = who.as_ref().map(|who| &who.0);
857    V::Permission::default()
858        .check_request((&state).into(), principal, ViewAction::List)
859        .await?;
860    let after = params
861        .get("after")
862        .map_or("0", String::as_str)
863        .parse()
864        .map_err(|_| AppError::BadRequest("invalid model cursor".into()))?;
865    let limit = params
866        .get("limit")
867        .map_or("100", String::as_str)
868        .parse()
869        .map_err(|_| AppError::BadRequest("invalid page limit".into()))?;
870    let server = server_for(&viewset, &state, principal, true).await?;
871    Ok(Json(
872        server
873            .changes::<V::Model>(after, limit)
874            .await
875            .map_err(sync_error)?,
876    ))
877}
878
879fn write_response<V: SyncViewSet>(
880    viewset: &V,
881    result: PushResult,
882    action: ViewAction,
883    model_logs: bool,
884) -> AppResult<Response>
885where
886    V::Model: SyncModel,
887{
888    if !model_logs {
889        return Ok(rest_response(result, action, V::Model::SYNC_NAME));
890    }
891    let status = match &result {
892        PushResult::Accepted(_) if action == ViewAction::Create => StatusCode::CREATED,
893        PushResult::Accepted(_) => StatusCode::OK,
894        PushResult::Conflict(_) => StatusCode::PRECONDITION_FAILED,
895        PushResult::Rejected { .. } => StatusCode::BAD_REQUEST,
896    };
897    let revision = match &result {
898        PushResult::Accepted(entities) => entities
899            .iter()
900            .find(|entity| entity.model == V::Model::SYNC_NAME)
901            .map(|entity| entity.revision),
902        _ => None,
903    };
904    let result = viewset
905        .sync_registry()?
906        .model_result(result)
907        .map_err(sync_error)?;
908    let mut response = (status, Json(result)).into_response();
909    response.headers_mut().insert(
910        "content-type",
911        "application/vnd.che-sync.v2+json".parse().unwrap(),
912    );
913    if let Some(revision) = revision {
914        response
915            .headers_mut()
916            .insert("etag", format!("\"{revision}\"").parse().unwrap());
917    }
918    Ok(response)
919}
920
921impl<V: SyncViewSet> MutationHook<V> for SyncEndpoints<V>
922where
923    V::Model: SyncModel,
924{
925    fn id(&self) -> &'static str {
926        "sync"
927    }
928    fn installed(&self, state: &AppState, viewset: &V, hooks: &[Arc<dyn MutationHook<V>>]) {
929        let mut handlers = state.sync_lifecycle.write().expect("sync lifecycle lock");
930        let handlers = handlers.entry(V::Model::SYNC_NAME.into()).or_default();
931        handlers.retain(|handler| handler.path() != viewset.path());
932        handlers.push(Arc::new(Lifecycle {
933            viewset: viewset.clone(),
934            hooks: hooks.to_vec(),
935            model_logs: self.model_logs,
936        }));
937    }
938    fn backend(&self) -> Option<&dyn MutationBackend<V>> {
939        Some(self)
940    }
941}
942
943fn accepted(result: PushResult) -> AppResult<Vec<Entity>> {
944    match result {
945        PushResult::Accepted(entities) => Ok(entities),
946        PushResult::Conflict(_) => Err(AppError::Conflict(
947            "concurrent sync write; retry with fresh state".into(),
948        )),
949        PushResult::Rejected { reason } => Err(AppError::BadRequest(reason)),
950    }
951}
952
953impl<V: SyncViewSet> MutationBackend<V> for SyncEndpoints<V>
954where
955    V::Model: SyncModel,
956{
957    fn object_permissions(&self) -> bool {
958        self.object_access.is_some()
959    }
960    fn filter_read(&self, queryset: V::QuerySet) -> V::QuerySet {
961        if self.model_logs {
962            queryset.filter(
963                che_orm::ModelField::<V::Model, Option<che_orm::time::OffsetDateTime>>::new(
964                    V::Model::table_name(),
965                    V::Model::DELETED_AT_COLUMN,
966                )
967                .is_null(),
968            )
969        } else {
970            queryset
971        }
972    }
973    fn rest<'a>(
974        &'a self,
975        state: &'a AppState,
976        principal: Option<&'a CurrentPrincipal>,
977        action: ViewAction,
978        path_id: Option<Uuid>,
979        headers: &'a HeaderMap,
980        mut data: Value,
981    ) -> MutationFuture<'a, Option<Response>> {
982        Box::pin(async move {
983            let conditional = [
984                "x-sync-replica",
985                "idempotency-key",
986                "if-match",
987                "x-sync-protocol",
988                "x-sync-version",
989                "x-sync-scope",
990                "x-sync-entity",
991            ]
992            .iter()
993            .any(|name| headers.contains_key(*name));
994            let header = |name: &str| -> AppResult<&str> {
995                headers
996                    .get(name)
997                    .and_then(|v| v.to_str().ok())
998                    .ok_or_else(|| AppError::BadRequest(format!("missing or invalid {name}")))
999            };
1000            let replica: Uuid = if conditional {
1001                header("x-sync-replica")?
1002                    .parse()
1003                    .map_err(|_| AppError::BadRequest("invalid replica UUID".into()))?
1004            } else {
1005                Uuid::nil()
1006            };
1007            let operation: Uuid = if conditional {
1008                header("idempotency-key")?
1009                    .parse()
1010                    .map_err(|_| AppError::BadRequest("invalid operation UUID".into()))?
1011            } else {
1012                Uuid::now_v7()
1013            };
1014            let version: u32 = if conditional {
1015                header("x-sync-version")?
1016                    .parse()
1017                    .map_err(|_| AppError::BadRequest("invalid sync version".into()))?
1018            } else {
1019                V::Model::SYNC_VERSION
1020            };
1021            let expected_protocol = if self.object_access.is_some() {
1022                3
1023            } else if self.model_logs {
1024                che_sync::protocol::model_log::MODEL_LOG_PROTOCOL
1025            } else {
1026                PROTOCOL_VERSION
1027            };
1028            if conditional && header("x-sync-protocol")? != expected_protocol.to_string() {
1029                return Err(AppError::BadRequest("incompatible sync protocol".into()));
1030            }
1031            if version != V::Model::SYNC_VERSION {
1032                return Err(AppError::BadRequest("incompatible model version".into()));
1033            }
1034            let revision: i64 = if conditional {
1035                header("if-match")?
1036                    .strip_prefix('"')
1037                    .and_then(|v| v.strip_suffix('"'))
1038                    .and_then(|v| v.parse().ok())
1039                    .filter(|v| *v >= 0)
1040                    .ok_or_else(|| {
1041                        AppError::BadRequest(
1042                            "If-Match must be a quoted nonnegative revision".into(),
1043                        )
1044                    })?
1045            } else {
1046                0
1047            };
1048            let mut id = match path_id {
1049                Some(id) => id,
1050                None if conditional => header("x-sync-entity")?
1051                    .parse()
1052                    .map_err(|_| AppError::BadRequest("invalid offline entity UUID".into()))?,
1053                None => Uuid::now_v7(),
1054            };
1055            if action == ViewAction::Create && revision != 0 {
1056                return Err(AppError::BadRequest("create requires revision zero".into()));
1057            }
1058            let principal = principal
1059                .ok_or_else(|| AppError::Unauthorized("authentication required".into()))?;
1060            if self.object_access.is_none() {
1061                V::Permission::default()
1062                    .check_request(state.into(), Some(principal), action)
1063                    .await?;
1064            }
1065            let scope = if self.model_logs {
1066                che_sync::model_log::MODEL_LOG_SCOPE.into()
1067            } else {
1068                self.viewset.sync_scope(state, principal)?
1069            };
1070            if conditional && !self.model_logs && header("x-sync-scope")? != scope {
1071                return Err(AppError::BadRequest("sync scope mismatch".into()));
1072            }
1073            let server = server_with_objects(
1074                &self.viewset,
1075                state,
1076                Some(principal),
1077                self.model_logs,
1078                self.object_access.as_ref(),
1079            )
1080            .await?;
1081            let json_null_fields: Vec<String> =
1082                if self.model_logs {
1083                    match headers.get("x-sync-json-null-fields") {
1084                        Some(value) => serde_json::from_str(value.to_str().map_err(|_| {
1085                            AppError::BadRequest("invalid JSON null fields".into())
1086                        })?)
1087                        .map_err(|_| AppError::BadRequest("invalid JSON null fields".into()))?,
1088                        None => vec![],
1089                    }
1090                } else {
1091                    vec![]
1092                };
1093            let identity_body = if self.model_logs {
1094                json!({"body": &data, "json_null_fields": &json_null_fields})
1095            } else {
1096                data.clone()
1097            };
1098            let identity = serde_json::to_string(&(
1099                V::Model::SYNC_NAME,
1100                format!("{action:?}"),
1101                id,
1102                revision,
1103                version,
1104                &identity_body,
1105            ))?;
1106            if let Some(result) = server
1107                .request_receipt(replica, operation, &identity)
1108                .await
1109                .map_err(sync_error)?
1110            {
1111                retry_effects(state, principal, &server, &scope).await;
1112                return Ok(Some(
1113                    objects::response(
1114                        &self.viewset,
1115                        result,
1116                        action,
1117                        self.model_logs,
1118                        self.object_access.as_ref(),
1119                        state,
1120                        principal,
1121                        &server,
1122                        operation,
1123                    )
1124                    .await?,
1125                ));
1126            }
1127            let outcome = async {
1128                V::Permission::default()
1129                    .check_request(state.into(), Some(principal), action)
1130                    .await?;
1131                let mut request = PushRequest {
1132                    protocol_version: PROTOCOL_VERSION,
1133                    scope: scope.clone(),
1134                    replica_id: replica,
1135                    operation: Operation {
1136                        id: operation,
1137                        mutations: vec![Mutation {
1138                            model: V::Model::SYNC_NAME.into(),
1139                            id,
1140                            schema_version: version,
1141                            base_revision: revision,
1142                            changes: if action == ViewAction::Delete {
1143                                None
1144                            } else {
1145                                Some(Record::new())
1146                            },
1147                        }],
1148                    },
1149                };
1150                let before = server.prepare_push(&request).await.map_err(sync_error)?;
1151                let current = before
1152                    .iter()
1153                    .find(|entity| entity.model == V::Model::SYNC_NAME && entity.id == id)
1154                    .expect("prepared root");
1155                let revision = if conditional {
1156                    revision
1157                } else if action == ViewAction::Create {
1158                    0
1159                } else {
1160                    current.revision
1161                };
1162                request.operation.mutations[0].base_revision = revision;
1163                let item = if action != ViewAction::Create && current.record.is_some() {
1164                    let item = self
1165                        .viewset
1166                        .get_queryset()
1167                        .filter(V::Model::primary_key().eq(id))
1168                        .first(state.database())
1169                        .await?
1170                        .ok_or(AppError::NotFound)?;
1171                    V::Permission::default()
1172                        .check_object(
1173                            state.into(),
1174                            Some(principal),
1175                            action,
1176                            V::QuerySet::item_model(&item),
1177                        )
1178                        .await?;
1179                    Some(materialize::<V::Model>(current)?)
1180                } else {
1181                    None
1182                };
1183                if current.revision != revision
1184                    || (action != ViewAction::Create && current.record.is_none())
1185                {
1186                    if !conditional {
1187                        return Err(AppError::NotFound);
1188                    }
1189                    return Ok(Some(
1190                        objects::response(
1191                            &self.viewset,
1192                            PushResult::Conflict(vec![current.clone()]),
1193                            action,
1194                            self.model_logs,
1195                            self.object_access.as_ref(),
1196                            state,
1197                            principal,
1198                            &server,
1199                            operation,
1200                        )
1201                        .await?,
1202                    ));
1203                }
1204                if action != ViewAction::Delete {
1205                    let mut json_null_mappings = Vec::new();
1206                    for name in &json_null_fields {
1207                        let field = V::Serializer::fields()
1208                            .iter()
1209                            .find(|field| field.name == name && !field.read_only)
1210                            .ok_or_else(|| {
1211                                AppError::BadRequest("unknown writable JSON null field".into())
1212                            })?;
1213                        let schema = V::Model::schema();
1214                        let column = schema
1215                            .columns
1216                            .iter()
1217                            .find(|column| column.field_name == field.source)
1218                            .filter(|column| V::Model::json_columns().contains(&column.name))
1219                            .ok_or_else(|| {
1220                                AppError::BadRequest(
1221                                    "JSON null marker requires a JSON field".into(),
1222                                )
1223                            })?;
1224                        if data.get(name).is_none_or(|value| !value.is_null())
1225                            || json_null_mappings
1226                                .iter()
1227                                .any(|(existing, _)| existing == name)
1228                        {
1229                            return Err(AppError::BadRequest(
1230                                "JSON null marker must name an explicit null exactly once".into(),
1231                            ));
1232                        }
1233                        let wire = V::Model::registered_fields()
1234                            .into_iter()
1235                            .find(|mapping| mapping.column == column.name && mapping.writable)
1236                            .ok_or_else(|| {
1237                                AppError::BadRequest("JSON null field is server-owned".into())
1238                            })?;
1239                        json_null_mappings.push((name.clone(), wire.name));
1240                    }
1241                    crate::rest::router::normalize_datetime_fields(
1242                        &mut data,
1243                        V::Serializer::fields(),
1244                    );
1245                    // Sync JSON uses decimal strings for i64; turn them into exact
1246                    // serde_json integers before invoking the ordinary serializer.
1247                    if conditional && let Some(values) = data.as_object_mut() {
1248                        let schema = V::Model::schema();
1249                        for field in V::Serializer::fields() {
1250                            let column = schema.columns.iter().find(|column| {
1251                                if field.related_model.is_some() {
1252                                    column.name == field.source
1253                                } else {
1254                                    column.field_name == field.source
1255                                }
1256                            });
1257                            if column.is_some_and(|column| {
1258                                column.column_type == che_orm::ColumnType::Integer
1259                            }) && let Some(Value::String(decimal)) = values.get(field.name)
1260                            {
1261                                let integer = decimal.parse::<i64>().map_err(|_| {
1262                                    AppError::BadRequest(format!("invalid i64 for {}", field.name))
1263                                })?;
1264                                values.insert(field.name.into(), json!(integer));
1265                            }
1266                        }
1267                    }
1268                    let mode = match action {
1269                        ViewAction::Create => WriteMode::Create,
1270                        ViewAction::Update => WriteMode::Update { id },
1271                        _ => WriteMode::Patch { id },
1272                    };
1273                    let write = V::Serializer::is_valid(data, mode)
1274                        .map_err(crate::rest::router::error_validation)?;
1275                    let write = match action {
1276                        ViewAction::Create => {
1277                            match self.viewset.prepare_create(state, Some(principal), write)? {
1278                                ValidatedWrite::Create(query) => {
1279                                    ValidatedWrite::Create(if conditional {
1280                                        query.set(V::Model::primary_key(), id)
1281                                    } else {
1282                                        query
1283                                    })
1284                                }
1285                                _ => {
1286                                    return Err(AppError::BadRequest(
1287                                        "create preparation changed write kind".into(),
1288                                    ));
1289                                }
1290                            }
1291                        }
1292                        ViewAction::Update => self.viewset.prepare_update(
1293                            state,
1294                            Some(principal),
1295                            item.as_ref().expect("current item"),
1296                            write,
1297                        )?,
1298                        _ => self.viewset.prepare_patch(
1299                            state,
1300                            Some(principal),
1301                            item.as_ref().expect("current item"),
1302                            write,
1303                        )?,
1304                    };
1305                    let mut prepared = if !conditional && action == ViewAction::Create {
1306                        server.prepare_write(write).await
1307                    } else {
1308                        server.prepare_conditional_write(write, revision).await
1309                    }
1310                    .map_err(sync_error)?;
1311                    for (_, wire) in json_null_mappings {
1312                        prepared.operation.mutations[0]
1313                            .changes
1314                            .as_mut()
1315                            .ok_or_else(|| AppError::BadRequest("missing JSON write".into()))?
1316                            .insert(wire.into(), che_sync::protocol::Value::Text("null".into()));
1317                    }
1318                    if !conditional && action == ViewAction::Create {
1319                        id = prepared.operation.mutations[0].id;
1320                        request.operation.mutations[0].id = id;
1321                    } else if prepared.operation.mutations[0].id != id {
1322                        return Err(AppError::BadRequest(
1323                            "preparation changed entity identity".into(),
1324                        ));
1325                    }
1326                    request.operation.mutations[0].changes =
1327                        prepared.operation.mutations[0].changes.clone();
1328                }
1329                let result = commit_rest(
1330                    state,
1331                    &self.viewset,
1332                    principal,
1333                    &server,
1334                    request,
1335                    identity.clone(),
1336                    action,
1337                )
1338                .await?;
1339                if conditional {
1340                    return Ok(Some(
1341                        objects::response(
1342                            &self.viewset,
1343                            result,
1344                            action,
1345                            self.model_logs,
1346                            self.object_access.as_ref(),
1347                            state,
1348                            principal,
1349                            &server,
1350                            operation,
1351                        )
1352                        .await?,
1353                    ));
1354                }
1355                accepted(result)?;
1356                if let Some(factory) = &self.object_access {
1357                    return Ok(Some(
1358                        objects::ordinary_response(
1359                            &self.viewset,
1360                            state,
1361                            principal,
1362                            factory,
1363                            id,
1364                            action,
1365                        )
1366                        .await?,
1367                    ));
1368                }
1369                if action == ViewAction::Delete {
1370                    return Ok(Some(StatusCode::NO_CONTENT.into_response()));
1371                }
1372                let item = self
1373                    .viewset
1374                    .get_queryset()
1375                    .filter(V::Model::primary_key().eq(id))
1376                    .first(state.database())
1377                    .await?
1378                    .ok_or(AppError::NotFound)?;
1379                let payload = V::Serializer::to_json(item)?;
1380                Ok(Some(
1381                    (
1382                        if action == ViewAction::Create {
1383                            StatusCode::CREATED
1384                        } else {
1385                            StatusCode::OK
1386                        },
1387                        Json(payload),
1388                    )
1389                        .into_response(),
1390                ))
1391            }
1392            .await;
1393            // A concurrent request may have committed while validation, object
1394            // loading or preparation was running. Resolve that receipt before
1395            // returning an early error/conflict instead of the canonical replay.
1396            if conditional
1397                && (outcome.is_err()
1398                    || outcome
1399                        .as_ref()
1400                        .ok()
1401                        .and_then(|response| response.as_ref())
1402                        .is_some_and(|response| {
1403                            response.status() == StatusCode::PRECONDITION_FAILED
1404                        }))
1405                && let Some(result) = server
1406                    .request_receipt(replica, operation, &identity)
1407                    .await
1408                    .map_err(sync_error)?
1409            {
1410                retry_effects(state, principal, &server, &scope).await;
1411                return Ok(Some(
1412                    objects::response(
1413                        &self.viewset,
1414                        result,
1415                        action,
1416                        self.model_logs,
1417                        self.object_access.as_ref(),
1418                        state,
1419                        principal,
1420                        &server,
1421                        operation,
1422                    )
1423                    .await?,
1424                ));
1425            }
1426            let rejection = match &outcome {
1427                Err(AppError::BadRequest(reason)) => Some(reason.clone()),
1428                Err(AppError::Forbidden(_) | AppError::NotFound)
1429                    if self.object_access.is_some() =>
1430                {
1431                    Some("object permission required".into())
1432                }
1433                _ => None,
1434            };
1435            if conditional
1436                && self.model_logs
1437                && let Some(reason) = rejection
1438            {
1439                let request = PushRequest {
1440                    protocol_version: PROTOCOL_VERSION,
1441                    scope,
1442                    replica_id: replica,
1443                    operation: Operation {
1444                        id: operation,
1445                        mutations: vec![Mutation {
1446                            model: V::Model::SYNC_NAME.into(),
1447                            id,
1448                            schema_version: version,
1449                            base_revision: revision,
1450                            changes: Some(Record::new()),
1451                        }],
1452                    },
1453                };
1454                let result = server
1455                    .reject_request(request, identity, reason)
1456                    .await
1457                    .map_err(sync_error)?;
1458                return Ok(Some(
1459                    objects::response(
1460                        &self.viewset,
1461                        result,
1462                        action,
1463                        true,
1464                        self.object_access.as_ref(),
1465                        state,
1466                        principal,
1467                        &server,
1468                        operation,
1469                    )
1470                    .await?,
1471                ));
1472            }
1473            outcome
1474        })
1475    }
1476    fn save<'a>(
1477        &'a self,
1478        state: &'a AppState,
1479        principal: Option<&'a CurrentPrincipal>,
1480        write: crate::ValidatedWrite<V::Model>,
1481    ) -> MutationFuture<'a, Option<V::Model>> {
1482        Box::pin(async move {
1483            let server = server(&self.viewset, state, principal).await?;
1484            let entities = accepted(server.write(write).await.map_err(sync_error)?)?;
1485            let entity = entities
1486                .iter()
1487                .find(|e| e.model == <V::Model as SyncModel>::SYNC_NAME)
1488                .ok_or_else(|| AppError::BadRequest("missing canonical write result".into()))?;
1489            // Decode the canonical receipt, without racing a later database write.
1490            Ok(Some(materialize::<V::Model>(entity)?))
1491        })
1492    }
1493
1494    fn delete<'a>(
1495        &'a self,
1496        state: &'a AppState,
1497        principal: Option<&'a CurrentPrincipal>,
1498        id: Uuid,
1499    ) -> MutationFuture<'a, ()> {
1500        Box::pin(async move {
1501            let server = server(&self.viewset, state, principal).await?;
1502            accepted(server.delete::<V::Model>(id).await.map_err(sync_error)?)?;
1503            Ok(())
1504        })
1505    }
1506}
1507
1508fn rest_response(result: PushResult, action: ViewAction, model: &str) -> Response {
1509    let status = match &result {
1510        PushResult::Accepted(_) if action == ViewAction::Create => StatusCode::CREATED,
1511        PushResult::Accepted(_) => StatusCode::OK,
1512        PushResult::Conflict(_) => StatusCode::PRECONDITION_FAILED,
1513        PushResult::Rejected { .. } => StatusCode::BAD_REQUEST,
1514    };
1515    let revision = match &result {
1516        PushResult::Accepted(entities) => entities
1517            .iter()
1518            .find(|e| e.model == model)
1519            .map(|e| e.revision),
1520        _ => None,
1521    };
1522    let mut response = (status, Json(result)).into_response();
1523    response.headers_mut().insert(
1524        "content-type",
1525        "application/vnd.che-sync+json".parse().unwrap(),
1526    );
1527    if let Some(revision) = revision {
1528        response
1529            .headers_mut()
1530            .insert("etag", format!("\"{revision}\"").parse().unwrap());
1531    }
1532    response
1533}
1534
1535pub(crate) fn add_rest_openapi(document: &mut Value) {
1536    if let Some(paths) = document["paths"].as_object_mut() {
1537        for item in paths.values_mut() {
1538            for method in ["post", "patch", "put", "delete"] {
1539                let Some(operation) = item.get_mut(method) else {
1540                    continue;
1541                };
1542                let parameters = operation
1543                    .as_object_mut()
1544                    .unwrap()
1545                    .entry("parameters")
1546                    .or_insert_with(|| json!([]))
1547                    .as_array_mut()
1548                    .unwrap();
1549                for name in [
1550                    "X-Sync-Protocol",
1551                    "X-Sync-Replica",
1552                    "X-Sync-Scope",
1553                    "X-Sync-Version",
1554                    "If-Match",
1555                    "Idempotency-Key",
1556                ] {
1557                    parameters.push(json!({"in":"header","name":name,"required":false,"description":"Required together for a conditional, idempotent sync write; body uses the ordinary serializer.","schema":{"type":"string"}}));
1558                }
1559                if method == "post" {
1560                    parameters.push(json!({"in":"header","name":"X-Sync-Entity","required":false,"description":"Offline UUID for conditional sync creation.","schema":{"type":"string","format":"uuid"}}));
1561                }
1562                let responses = operation["responses"].as_object_mut().unwrap();
1563                for status in [if method == "post" { "201" } else { "200" }, "412", "400"] {
1564                    let response = responses.entry(status).or_insert_with(
1565                        || json!({"description":"Conditional synchronization result"}),
1566                    );
1567                    response
1568                        .as_object_mut()
1569                        .unwrap()
1570                        .entry("content")
1571                        .or_insert_with(|| json!({}))
1572                        .as_object_mut()
1573                        .unwrap()
1574                        .insert(
1575                            "application/vnd.che-sync+json".into(),
1576                            json!({"schema":PushResult::api_schema().openapi}),
1577                        );
1578                }
1579            }
1580        }
1581    }
1582}
1583
1584pub(crate) fn add_model_rest_openapi(document: &mut Value) {
1585    add_rest_openapi(document);
1586    if let Some(paths) = document["paths"].as_object_mut() {
1587        for item in paths.values_mut() {
1588            for method in ["post", "put", "patch", "delete"] {
1589                let Some(operation) = item.get_mut(method) else {
1590                    continue;
1591                };
1592                if let Some(parameters) = operation["parameters"].as_array_mut() {
1593                    parameters.retain(|parameter| parameter["name"] != "X-Sync-Scope");
1594                    for parameter in parameters {
1595                        if parameter["name"] == "X-Sync-Protocol" {
1596                            parameter["schema"]["enum"] = json!(["2"]);
1597                        }
1598                    }
1599                }
1600                if let Some(responses) = operation["responses"].as_object_mut() {
1601                    for response in responses.values_mut() {
1602                        if let Some(content) = response["content"].as_object_mut() {
1603                            content.remove("application/vnd.che-sync+json");
1604                            content.insert(
1605                                "application/vnd.che-sync.v2+json".into(),
1606                                json!({"schema": model_write_schema()}),
1607                            );
1608                        }
1609                    }
1610                }
1611            }
1612        }
1613    }
1614}
1615
1616fn model_write_schema() -> Value {
1617    json!({"oneOf":[
1618        {"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["accepted","conflict"]},"data":{"type":"array","items":{"type":"object","required":["model","record_id","revision","schema_version","values"],"properties":{"model":{"type":"string"},"record_id":{"type":"string","format":"uuid"},"revision":{"type":"string"},"schema_version":{"type":"integer"},"values":{"type":"object","nullable":true,"additionalProperties":true}}}}}},
1619        {"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["rejected"]},"data":{"type":"object","required":["code","reason"],"properties":{"code":{"type":"string"},"reason":{"type":"string"}}}}}
1620    ]})
1621}
1622
1623impl ApiSchema for che_sync::protocol::model_log::ModelChanges {
1624    fn api_schema() -> ApiSchemaDefinition {
1625        ApiSchemaDefinition {
1626            name: "ModelChanges",
1627            openapi: json!({"type":"object","required":["model","history","operations","next_cursor","has_more"],"properties":{
1628                "model":{"type":"string"},"history":{"type":"string","format":"uuid"},"next_cursor":{"type":"string"},"has_more":{"type":"boolean"},
1629                "operations":{"type":"array","items":{"type":"object","required":["id","record_id","revision","kind","diff","created_at","schema_version"],"properties":{
1630                    "id":{"type":"string"},"record_id":{"type":"string","format":"uuid"},"revision":{"type":"string"},"kind":{"type":"string","enum":["create","update","delete"]},"created_at":{"type":"string","format":"date-time"},"schema_version":{"type":"integer"},
1631                    "diff":{"type":"array","items":{"type":"object","required":["field"],"properties":{"field":{"type":"string"},"old_value":{},"new_value":{},"old_sql_null":{"type":"boolean"},"new_sql_null":{"type":"boolean"}}}}
1632                }}}
1633            }}),
1634            typescript: concat!(
1635                "export interface ModelFieldDiff { field: string; old_value?: JsonValue; new_value?: JsonValue; old_sql_null?: boolean; new_sql_null?: boolean; }\n",
1636                "export interface ModelLogOperation { id: string; record_id: string; revision: string; kind: 'create' | 'update' | 'delete'; diff: ModelFieldDiff[]; created_at: string; schema_version: number; }\n",
1637                "export interface ModelChanges { model: string; history: string; operations: ModelLogOperation[]; next_cursor: string; has_more: boolean; }"
1638            ),
1639        }
1640    }
1641}
1642
1643fn database_value(value: &che_sync::protocol::Value) -> che_orm::DatabaseValue {
1644    use che_orm::DatabaseValue as D;
1645    use che_sync::protocol::Value as V;
1646    match value {
1647        V::Integer(v) => D::Integer(*v),
1648        V::Real(v) => D::Real(*v),
1649        V::Text(v) => D::Text(v.clone()),
1650        V::Binary(v) => D::Binary(v.clone()),
1651        V::Boolean(v) => D::Boolean(*v),
1652        V::DateTime(v) => D::DateTime(*v),
1653        V::Uuid(v) => D::Uuid(*v),
1654        V::Null => D::Null,
1655    }
1656}
1657
1658fn object(properties: Value, required: &[&str]) -> Value {
1659    json!({"type":"object", "properties":properties, "required":required})
1660}
1661fn cursor_schema() -> Value {
1662    object(
1663        json!({"scope":{"type":"string"},"model":{"type":"string"},"epoch":{"type":"string","format":"uuid"},
1664        "sequence":{"type":"string","pattern":"^[0-9]+$"}}),
1665        &["scope", "epoch", "sequence"],
1666    )
1667}
1668fn record_schema() -> Value {
1669    let variant = |tag: &str, value: Value| {
1670        object(
1671            json!({"type":{"type":"string","enum":[tag]},"value":value}),
1672            &["type", "value"],
1673        )
1674    };
1675    json!({"type":"object","additionalProperties":{"oneOf":[
1676        variant("integer",json!({"type":"string","pattern":"^-?[0-9]+$"})),
1677        variant("real",json!({"type":"number"})), variant("text",json!({"type":"string"})),
1678        variant("binary",json!({"type":"array","items":{"type":"integer","minimum":0,"maximum":255}})),
1679        variant("boolean",json!({"type":"boolean"})),
1680        variant("date_time",json!({"type":"string"})),
1681        variant("uuid",json!({"type":"string","format":"uuid"})),
1682        object(json!({"type":{"type":"string","enum":["null"]}}), &["type"])
1683    ]}})
1684}
1685fn entity_schema() -> Value {
1686    let mut record = record_schema();
1687    record["nullable"] = json!(true);
1688    object(
1689        json!({"model":{"type":"string"},"id":{"type":"string","format":"uuid"},
1690        "schema_version":{"type":"integer","minimum":1},"revision":{"type":"string","pattern":"^[0-9]+$"},
1691        "epoch":{"type":"string","format":"uuid","nullable":true},
1692        "updated_at":{"type":"string","format":"date-time","nullable":true},
1693        "deleted_at":{"type":"string","format":"date-time","nullable":true},
1694        "record":record}),
1695        &["model", "id", "schema_version", "revision", "record"],
1696    )
1697}
1698fn entities_schema() -> Value {
1699    json!({"type":"array","items":entity_schema()})
1700}
1701
1702impl ApiSchema for PushRequest {
1703    fn api_schema() -> ApiSchemaDefinition {
1704        let mut changes = record_schema();
1705        changes["nullable"] = json!(true);
1706        let mutation = object(
1707            json!({"model":{"type":"string"},"id":{"type":"string","format":"uuid"},
1708            "schema_version":{"type":"integer","minimum":1},"base_revision":{"type":"string","pattern":"^[0-9]+$"},
1709            "changes":changes}),
1710            &["model", "id", "schema_version", "base_revision", "changes"],
1711        );
1712        ApiSchemaDefinition {
1713            name: "SyncPushRequest",
1714            openapi: object(
1715                json!({
1716                    "protocol_version":{"type":"integer","enum":[PROTOCOL_VERSION]},"scope":{"type":"string"},
1717                    "replica_id":{"type":"string","format":"uuid"},"operation":object(json!({"id":{"type":"string","format":"uuid"},
1718                        "mutations":{"type":"array","minItems":1,"items":mutation}}), &["id","mutations"])
1719                }),
1720                &["protocol_version", "scope", "replica_id", "operation"],
1721            ),
1722            typescript: concat!(
1723                "export type SyncValue = { type: 'integer'; value: string } | { type: 'real'; value: number } | { type: 'text' | 'uuid' | 'date_time'; value: string } | { type: 'binary'; value: number[] } | { type: 'boolean'; value: boolean } | { type: 'null' };\n",
1724                "export type SyncRecord = Record<string, SyncValue>;\n",
1725                "export interface SyncEntity { model: string; id: string; schema_version: number; revision: string; epoch?: string | null; updated_at?: string | null; deleted_at?: string | null; record: SyncRecord | null; }\n",
1726                "export interface SyncCursor { scope: string; model?: string; epoch: string; sequence: string; }\n",
1727                "export interface SyncChangeGroup { sequence: string; entities: SyncEntity[]; }\n",
1728                "export interface SyncPushRequest { protocol_version: number; scope: string; replica_id: string; operation: { id: string; mutations: { model: string; id: string; schema_version: number; base_revision: string; changes: SyncRecord | null; }[] }; }"
1729            ),
1730        }
1731    }
1732}
1733impl ApiSchema for PushResult {
1734    fn api_schema() -> ApiSchemaDefinition {
1735        ApiSchemaDefinition {
1736            name: "SyncPushResult",
1737            openapi: json!({"oneOf":[
1738                object(json!({"status":{"type":"string","enum":["accepted","conflict"]},"data":entities_schema()}), &["status","data"]),
1739                object(json!({"status":{"type":"string","enum":["rejected"]},"data":object(json!({"reason":{"type":"string"}}), &["reason"])}), &["status","data"])
1740            ]}),
1741            typescript: "export type SyncPushResult = { status: 'accepted' | 'conflict'; data: SyncEntity[] } | { status: 'rejected'; data: { reason: string } };",
1742        }
1743    }
1744}
1745impl ApiSchema for PullRequest {
1746    fn api_schema() -> ApiSchemaDefinition {
1747        let mut cursor = cursor_schema();
1748        cursor["nullable"] = json!(true);
1749        ApiSchemaDefinition {
1750            name: "SyncPullRequest",
1751            openapi: object(
1752                json!({"protocol_version":{"type":"integer","enum":[PROTOCOL_VERSION]},
1753            "cursor":cursor,"limit":{"type":"integer","minimum":1,"maximum":1000}}),
1754                &["protocol_version", "cursor", "limit"],
1755            ),
1756            typescript: concat!(
1757                "export type SyncValue = { type: 'integer'; value: string } | { type: 'real'; value: number } | { type: 'text' | 'uuid' | 'date_time'; value: string } | { type: 'binary'; value: number[] } | { type: 'boolean'; value: boolean } | { type: 'null' };\n",
1758                "export type SyncRecord = Record<string, SyncValue>;\n",
1759                "export interface SyncEntity { model: string; id: string; schema_version: number; revision: string; epoch?: string | null; updated_at?: string | null; deleted_at?: string | null; record: SyncRecord | null; }\n",
1760                "export interface SyncCursor { scope: string; model?: string; epoch: string; sequence: string; }\n",
1761                "export interface SyncChangeGroup { sequence: string; entities: SyncEntity[]; }\n",
1762                "export type SyncRestResult = { status: 'accepted' | 'conflict'; data: SyncEntity[] } | { status: 'rejected'; data: { reason: string } };\n",
1763                "export interface SyncPullRequest { protocol_version: number; cursor: SyncCursor | null; limit: number; }"
1764            ),
1765        }
1766    }
1767}
1768impl ApiSchema for PullResult {
1769    fn api_schema() -> ApiSchemaDefinition {
1770        ApiSchemaDefinition {
1771            name: "SyncPullResult",
1772            openapi: json!({"oneOf":[
1773                object(json!({"status":{"type":"string","enum":["full"]},"data":object(json!({"entities":entities_schema(),"cursor":cursor_schema()}), &["entities","cursor"])}), &["status","data"]),
1774                object(json!({"status":{"type":"string","enum":["changes"]},"data":object(json!({
1775                    "groups":{"type":"array","items":object(json!({"sequence":{"type":"string","pattern":"^[0-9]+$"},"entities":entities_schema()}), &["sequence","entities"])},
1776                    "cursor":cursor_schema(),"has_more":{"type":"boolean"}}), &["groups","cursor","has_more"])}), &["status","data"]),
1777                object(json!({"status":{"type":"string","enum":["reset_required"]}}), &["status"])
1778            ]}),
1779            typescript: "export type SyncPullResult = { status: 'full'; data: { entities: SyncEntity[]; cursor: SyncCursor } } | { status: 'changes'; data: { groups: SyncChangeGroup[]; cursor: SyncCursor; has_more: boolean } } | { status: 'reset_required' };",
1780        }
1781    }
1782}
1783impl ApiSchema for Snapshot {
1784    fn api_schema() -> ApiSchemaDefinition {
1785        ApiSchemaDefinition {
1786            name: "SyncSnapshot",
1787            openapi: object(
1788                json!({"entities":entities_schema(),"cursor":cursor_schema()}),
1789                &["entities", "cursor"],
1790            ),
1791            typescript: "export interface SyncSnapshot { entities: SyncEntity[]; cursor: SyncCursor; }",
1792        }
1793    }
1794}
1795
1796pub(crate) fn add_object_rest_openapi(document: &mut Value) {
1797    objects::add_openapi(document);
1798}
1799
1800/// Check the same whole-model permission and sync policy as a model journal GET.
1801pub async fn authorize_model_journal<V: SyncViewSet>(
1802    viewset: &V,
1803    state: &AppState,
1804    principal: &CurrentPrincipal,
1805) -> AppResult<()>
1806where
1807    V::Model: SyncModel,
1808{
1809    let permission = V::Permission::default();
1810    if permission.object_scoped() {
1811        return Err(AppError::Forbidden(
1812            "whole-model journal access required".into(),
1813        ));
1814    }
1815    permission
1816        .check_request(state.into(), Some(principal), ViewAction::List)
1817        .await?;
1818    viewset
1819        .sync_policy()
1820        .authorize_scope(
1821            &principal.auth_user().id.to_string(),
1822            che_sync::model_log::MODEL_LOG_SCOPE,
1823        )
1824        .map_err(|e| AppError::Forbidden(e.to_string()))
1825}
1826
1827#[derive(serde::Serialize, serde::Deserialize)]
1828pub struct JournalChangesRequest {
1829    pub models: Vec<che_sync::model_log::ModelJournalRequest>,
1830    pub limit: u32,
1831}
1832#[derive(serde::Serialize, serde::Deserialize)]
1833pub struct JournalChangesResponse {
1834    pub models: Vec<che_sync::model_log::ModelJournalPage>,
1835}
1836impl ApiSchema for JournalChangesRequest {
1837    fn api_schema() -> ApiSchemaDefinition {
1838        ApiSchemaDefinition {
1839            name: "JournalChangesRequest",
1840            openapi: json!({"type":"object","required":["models","limit"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":1000},"models":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["model","cursor"],"properties":{"model":{"type":"string"},"cursor":{"type":"object","nullable":true,"required":["history","after"],"properties":{"history":{"type":"string","format":"uuid"},"after":{"type":"string","pattern":"^[0-9]+$"}}}}}}}}),
1841            typescript: "export interface JournalChangesRequest { models: { model: string; cursor: { history: string; after: string } | null }[]; limit: number; }",
1842        }
1843    }
1844}
1845impl ApiSchema for JournalChangesResponse {
1846    fn api_schema() -> ApiSchemaDefinition {
1847        let operation = <che_sync::model_log::ModelChanges as ApiSchema>::api_schema().openapi["properties"]["operations"].clone();
1848        ApiSchemaDefinition {
1849            name: "JournalChangesResponse",
1850            openapi: json!({"type":"object","required":["models"],"properties":{"models":{"type":"array","items":{"oneOf":[{"type":"object","required":["model","status"],"properties":{"model":{"type":"string"},"status":{"type":"string","enum":["reset_required"]}}},{"type":"object","required":["model","status","operations","cursor","has_more"],"properties":{"model":{"type":"string"},"status":{"type":"string","enum":["changes"]},"operations":operation,"cursor":{"type":"object","required":["history","after"],"properties":{"history":{"type":"string","format":"uuid"},"after":{"type":"string"}}},"has_more":{"type":"boolean"}}}]}}}}),
1851            typescript: "export interface JournalChangesResponse { models: ({ model: string; status: 'reset_required' } | { model: string; status: 'changes'; operations: { id: string; record_id: string; revision: string; kind: 'create' | 'update' | 'delete'; diff: { field: string; old_value?: unknown; new_value?: unknown; old_sql_null?: boolean; new_sql_null?: boolean }[]; created_at: string; schema_version: number }[]; cursor: { history: string; after: string }; has_more: boolean })[]; }",
1852        }
1853    }
1854}