1use 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#[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
64pub 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
339pub 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#[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#[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
415pub(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#[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
704pub 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 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 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 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
1800pub 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}