Skip to main content

che_rest/sync/
objects.rs

1//! HTTP/principal bridge for explicit object-delivery protocol 3.
2use super::*;
3use crate::auth::access::{ADD, Access, AccessModel, CHANGE, DELETE, VIEW};
4use crate::rest::permissions::PermissionContext;
5use che_orm::{Expr, Transaction, TransactionFuture};
6use che_sync::object_log::*;
7use std::marker::PhantomData;
8
9pub(super) type ObjectPolicyFactory = Arc<
10    dyn Fn(
11            AppState,
12            CurrentPrincipal,
13        ) -> AppResult<(Arc<dyn AccessPolicy>, Arc<dyn ObjectAccessPolicy>)>
14        + Send
15        + Sync,
16>;
17
18/// Opt-in protocol 3. ACLs and business writes share a transaction; GET journal
19/// v2 is deliberately absent. Apply explicit object-delivery follow-up migrations.
20#[derive(Clone)]
21pub struct ObjectSyncEndpoints<V>(SyncEndpoints<V>);
22impl<V: SyncViewSet> ObjectSyncEndpoints<V>
23where
24    V::Model: SyncModel + AccessModel,
25{
26    pub fn new(viewset: V) -> Self {
27        let mut inner = SyncEndpoints::new(viewset.clone());
28        inner.model_logs = true;
29        inner.object_access = Some(Arc::new(move |state, principal| {
30            let filter = viewset.get_queryset().object_sync_filter()?;
31            let policy = Arc::new(ObjectPolicy::<V::Model> {
32                state,
33                principal,
34                filter,
35                namespace: viewset.path().into(),
36                model: PhantomData,
37            });
38            Ok((policy.clone(), policy))
39        }));
40        Self(inner)
41    }
42}
43impl<V: SyncViewSet> ViewSetExtension<V> for ObjectSyncEndpoints<V>
44where
45    V::Model: SyncModel + AccessModel,
46{
47    const ID: &'static str = "object-sync";
48    fn install(self, context: &mut ExtensionContext<'_, V>) -> AppResult<()> {
49        if std::any::TypeId::of::<V::Permission>() != std::any::TypeId::of::<Access<V::Model>>() {
50            return Err(AppError::BadRequest(
51                "object sync currently requires Permission = Access<Model>".into(),
52            ));
53        }
54        che_sync::object_log::validate_registry(&self.0.viewset.sync_registry()?)?;
55        self.0.viewset.get_queryset().object_sync_filter()?;
56        let schema = V::Model::schema();
57        for mapping in V::Model::registered_fields() {
58            if [
59                V::Model::REVISION_COLUMN,
60                V::Model::UPDATED_AT_COLUMN,
61                V::Model::DELETED_AT_COLUMN,
62                V::Model::SCOPE_COLUMN,
63            ]
64            .contains(&mapping.column)
65            {
66                continue;
67            }
68            let column = schema
69                .columns
70                .iter()
71                .find(|c| c.name == mapping.column)
72                .expect("registered column");
73            if !V::Serializer::fields()
74                .iter()
75                .any(|f| f.source == column.field_name && f.related_model.is_none())
76            {
77                return Err(AppError::BadRequest(format!(
78                    "object sync discloses full scalar states; serializer must expose {}",
79                    mapping.name
80                )));
81            }
82        }
83
84        self.0.install(context)
85    }
86}
87
88struct ObjectPolicy<M> {
89    state: AppState,
90    principal: CurrentPrincipal,
91    filter: Option<Expr>,
92    namespace: String,
93    model: PhantomData<fn() -> M>,
94}
95fn policy_error(error: AppError) -> OrmError {
96    match error {
97        AppError::Orm(e) => e,
98        _ => OrmError::Configuration("object permission required".into()),
99    }
100}
101impl<M: SyncModel + AccessModel> ObjectPolicy<M> {
102    async fn in_queryset(&self, tx: &Transaction, id: Uuid) -> Result<bool, OrmError> {
103        let mut q = M::query().filter(M::primary_key().eq(id));
104        if let Some(f) = &self.filter {
105            q = q.filter(f.clone());
106        }
107        Ok(tx.fetch_one(q).await?.is_some())
108    }
109    fn context<'a>(&'a self, tx: &'a Transaction) -> PermissionContext<'a> {
110        PermissionContext::in_transaction(&self.state, tx)
111    }
112}
113impl<M: SyncModel + AccessModel> ObjectAccessPolicy for ObjectPolicy<M> {
114    fn feed_namespace(&self) -> &str {
115        &self.namespace
116    }
117    fn rights<'a>(
118        &'a self,
119        tx: &'a Transaction,
120        model: &'a str,
121        id: Uuid,
122    ) -> TransactionFuture<'a, ObjectRights> {
123        Box::pin(async move {
124            if model != M::SYNC_NAME {
125                return Err(OrmError::Configuration("wrong object model".into()));
126            }
127            if !self.in_queryset(tx, id).await? {
128                return Ok(ObjectRights::default());
129            }
130            let context = self.context(tx);
131            Ok(ObjectRights {
132                read: Access::<M>::can(context, &self.principal, VIEW, id)
133                    .await
134                    .map_err(policy_error)?,
135                change: Access::<M>::can(context, &self.principal, CHANGE, id)
136                    .await
137                    .map_err(policy_error)?,
138                delete: Access::<M>::can(context, &self.principal, DELETE, id)
139                    .await
140                    .map_err(policy_error)?,
141            })
142        })
143    }
144    fn can_create<'a>(
145        &'a self,
146        tx: &'a Transaction,
147        model: &'a str,
148    ) -> TransactionFuture<'a, bool> {
149        Box::pin(async move {
150            if model != M::SYNC_NAME {
151                return Err(OrmError::Configuration("wrong object model".into()));
152            }
153            Ok(
154                (M::SUPERUSER_BYPASS && self.principal.auth_user().is_superuser)
155                    || Access::<M>::has_model_permission(
156                        self.context(tx),
157                        self.principal.auth_user().id,
158                        ADD,
159                    )
160                    .await
161                    .map_err(policy_error)?,
162            )
163        })
164    }
165}
166impl<M: SyncModel + AccessModel> AccessPolicy for ObjectPolicy<M> {
167    fn isolation(&self) -> che_orm::IsolationLevel {
168        che_orm::IsolationLevel::Serializable
169    }
170    fn authorize_scope(&self, principal: &str, scope: &str) -> Result<(), OrmError> {
171        if principal != self.principal.auth_user().id.to_string()
172            || scope != che_sync::model_log::MODEL_LOG_SCOPE
173        {
174            return Err(OrmError::Configuration("object principal mismatch".into()));
175        }
176        Ok(())
177    }
178    fn validate(&self, _: &str, _: &str, _: &Entity, _: &Entity) -> Result<(), OrmError> {
179        Ok(())
180    }
181    fn authorize_write<'a>(
182        &'a self,
183        tx: &'a Transaction,
184        current: &'a Entity,
185        mutation: &'a Mutation,
186    ) -> TransactionFuture<'a, ()> {
187        Box::pin(async move {
188            if mutation.model != M::SYNC_NAME {
189                return Err(OrmError::Configuration("wrong object model".into()));
190            }
191            let create = mutation.base_revision == 0 && mutation.changes.is_some();
192            if create {
193                if !self.can_create(tx, M::SYNC_NAME).await? {
194                    return Err(OrmError::Configuration("add permission required".into()));
195                }
196            } else {
197                if !self.in_queryset(tx, current.id).await? {
198                    return Err(OrmError::Configuration("object permission required".into()));
199                }
200                Access::<M>::require(
201                    self.context(tx),
202                    &self.principal,
203                    if mutation.changes.is_none() {
204                        DELETE
205                    } else {
206                        CHANGE
207                    },
208                    current.id,
209                )
210                .await
211                .map_err(policy_error)?;
212            }
213            Ok(())
214        })
215    }
216    fn after_write<'a>(
217        &'a self,
218        tx: &'a Transaction,
219        current: &'a Entity,
220        next: &'a Entity,
221    ) -> TransactionFuture<'a, ()> {
222        Box::pin(async move {
223            if current.revision == 0 && next.record.is_some() {
224                for permission in M::CREATOR_PERMISSIONS {
225                    Access::<M>::grant(
226                        tx,
227                        crate::auth::access::Subject::User(self.principal.auth_user().id),
228                        permission,
229                        next.id,
230                    )
231                    .await
232                    .map_err(policy_error)?;
233                }
234            }
235            Ok(())
236        })
237    }
238}
239
240#[derive(serde::Deserialize)]
241#[serde(deny_unknown_fields)]
242struct ObjectPullRequest {
243    protocol_version: u32,
244    cursor: Option<ObjectCursor>,
245    limit: u32,
246}
247fn object_cursor_schema() -> Value {
248    object(
249        json!({"model":{"type":"string"},"history":{"type":"string","format":"uuid"},"feed":{"type":"string","format":"uuid"},"sequence":{"type":"string","pattern":"^[0-9]+$"}}),
250        &["model", "history", "feed", "sequence"],
251    )
252}
253impl ApiSchema for ObjectPullRequest {
254    fn api_schema() -> ApiSchemaDefinition {
255        let mut cursor = object_cursor_schema();
256        cursor["nullable"] = json!(true);
257        ApiSchemaDefinition {
258            name: "ObjectPullRequest",
259            openapi: object(
260                json!({"protocol_version":{"type":"integer","enum":[3]},"cursor":cursor,"limit":{"type":"integer","minimum":1,"maximum":1000}}),
261                &["protocol_version", "cursor", "limit"],
262            ),
263            typescript: concat!(
264                "export interface ObjectCursor { model:string; history:string; feed:string; sequence:string; }\n",
265                "export interface ObjectPullRequest { protocol_version:3; cursor:ObjectCursor | null; limit:number; }"
266            ),
267        }
268    }
269}
270impl ApiSchema for ObjectChanges {
271    fn api_schema() -> ApiSchemaDefinition {
272        let rights = object(
273            json!({"read":{"type":"boolean"},"change":{"type":"boolean"},"delete":{"type":"boolean"}}),
274            &["read", "change", "delete"],
275        );
276        let state = object(
277            json!({"model":{"type":"string"},"record_id":{"type":"string","format":"uuid"},"revision":{"type":"string"},"schema_version":{"type":"integer"},"values":{"type":"object","additionalProperties":true},"sql_null_fields":{"type":"array","items":{"type":"string"}},"updated_at":{"type":"string","format":"date-time","nullable":true},"deleted_at":{"type":"string","format":"date-time","nullable":true}}),
278            &["model", "record_id", "revision", "schema_version", "values"],
279        );
280        let changes = json!({"oneOf":[
281            object(json!({"kind":{"type":"string","enum":["state"]},"state":state,"rights":rights}),&["kind","state","rights"]),
282            object(json!({"kind":{"type":"string","enum":["revoked"]},"record_id":{"type":"string","format":"uuid"}}),&["kind","record_id"]),
283            object(json!({"kind":{"type":"string","enum":["deleted"]},"record_id":{"type":"string","format":"uuid"},"revision":{"type":"string"}}),&["kind","record_id","revision"])
284        ]});
285        ApiSchemaDefinition {
286            name: "ObjectChanges",
287            openapi: object(
288                json!({"protocol_version":{"type":"integer","enum":[3]},"cursor":object_cursor_schema(),"after":{"type":"string"},"events":{"type":"array","items":object(json!({"sequence":{"type":"string"},"change":changes}),&["sequence","change"])},"can_create":{"type":"boolean"},"has_more":{"type":"boolean"}}),
289                &[
290                    "protocol_version",
291                    "cursor",
292                    "after",
293                    "events",
294                    "can_create",
295                    "has_more",
296                ],
297            ),
298            typescript: concat!(
299                "export interface ObjectRights { read:boolean; change:boolean; delete:boolean; }\n",
300                "export interface ObjectModelState { model:string; record_id:string; revision:string; schema_version:number; values:Record<string,unknown> | null; sql_null_fields:string[]; updated_at:string | null; deleted_at:string | null; }\n",
301                "export type ObjectChange = {kind:'state'; state:ObjectModelState; rights:ObjectRights} | {kind:'revoked'; record_id:string} | {kind:'deleted'; record_id:string; revision:string};\n",
302                "export interface ObjectChanges { protocol_version:3; cursor:ObjectCursor; after:string; events:{sequence:string;change:ObjectChange}[]; can_create:boolean; has_more:boolean; }"
303            ),
304        }
305    }
306}
307pub(super) fn install_route<V: SyncViewSet>(
308    endpoints: &SyncEndpoints<V>,
309    context: &mut ExtensionContext<'_, V>,
310) -> AppResult<()>
311where
312    V::Model: SyncModel,
313{
314    let factory = endpoints.object_access.clone().expect("object factory");
315    let prefix = endpoints.viewset.path().trim_matches('/').replace('/', "_");
316    context.route("sync/objects", move |route| {
317        route.post(
318            move |Extension(state): Extension<AppState>,
319                  Extension(viewset): Extension<V>,
320                  who: Option<Extension<CurrentPrincipal>>,
321                  Json(request): Json<ObjectPullRequest>| {
322                let factory = factory.clone();
323                async move {
324                    if request.protocol_version != OBJECT_LOG_PROTOCOL {
325                        return Err(AppError::BadRequest("incompatible object protocol".into()));
326                    }
327                    let principal = who
328                        .ok_or_else(|| AppError::Unauthorized("authentication required".into()))?
329                        .0;
330                    let server = server_with_objects(
331                        &viewset,
332                        &state,
333                        Some(&principal),
334                        true,
335                        Some(&factory),
336                    )
337                    .await?;
338                    let policy = factory(state.clone(), principal)?.1;
339                    Ok::<_, AppError>(Json(
340                        server
341                            .object_changes::<V::Model>(request.cursor, request.limit, policy)
342                            .await
343                            .map_err(sync_error)?,
344                    ))
345                }
346            },
347            OperationSpec::new(format!("{prefix}_sync_objects"))
348                .authenticated()
349                .request::<ObjectPullRequest>()
350                .response::<ObjectChanges>(StatusCode::OK)
351                .client("sync", "objects"),
352        )
353    })
354}
355
356#[allow(clippy::too_many_arguments)]
357pub(super) async fn response<V: SyncViewSet>(
358    viewset: &V,
359    result: PushResult,
360    action: ViewAction,
361    model_logs: bool,
362    factory: Option<&ObjectPolicyFactory>,
363    state: &AppState,
364    principal: &CurrentPrincipal,
365    server: &SyncServer,
366    operation: Uuid,
367) -> AppResult<Response>
368where
369    V::Model: SyncModel,
370{
371    let Some(factory) = factory else {
372        return write_response(viewset, result, action, model_logs);
373    };
374    let result = server
375        .object_write_result(
376            operation,
377            result,
378            factory(state.clone(), principal.clone())?.1,
379        )
380        .await?;
381    let outcome = match &result {
382        ObjectWriteResult::Acknowledged { outcome, .. } => *outcome,
383        ObjectWriteResult::Canonical(r) => match r {
384            che_sync::model_log::ModelWriteResult::Accepted(_) => WriteOutcome::Accepted,
385            che_sync::model_log::ModelWriteResult::Conflict(_) => WriteOutcome::Conflict,
386            che_sync::model_log::ModelWriteResult::Rejected { .. } => WriteOutcome::Rejected,
387        },
388    };
389    let status = match outcome {
390        WriteOutcome::Accepted if action == ViewAction::Create => StatusCode::CREATED,
391        WriteOutcome::Accepted => StatusCode::OK,
392        WriteOutcome::Conflict => StatusCode::PRECONDITION_FAILED,
393        WriteOutcome::Rejected => StatusCode::BAD_REQUEST,
394    };
395    let mut response = (status, Json(result)).into_response();
396    response.headers_mut().insert(
397        "content-type",
398        "application/vnd.che-sync.v3+json".parse().unwrap(),
399    );
400    Ok(response)
401}
402
403/// Schema-only infrastructure module. Freeze the operations returned by
404/// `che_sync::object_log::migration_operations(Server)` in a follow-up history.
405pub fn object_schema_module() -> impl crate::AppModule {
406    ObjectSchemaModule
407}
408struct ObjectSchemaModule;
409impl crate::AppModule for ObjectSchemaModule {
410    fn name(&self) -> &'static str {
411        "che_object_sync"
412    }
413    fn schema(&self) -> che_orm::SchemaSet {
414        che_sync::object_log::schema(che_orm::ModelRole::Server)
415    }
416    fn init(&self, _: &mut crate::ModuleContext) {}
417}
418
419pub(super) fn add_openapi(document: &mut Value) {
420    add_model_rest_openapi(document);
421    if let Some(paths) = document["paths"].as_object_mut() {
422        for item in paths.values_mut() {
423            for method in ["post", "put", "patch", "delete"] {
424                let Some(operation) = item.get_mut(method) else {
425                    continue;
426                };
427                if let Some(parameters) = operation["parameters"].as_array_mut() {
428                    for parameter in parameters {
429                        if parameter["name"] == "X-Sync-Protocol" {
430                            parameter["schema"]["enum"] = json!(["3"]);
431                        }
432                    }
433                }
434                if let Some(responses) = operation["responses"].as_object_mut() {
435                    for response in responses.values_mut() {
436                        if let Some(content) = response["content"].as_object_mut() {
437                            content.remove("application/vnd.che-sync.v2+json");
438                            content.insert("application/vnd.che-sync.v3+json".into(),json!({"schema":{"oneOf":[object(json!({"kind":{"type":"string","enum":["canonical"]},"data":model_write_schema()}),&["kind","data"]),object(json!({"kind":{"type":"string","enum":["acknowledged"]},"data":object(json!({"operation_id":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["accepted","conflict","rejected"]}}),&["operation_id","outcome"])}),&["kind","data"])]}}));
439                        }
440                    }
441                }
442            }
443        }
444    }
445}
446
447pub(super) async fn ordinary_response<V: SyncViewSet>(
448    viewset: &V,
449    state: &AppState,
450    principal: &CurrentPrincipal,
451    factory: &ObjectPolicyFactory,
452    id: Uuid,
453    action: ViewAction,
454) -> AppResult<Response>
455where
456    V::Model: SyncModel,
457{
458    if action == ViewAction::Delete {
459        return Ok(StatusCode::NO_CONTENT.into_response());
460    }
461    let policy = factory(state.clone(), principal.clone())?.1;
462    let viewset = viewset.clone();
463    // Authorization and response materialization must see the same snapshot;
464    // a later write after a concurrent revoke cannot leak through a reload.
465    let payload = state
466        .database()
467        .transaction_result(move |tx| {
468            Box::pin(async move {
469                if !policy.rights(tx, V::Model::SYNC_NAME, id).await?.read {
470                    return Ok::<_, AppError>(None);
471                }
472                let item = viewset
473                    .get_queryset()
474                    .filter(V::Model::primary_key().eq(id))
475                    .first_in(tx)
476                    .await?
477                    .ok_or(AppError::NotFound)?;
478                Ok(Some(V::Serializer::to_json(item)?))
479            })
480        })
481        .await?;
482    let status = if action == ViewAction::Create {
483        StatusCode::CREATED
484    } else if payload.is_some() {
485        StatusCode::OK
486    } else {
487        StatusCode::NO_CONTENT
488    };
489    Ok(match payload {
490        Some(payload) => (status, Json(payload)).into_response(),
491        None => status.into_response(),
492    })
493}