Skip to main content

che_rest/
media.rs

1//! File-backed image fields. Model columns store only relative keys; application
2//! code retains control over who may upload or clear a particular model field.
3use std::{
4    any::Any, collections::HashMap, fs, future::Future, io::Cursor, path::PathBuf, pin::Pin,
5};
6
7use axum::{
8    Extension, Router,
9    body::{Body, Bytes},
10    extract::{Multipart, Path as AxumPath, multipart::Field},
11    http::{StatusCode, header},
12    response::{IntoResponse, Response},
13    routing::get,
14};
15use che_orm::{ImageField, Model, ModelField, ModelSerializer, ValidatedWrite};
16use image::{GenericImageView, ImageFormat, ImageReader, Limits};
17use rand::RngCore;
18
19use crate::{
20    ApiSchema, ApiSchemaDefinition, AppError, AppModule, AppResult, AppState, CurrentPrincipal,
21    ExtensionContext, ModuleContext, MutationHook, OperationSpec, Permission, RestQuerySet,
22    ViewAction, ViewSet, ViewSetConfig, ViewSetExtension,
23};
24
25#[derive(Clone, Debug)]
26pub struct ImagePolicy {
27    pub directory: &'static str,
28    pub max_bytes: usize,
29    pub max_dimension: u32,
30    /// Optionally produce a bounded PNG instead of retaining the input bytes.
31    pub thumbnail: Option<u32>,
32}
33
34impl ImagePolicy {
35    pub const fn new(directory: &'static str, max_bytes: usize, max_dimension: u32) -> Self {
36        Self {
37            directory,
38            max_bytes,
39            max_dimension,
40            thumbnail: None,
41        }
42    }
43
44    pub const fn thumbnail(mut self, max_dimension: u32) -> Self {
45        self.thumbnail = Some(max_dimension);
46        self
47    }
48}
49
50pub struct ImageStorage {
51    root: PathBuf,
52}
53
54/// Read a multipart image field with an explicit per-field limit. Callers own
55/// authorization and any other fields in the multipart form.
56pub async fn read_image_field(field: Field<'_>, max_bytes: usize) -> AppResult<axum::body::Bytes> {
57    let bytes = field
58        .bytes()
59        .await
60        .map_err(|error| AppError::BadRequest(error.to_string()))?;
61    if bytes.is_empty() || bytes.len() > max_bytes {
62        return Err(AppError::BadRequest(
63            "image exceeds the allowed size".into(),
64        ));
65    }
66    Ok(bytes)
67}
68
69pub type ImageGuard = Box<dyn Any + Send>;
70pub type ImageFuture<'a, T> = Pin<Box<dyn Future<Output = AppResult<T>> + Send + 'a>>;
71
72/// File plus application-owned multipart data (for example, a scene version).
73pub struct ImageForm {
74    pub file: Option<Bytes>,
75    pub file_name: Option<String>,
76    pub content_type: Option<String>,
77    pub fields: HashMap<String, Bytes>,
78}
79
80impl ImageForm {
81    pub fn field(&self, name: &str) -> Option<&[u8]> {
82        self.fields.get(name).map(Bytes::as_ref)
83    }
84
85    pub fn text(&self, name: &str) -> AppResult<Option<&str>> {
86        self.field(name)
87            .map(|bytes| {
88                std::str::from_utf8(bytes)
89                    .map_err(|_| AppError::BadRequest(format!("invalid {name}")))
90            })
91            .transpose()
92    }
93}
94
95async fn parse_image_form(mut multipart: Multipart, max_bytes: usize) -> AppResult<ImageForm> {
96    let mut form = ImageForm {
97        file: None,
98        file_name: None,
99        content_type: None,
100        fields: HashMap::new(),
101    };
102    while let Some(field) = multipart
103        .next_field()
104        .await
105        .map_err(|error| AppError::BadRequest(error.to_string()))?
106    {
107        let name = field
108            .name()
109            .ok_or_else(|| AppError::BadRequest("unnamed multipart field".into()))?
110            .to_owned();
111        if name == "file" {
112            if form.file.is_some() {
113                return Err(AppError::BadRequest("duplicate file".into()));
114            }
115            form.file_name = field.file_name().map(str::to_owned);
116            form.content_type = field.content_type().map(str::to_owned);
117            form.file = Some(read_image_field(field, max_bytes).await?);
118        } else {
119            let bytes = field
120                .bytes()
121                .await
122                .map_err(|error| AppError::BadRequest(error.to_string()))?;
123            if bytes.len() > 64 * 1024 || form.fields.insert(name, bytes).is_some() {
124                return Err(AppError::BadRequest("invalid multipart field".into()));
125            }
126        }
127    }
128    Ok(form)
129}
130
131pub type ImageAuthorize<V> = for<'a> fn(
132    crate::PermissionContext<'a>,
133    Option<&'a CurrentPrincipal>,
134    &'a <V as ViewSet>::Model,
135    ViewAction,
136) -> ImageFuture<'a, ()>;
137pub type ImageBefore<V> = for<'a> fn(
138    &'a AppState,
139    &'a <V as ViewSet>::Model,
140    &'a ImageForm,
141) -> ImageFuture<'a, ImageGuard>;
142pub type ImageWrite<V> = fn(
143    &AppState,
144    &<V as ViewSet>::Model,
145    Option<&ImageField>,
146    usize,
147    ValidatedWrite<<V as ViewSet>::Model>,
148) -> AppResult<ValidatedWrite<<V as ViewSet>::Model>>;
149
150type ImageState<V> =
151    for<'a> fn(&'a V, &'a AppState, Option<&'a CurrentPrincipal>) -> ImageFuture<'a, AppState>;
152
153fn model_sync_image_state<'a, V: crate::SyncViewSet>(
154    viewset: &'a V,
155    state: &'a AppState,
156    principal: Option<&'a CurrentPrincipal>,
157) -> ImageFuture<'a, AppState>
158where
159    V::Model: che_orm::SyncModel,
160{
161    Box::pin(crate::sync::model_media_state(viewset, state, principal))
162}
163
164/// Explicit protocol-2 image adapter. CAS writes use the configured model-log
165/// database, so the image metadata and its journal operation commit together.
166#[derive(Clone)]
167pub struct ModelSyncImageFieldEndpoint<V: ViewSet>(ImageFieldEndpoint<V>);
168/// Protocol-2 image creation with journal-aware domain callback transactions.
169pub struct ModelSyncImageCreateEndpoint<
170    V: ViewSet,
171    R: ApiSchema + serde::Serialize + Send + Sync + 'static,
172>(ImageCreateEndpoint<V, R>);
173
174impl<V: ViewSet, R: ApiSchema + serde::Serialize + Send + Sync + 'static> Clone
175    for ModelSyncImageCreateEndpoint<V, R>
176{
177    fn clone(&self) -> Self {
178        Self(self.0.clone())
179    }
180}
181
182/// Declares automatic upload/replace and clear actions for a nullable image
183/// field of an existing ViewSet model.
184pub struct ImageFieldEndpoint<V: ViewSet> {
185    pub name: &'static str,
186    pub column: ModelField<V::Model, Option<ImageField>>,
187    pub image: for<'a> fn(&'a V::Model) -> Option<&'a ImageField>,
188    pub policy: ImagePolicy,
189    pub authorize: Option<ImageAuthorize<V>>,
190    pub before: Option<ImageBefore<V>>,
191    pub write: Option<ImageWrite<V>>,
192    prepare_state: Option<ImageState<V>>,
193}
194
195impl<V: ViewSet> Clone for ImageFieldEndpoint<V> {
196    fn clone(&self) -> Self {
197        Self {
198            name: self.name,
199            column: self.field(),
200            image: self.image,
201            policy: self.policy.clone(),
202            authorize: self.authorize,
203            before: self.before,
204            write: self.write,
205            prepare_state: self.prepare_state,
206        }
207    }
208}
209
210impl<V: ViewSet> ImageFieldEndpoint<V> {
211    fn field(&self) -> ModelField<V::Model, Option<ImageField>> {
212        let column = self.column.column();
213        ModelField::new(column.table, column.name)
214    }
215    pub fn new(
216        name: &'static str,
217        column: ModelField<V::Model, Option<ImageField>>,
218        image: for<'a> fn(&'a V::Model) -> Option<&'a ImageField>,
219        policy: ImagePolicy,
220    ) -> Self {
221        Self {
222            name,
223            column,
224            image,
225            policy,
226            authorize: None,
227            before: None,
228            write: None,
229            prepare_state: None,
230        }
231    }
232
233    pub fn authorize(mut self, callback: ImageAuthorize<V>) -> Self {
234        self.authorize = Some(callback);
235        self
236    }
237    pub fn before(mut self, callback: ImageBefore<V>) -> Self {
238        self.before = Some(callback);
239        self
240    }
241    pub fn write(mut self, callback: ImageWrite<V>) -> Self {
242        self.write = Some(callback);
243        self
244    }
245
246    pub fn model_sync(mut self) -> ModelSyncImageFieldEndpoint<V>
247    where
248        V: crate::SyncViewSet,
249        V::Model: che_orm::SyncModel,
250    {
251        self.prepare_state = Some(model_sync_image_state::<V>);
252        ModelSyncImageFieldEndpoint(self)
253    }
254
255    async fn model(
256        &self,
257        state: &AppState,
258        viewset: &V,
259        principal: Option<&CurrentPrincipal>,
260        id: <V::Model as Model>::PrimaryKey,
261    ) -> AppResult<V::Model> {
262        V::Permission::default()
263            .check_request(state.into(), principal, ViewAction::Update)
264            .await?;
265        {
266            let item = viewset
267                .get_queryset()
268                .filter(V::Model::primary_key().eq(id))
269                .first(state.database())
270                .await?
271                .ok_or(AppError::NotFound)?;
272            V::Permission::default()
273                .check_object(
274                    state.into(),
275                    principal,
276                    ViewAction::Update,
277                    V::QuerySet::item_model(&item),
278                )
279                .await?;
280        }
281        let model = state
282            .database()
283            .get::<V::Model>(id)
284            .await?
285            .ok_or(AppError::NotFound)?;
286        if let Some(authorize) = self.authorize {
287            authorize(state.into(), principal, &model, ViewAction::Update).await?;
288        }
289        Ok(model)
290    }
291
292    async fn persist(
293        &self,
294        state: &AppState,
295        principal: Option<&CurrentPrincipal>,
296        id: <V::Model as Model>::PrimaryKey,
297        previous: &V::Model,
298        next: Option<ImageField>,
299        size: usize,
300    ) -> AppResult<()> {
301        let column = self.field();
302        let condition = match (self.image)(previous) {
303            Some(image) => column.eq(Some(image.clone())),
304            None => column.is_null(),
305        };
306        let write = ValidatedWrite::Update(
307            V::Model::update()
308                .filter(V::Model::primary_key().eq(id))
309                .filter(condition),
310        )
311        .set(self.field(), next.clone());
312        let owned_state = state.clone();
313        let principal = principal.cloned();
314        let callback = self.authorize;
315        let prepare = self.write;
316        let saved = state
317            .database()
318            .transaction_result(move |tx| {
319                Box::pin(async move {
320                    let model = tx.get::<V::Model>(id).await?.ok_or(AppError::NotFound)?;
321                    let context = crate::PermissionContext::in_transaction(&owned_state, tx);
322                    if let Some(callback) = callback {
323                        callback(context, principal.as_ref(), &model, ViewAction::Update).await?;
324                    }
325                    let write = match prepare {
326                        Some(callback) => {
327                            callback(&owned_state, &model, next.as_ref(), size, write)?
328                        }
329                        None => write,
330                    };
331                    V::Permission::default()
332                        .check_write(
333                            context,
334                            principal.as_ref(),
335                            ViewAction::Update,
336                            Some(&model),
337                            Some(&write),
338                        )
339                        .await?;
340                    Ok::<_, AppError>(write.save_in(tx).await?.is_some())
341                })
342            })
343            .await?;
344        if !saved {
345            return Err(image_update_conflict::<V::Model>(state, id).await?);
346        }
347        Ok(())
348    }
349
350    async fn replace(
351        &self,
352        state: AppState,
353        viewset: V,
354        principal: Option<CurrentPrincipal>,
355        id: <V::Model as Model>::PrimaryKey,
356        multipart: Multipart,
357    ) -> AppResult<axum::Json<ImageUploadResponse>> {
358        let state = match self.prepare_state {
359            Some(prepare) => prepare(&viewset, &state, principal.as_ref()).await?,
360            None => state,
361        };
362        let form = parse_image_form(multipart, self.policy.max_bytes).await?;
363        let bytes = form
364            .file
365            .as_ref()
366            .ok_or_else(|| AppError::BadRequest("file is required".into()))?;
367        let model = self.model(&state, &viewset, principal.as_ref(), id).await?;
368        let _guard = match self.before {
369            Some(callback) => callback(&state, &model, &form).await?,
370            None => Box::new(()),
371        };
372        let storage = ImageStorage::from_state(&state);
373        let image = storage.save(bytes, &self.policy)?;
374        if let Err(error) = self
375            .persist(
376                &state,
377                principal.as_ref(),
378                id,
379                &model,
380                Some(image.clone()),
381                bytes.len(),
382            )
383            .await
384        {
385            let _ = storage.remove(&image);
386            return Err(error);
387        }
388        if let Some(previous) = (self.image)(&model) {
389            let _ = storage.remove(previous);
390        }
391        Ok(axum::Json(ImageUploadResponse {
392            url: url(&image, &state.config.server.api_prefix),
393            key: image.key().to_owned(),
394        }))
395    }
396
397    async fn clear(
398        &self,
399        state: AppState,
400        viewset: V,
401        principal: Option<CurrentPrincipal>,
402        id: <V::Model as Model>::PrimaryKey,
403        multipart: Multipart,
404    ) -> AppResult<StatusCode> {
405        let state = match self.prepare_state {
406            Some(prepare) => prepare(&viewset, &state, principal.as_ref()).await?,
407            None => state,
408        };
409        let form = parse_image_form(multipart, self.policy.max_bytes).await?;
410        if form.file.is_some() {
411            return Err(AppError::BadRequest(
412                "file is not allowed when clearing an image".into(),
413            ));
414        }
415        let model = self.model(&state, &viewset, principal.as_ref(), id).await?;
416        let _guard = match self.before {
417            Some(callback) => callback(&state, &model, &form).await?,
418            None => Box::new(()),
419        };
420        self.persist(&state, principal.as_ref(), id, &model, None, 0)
421            .await?;
422        if let Some(previous) = (self.image)(&model) {
423            let _ = ImageStorage::from_state(&state).remove(previous);
424        }
425        Ok(StatusCode::NO_CONTENT)
426    }
427}
428
429#[derive(serde::Serialize)]
430pub struct ImageUploadResponse {
431    pub key: String,
432    pub url: String,
433}
434
435impl ApiSchema for ImageUploadResponse {
436    fn api_schema() -> ApiSchemaDefinition {
437        ApiSchemaDefinition {
438            name: "ImageUploadResponse",
439            openapi: serde_json::json!({"type":"object", "properties":{"key":{"type":"string"}, "url":{"type":"string"}}, "required":["key","url"]}),
440            typescript: "export interface ImageUploadResponse { key: string; url: string; }",
441        }
442    }
443}
444
445impl<V: ViewSet> ViewSetExtension<V> for ImageFieldEndpoint<V> {
446    const ID: &'static str = "image-field";
447
448    fn install(self, context: &mut ExtensionContext<'_, V>) -> AppResult<()> {
449        let endpoint = std::sync::Arc::new(self);
450        let path = format!("{{id}}/images/{}", endpoint.name);
451        let operation = format!("{}.image.{}", context_id::<V>(), endpoint.name);
452        context.route(&path, |route| {
453            let upload = endpoint.clone();
454            route.put(
455                move |Extension(state): Extension<AppState>,
456                      Extension(viewset): Extension<V>,
457                      who: Option<Extension<CurrentPrincipal>>,
458                      AxumPath(id): AxumPath<<V::Model as Model>::PrimaryKey>,
459                      form: Multipart| {
460                    let endpoint = upload.clone();
461                    async move {
462                        endpoint
463                            .replace(state, viewset, who.map(|value| value.0), id, form)
464                            .await
465                    }
466                },
467                OperationSpec::new(format!("{operation}.replace"))
468                    .authenticated()
469                    .multipart()
470                    .body_limit(endpoint.policy.max_bytes + 128 * 1024)
471                    .response::<ImageUploadResponse>(StatusCode::OK)
472                    .client(endpoint.name, "replace"),
473            )?;
474            let clear = endpoint.clone();
475            route.delete(
476                move |Extension(state): Extension<AppState>,
477                      Extension(viewset): Extension<V>,
478                      who: Option<Extension<CurrentPrincipal>>,
479                      AxumPath(id): AxumPath<<V::Model as Model>::PrimaryKey>,
480                      form: Multipart| {
481                    let endpoint = clear.clone();
482                    async move {
483                        endpoint
484                            .clear(state, viewset, who.map(|value| value.0), id, form)
485                            .await
486                    }
487                },
488                OperationSpec::new(format!("{operation}.clear"))
489                    .authenticated()
490                    .multipart()
491                    .body_limit(128 * 1024)
492                    .client(endpoint.name, "clear"),
493            )
494        })
495    }
496}
497
498fn context_id<V: ViewSet>() -> &'static str {
499    std::any::type_name::<V>()
500}
501
502pub type ImageCreateAuthorize =
503    for<'a> fn(&'a AppState, Option<&'a CurrentPrincipal>, &'a ImageForm) -> ImageFuture<'a, ()>;
504pub type ImageCreateAction<R> = for<'a> fn(
505    &'a AppState,
506    Option<&'a CurrentPrincipal>,
507    &'a ImageField,
508    &'a ImageForm,
509) -> ImageFuture<'a, R>;
510
511/// Generates a multipart image creation endpoint for an application-owned
512/// image record and any associated links. The callback owns domain writes;
513/// failed callbacks cause the newly saved file to be removed.
514pub struct ImageCreateEndpoint<V: ViewSet, R: ApiSchema + serde::Serialize + Send + Sync + 'static>
515{
516    pub policy: ImagePolicy,
517    pub authorize: ImageCreateAuthorize,
518    pub create: ImageCreateAction<R>,
519    pub namespace: &'static str,
520    pub method: &'static str,
521    prepare_state: Option<ImageState<V>>,
522    _marker: std::marker::PhantomData<fn() -> V>,
523}
524
525impl<V: ViewSet, R: ApiSchema + serde::Serialize + Send + Sync + 'static> Clone
526    for ImageCreateEndpoint<V, R>
527{
528    fn clone(&self) -> Self {
529        Self {
530            policy: self.policy.clone(),
531            authorize: self.authorize,
532            create: self.create,
533            namespace: self.namespace,
534            method: self.method,
535            prepare_state: self.prepare_state,
536            _marker: std::marker::PhantomData,
537        }
538    }
539}
540
541impl<V: ViewSet, R: ApiSchema + serde::Serialize + Send + Sync + 'static>
542    ImageCreateEndpoint<V, R>
543{
544    pub fn new(
545        policy: ImagePolicy,
546        authorize: ImageCreateAuthorize,
547        create: ImageCreateAction<R>,
548        namespace: &'static str,
549        method: &'static str,
550    ) -> Self {
551        Self {
552            policy,
553            authorize,
554            create,
555            namespace,
556            method,
557            prepare_state: None,
558            _marker: std::marker::PhantomData,
559        }
560    }
561
562    pub fn model_sync(mut self) -> ModelSyncImageCreateEndpoint<V, R>
563    where
564        V: crate::SyncViewSet,
565        V::Model: che_orm::SyncModel,
566    {
567        self.prepare_state = Some(model_sync_image_state::<V>);
568        ModelSyncImageCreateEndpoint(self)
569    }
570
571    async fn upload(
572        &self,
573        state: AppState,
574        viewset: V,
575        who: Option<CurrentPrincipal>,
576        multipart: Multipart,
577    ) -> AppResult<(StatusCode, axum::Json<R>)> {
578        let state = match self.prepare_state {
579            Some(prepare) => prepare(&viewset, &state, who.as_ref()).await?,
580            None => state,
581        };
582        let form = parse_image_form(multipart, self.policy.max_bytes).await?;
583        V::Permission::default()
584            .check_request((&state).into(), who.as_ref(), ViewAction::Create)
585            .await?;
586        (self.authorize)(&state, who.as_ref(), &form).await?;
587        let bytes = form
588            .file
589            .as_ref()
590            .ok_or_else(|| AppError::BadRequest("file is required".into()))?;
591        let storage = ImageStorage::from_state(&state);
592        let image = storage.save(bytes, &self.policy)?;
593        match (self.create)(&state, who.as_ref(), &image, &form).await {
594            Ok(value) => Ok((StatusCode::CREATED, axum::Json(value))),
595            Err(error) => {
596                let _ = storage.remove(&image);
597                Err(error)
598            }
599        }
600    }
601}
602
603impl<V: ViewSet, R: ApiSchema + serde::Serialize + Send + Sync + 'static> ViewSetExtension<V>
604    for ImageCreateEndpoint<V, R>
605{
606    const ID: &'static str = "image-create";
607
608    fn install(self, context: &mut ExtensionContext<'_, V>) -> AppResult<()> {
609        let endpoint = std::sync::Arc::new(self);
610        context.route("upload", |route| {
611            let upload = endpoint.clone();
612            route.post(
613                move |Extension(state): Extension<AppState>,
614                      Extension(viewset): Extension<V>,
615                      who: Option<Extension<CurrentPrincipal>>,
616                      form: Multipart| {
617                    let endpoint = upload.clone();
618                    async move {
619                        endpoint
620                            .upload(state, viewset, who.map(|value| value.0), form)
621                            .await
622                    }
623                },
624                OperationSpec::new(format!("{}.image.create", context_id::<V>()))
625                    .authenticated()
626                    .multipart()
627                    .body_limit(endpoint.policy.max_bytes + 128 * 1024)
628                    .response::<R>(StatusCode::CREATED)
629                    .client(endpoint.namespace, endpoint.method),
630            )
631        })
632    }
633}
634
635impl<V: crate::SyncViewSet> ViewSetExtension<V> for ModelSyncImageFieldEndpoint<V>
636where
637    V::Model: che_orm::SyncModel,
638{
639    const ID: &'static str = "model-sync-image-field";
640    fn install(self, context: &mut ExtensionContext<'_, V>) -> AppResult<()> {
641        self.0.install(context)
642    }
643}
644impl<V: crate::SyncViewSet, R: ApiSchema + serde::Serialize + Send + Sync + 'static>
645    ViewSetExtension<V> for ModelSyncImageCreateEndpoint<V, R>
646where
647    V::Model: che_orm::SyncModel,
648{
649    const ID: &'static str = "model-sync-image-create";
650    fn install(self, context: &mut ExtensionContext<'_, V>) -> AppResult<()> {
651        self.0.install(context)
652    }
653}
654
655impl<V: ViewSet> ViewSetConfig<V> {
656    pub fn image_field(&mut self, field: ImageFieldEndpoint<V>) -> AppResult<()> {
657        self.extend(field)
658    }
659}
660
661impl ImageStorage {
662    pub fn new(root: impl Into<PathBuf>) -> Self {
663        Self { root: root.into() }
664    }
665
666    pub fn from_state(state: &AppState) -> Self {
667        Self::new(&state.config.media.root)
668    }
669
670    /// Store and attach a replacement only after validation succeeds. If the
671    /// database write fails, discard the new file and leave the old one intact.
672    pub async fn replace<M: Model + Send + 'static>(
673        &self,
674        state: &AppState,
675        id: M::PrimaryKey,
676        column: ModelField<M, Option<ImageField>>,
677        previous: Option<&ImageField>,
678        bytes: &[u8],
679        policy: &ImagePolicy,
680    ) -> AppResult<ImageField> {
681        self.replace_with(
682            state,
683            id,
684            column,
685            previous,
686            bytes,
687            policy,
688            |_image, write| Ok(write),
689        )
690        .await
691    }
692
693    /// Compare-and-swap the image key and optional server-owned metadata in one
694    /// database update. A losing request removes its own file, not the winner's.
695    #[expect(
696        clippy::too_many_arguments,
697        reason = "Keep the public replacement API consistent with replace, adding only the metadata callback"
698    )]
699    pub async fn replace_with<M, F>(
700        &self,
701        state: &AppState,
702        id: M::PrimaryKey,
703        column: ModelField<M, Option<ImageField>>,
704        previous: Option<&ImageField>,
705        bytes: &[u8],
706        policy: &ImagePolicy,
707        prepare: F,
708    ) -> AppResult<ImageField>
709    where
710        M: Model + Send + 'static,
711        F: FnOnce(&ImageField, ValidatedWrite<M>) -> AppResult<ValidatedWrite<M>>,
712    {
713        let next = self.save(bytes, policy)?;
714        let result = async {
715            let reference = column.column();
716            let condition: che_orm::Expr = match previous {
717                Some(image) => {
718                    ModelField::<M, Option<ImageField>>::new(reference.table, reference.name)
719                        .eq(Some(image.clone()))
720                }
721                None => ModelField::<M, Option<ImageField>>::new(reference.table, reference.name)
722                    .is_null(),
723            };
724            let write = ValidatedWrite::Update(
725                M::update()
726                    .filter(M::primary_key().eq(id))
727                    .filter(condition),
728            )
729            .set(column, Some(next.clone()));
730            if prepare(&next, write)?
731                .save(state.database())
732                .await?
733                .is_none()
734            {
735                return Err(image_update_conflict::<M>(state, id).await?);
736            }
737            Ok::<_, AppError>(())
738        }
739        .await;
740        if let Err(error) = result {
741            let _ = self.remove(&next);
742            return Err(error);
743        }
744        if let Some(old) = previous {
745            // The database is already committed. Defer failed file cleanup
746            // rather than reporting a failed replacement to the client.
747            let _ = self.remove(old);
748        }
749        Ok(next)
750    }
751
752    pub async fn clear<M: Model + Send + 'static>(
753        &self,
754        state: &AppState,
755        id: M::PrimaryKey,
756        column: ModelField<M, Option<ImageField>>,
757        previous: Option<&ImageField>,
758    ) -> AppResult<()> {
759        self.clear_with(state, id, column, previous, Ok).await
760    }
761
762    pub async fn clear_with<M, F>(
763        &self,
764        state: &AppState,
765        id: M::PrimaryKey,
766        column: ModelField<M, Option<ImageField>>,
767        previous: Option<&ImageField>,
768        prepare: F,
769    ) -> AppResult<()>
770    where
771        M: Model + Send + 'static,
772        F: FnOnce(ValidatedWrite<M>) -> AppResult<ValidatedWrite<M>>,
773    {
774        let reference = column.column();
775        let condition: che_orm::Expr = match previous {
776            Some(image) => {
777                ModelField::<M, Option<ImageField>>::new(reference.table, reference.name)
778                    .eq(Some(image.clone()))
779            }
780            None => {
781                ModelField::<M, Option<ImageField>>::new(reference.table, reference.name).is_null()
782            }
783        };
784        if prepare(
785            ValidatedWrite::Update(
786                M::update()
787                    .filter(M::primary_key().eq(id))
788                    .filter(condition),
789            )
790            .set(column, None::<ImageField>),
791        )?
792        .save(state.database())
793        .await?
794        .is_none()
795        {
796            return Err(image_update_conflict::<M>(state, id).await?);
797        }
798        if let Some(old) = previous {
799            let _ = self.remove(old);
800        }
801        Ok(())
802    }
803
804    pub fn save(&self, bytes: &[u8], policy: &ImagePolicy) -> AppResult<ImageField> {
805        if bytes.is_empty() || bytes.len() > policy.max_bytes || !safe_key(policy.directory) {
806            return Err(AppError::BadRequest(
807                "invalid image size or directory".into(),
808            ));
809        }
810        let format = image::guess_format(bytes)
811            .map_err(|_| AppError::BadRequest("unsupported image".into()))?;
812        if !matches!(
813            format,
814            ImageFormat::Png | ImageFormat::Jpeg | ImageFormat::Gif | ImageFormat::WebP
815        ) {
816            return Err(AppError::BadRequest("unsupported image format".into()));
817        }
818        let mut reader = ImageReader::with_format(Cursor::new(bytes), format);
819        let mut limits = Limits::default();
820        limits.max_image_width = Some(policy.max_dimension);
821        limits.max_image_height = Some(policy.max_dimension);
822        limits.max_alloc = Some(256 * 1024 * 1024);
823        reader.limits(limits);
824        let decoded = reader
825            .decode()
826            .map_err(|_| AppError::BadRequest("invalid image".into()))?;
827        let (width, height) = decoded.dimensions();
828        if width == 0 || height == 0 {
829            return Err(AppError::BadRequest("empty image".into()));
830        }
831        let (contents, extension) = if let Some(maximum) = policy.thumbnail {
832            if maximum == 0 {
833                return Err(AppError::BadRequest("invalid thumbnail size".into()));
834            }
835            let resized = decoded.thumbnail(maximum, maximum);
836            let mut output = Cursor::new(Vec::new());
837            resized
838                .write_to(&mut output, ImageFormat::Png)
839                .map_err(|_| AppError::BadRequest("could not encode image".into()))?;
840            (output.into_inner(), "png")
841        } else {
842            (
843                bytes.to_vec(),
844                match format {
845                    ImageFormat::Png => "png",
846                    ImageFormat::Jpeg => "jpg",
847                    ImageFormat::Gif => "gif",
848                    ImageFormat::WebP => "webp",
849                    _ => unreachable!(),
850                },
851            )
852        };
853        if contents.len() > policy.max_bytes {
854            return Err(AppError::BadRequest("processed image is too large".into()));
855        }
856        let directory = self.root.join(policy.directory);
857        fs::create_dir_all(&directory).map_err(AppError::Io)?;
858        let mut random = [0_u8; 16];
859        rand::thread_rng().fill_bytes(&mut random);
860        let name = format!("{}.{extension}", hex::encode(random));
861        let key = format!("{}/{}", policy.directory, name);
862        let path = self.root.join(&key);
863        let mut file = fs::OpenOptions::new()
864            .write(true)
865            .create_new(true)
866            .open(&path)
867            .map_err(AppError::Io)?;
868        use std::io::Write;
869        if let Err(error) = file.write_all(&contents) {
870            drop(file);
871            let _ = fs::remove_file(path);
872            return Err(AppError::Io(error));
873        }
874        if let Err(error) = self.retry_pending_cleanup() {
875            eprintln!("image cleanup retry failed: {error}");
876        }
877        Ok(ImageField::new(key))
878    }
879
880    pub fn remove(&self, image: &ImageField) -> AppResult<()> {
881        let path = self.path(image)?;
882        match fs::remove_file(path) {
883            Ok(()) => Ok(()),
884            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
885            Err(error) => {
886                if let Err(queue_error) = self.queue_cleanup(image) {
887                    eprintln!(
888                        "could not queue image cleanup for {}: {queue_error}",
889                        image.key()
890                    );
891                }
892                Err(AppError::Io(error))
893            }
894        }
895    }
896
897    fn cleanup_queue(&self) -> PathBuf {
898        self.root.join(".pending-image-deletions")
899    }
900
901    fn queue_cleanup(&self, image: &ImageField) -> std::io::Result<()> {
902        let directory = self.cleanup_queue();
903        fs::create_dir_all(&directory)?;
904        let mut random = [0_u8; 16];
905        rand::thread_rng().fill_bytes(&mut random);
906        let identifier = hex::encode(random);
907        let temporary = directory.join(format!("{identifier}.tmp"));
908        let final_path = directory.join(format!("{identifier}.key"));
909        let result = (|| {
910            use std::io::Write;
911            let mut file = fs::OpenOptions::new()
912                .write(true)
913                .create_new(true)
914                .open(&temporary)?;
915            file.write_all(image.key().as_bytes())?;
916            file.sync_all()?;
917            fs::rename(&temporary, &final_path)
918        })();
919        if result.is_err() {
920            let _ = fs::remove_file(&temporary);
921        }
922        result
923    }
924
925    /// Retry removals which failed after the corresponding database mutation.
926    pub fn retry_pending_cleanup(&self) -> AppResult<usize> {
927        let entries = match fs::read_dir(self.cleanup_queue()) {
928            Ok(entries) => entries,
929            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(0),
930            Err(error) => return Err(AppError::Io(error)),
931        };
932        let mut completed = 0;
933        for entry in entries {
934            let entry = entry.map_err(AppError::Io)?;
935            if entry
936                .path()
937                .extension()
938                .is_none_or(|extension| extension != "key")
939            {
940                continue;
941            }
942            let key = fs::read_to_string(entry.path()).map_err(AppError::Io)?;
943            let image = ImageField::new(key);
944            let path = match self.path(&image) {
945                Ok(path) => path,
946                Err(error) => {
947                    eprintln!(
948                        "invalid pending image cleanup entry {}: {error}",
949                        entry.path().display()
950                    );
951                    continue;
952                }
953            };
954            match fs::remove_file(path) {
955                Ok(()) => {}
956                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
957                Err(error) => {
958                    eprintln!("pending image cleanup for {} failed: {error}", image.key());
959                    continue;
960                }
961            }
962            match fs::remove_file(entry.path()) {
963                Ok(()) => {}
964                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
965                Err(error) => return Err(AppError::Io(error)),
966            }
967            completed += 1;
968        }
969        Ok(completed)
970    }
971
972    pub fn read(&self, image: &ImageField) -> AppResult<(Vec<u8>, &'static str)> {
973        let path = self.path(image)?;
974        let media_type = match path.extension().and_then(|value| value.to_str()) {
975            Some("png") => "image/png",
976            Some("jpg") => "image/jpeg",
977            Some("gif") => "image/gif",
978            Some("webp") => "image/webp",
979            _ => return Err(AppError::BadRequest("unsupported image extension".into())),
980        };
981        Ok((fs::read(path).map_err(AppError::Io)?, media_type))
982    }
983
984    fn path(&self, image: &ImageField) -> AppResult<PathBuf> {
985        if !safe_key(image.key()) {
986            return Err(AppError::BadRequest("invalid image key".into()));
987        }
988        Ok(self.root.join(image.key()))
989    }
990}
991
992async fn image_update_conflict<M: Model + Send + 'static>(
993    state: &AppState,
994    id: M::PrimaryKey,
995) -> AppResult<AppError> {
996    Ok(if state.database().get::<M>(id).await?.is_some() {
997        AppError::Conflict("image has changed".into())
998    } else {
999        AppError::NotFound
1000    })
1001}
1002
1003/// Cleans up an image after a ViewSet deletes its owning row.
1004pub struct ImageCleanup<V: ViewSet> {
1005    pub id: &'static str,
1006    pub image: for<'a> fn(&'a V::Model) -> Option<&'a ImageField>,
1007}
1008
1009impl<V: ViewSet> MutationHook<V> for ImageCleanup<V> {
1010    fn id(&self) -> &'static str {
1011        self.id
1012    }
1013
1014    fn prepare_delete(&self, model: &V::Model) -> serde_json::Value {
1015        (self.image)(model)
1016            .map(|image| serde_json::json!(image.key()))
1017            .unwrap_or(serde_json::Value::Null)
1018    }
1019
1020    fn after_delete(&self, state: &AppState, payload: &serde_json::Value) -> AppResult<()> {
1021        if let Some(key) = payload.as_str() {
1022            ImageStorage::from_state(state).remove(&ImageField::new(key))?;
1023        }
1024        Ok(())
1025    }
1026}
1027
1028pub fn url(image: &ImageField, api_prefix: &str) -> String {
1029    format!("{}/media/{}", api_prefix.trim_end_matches('/'), image.key())
1030}
1031
1032fn safe_key(key: &str) -> bool {
1033    !key.is_empty()
1034        && key.split('/').all(|segment| {
1035            !segment.is_empty()
1036                && segment != "."
1037                && segment != ".."
1038                && segment
1039                    .bytes()
1040                    .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
1041        })
1042}
1043
1044pub struct MediaModule;
1045pub fn module() -> MediaModule {
1046    MediaModule
1047}
1048impl AppModule for MediaModule {
1049    fn name(&self) -> &'static str {
1050        "media"
1051    }
1052    fn schema(&self) -> che_orm::SchemaSet {
1053        che_orm::SchemaSet::new()
1054    }
1055    fn init(&self, context: &mut ModuleContext) {
1056        context.route(Router::new().route("/media/{*key}", get(download_image)));
1057    }
1058
1059    fn start(&self, state: &AppState) {
1060        if let Err(error) = ImageStorage::from_state(state).retry_pending_cleanup() {
1061            eprintln!("image cleanup retry failed on startup: {error}");
1062        }
1063    }
1064}
1065
1066async fn download_image(
1067    Extension(state): Extension<AppState>,
1068    Extension(media_access): Extension<MediaAccess>,
1069    current: Option<Extension<CurrentPrincipal>>,
1070    AxumPath(key): AxumPath<String>,
1071) -> Response {
1072    if current.is_none() {
1073        return StatusCode::UNAUTHORIZED.into_response();
1074    }
1075    let (strict, readers) = {
1076        let registry = media_access.read().expect("media access registry");
1077        (registry.strict, registry.readers.clone())
1078    };
1079    if strict {
1080        let principal = &current.as_ref().expect("authenticated above").0;
1081        let mut allowed = false;
1082        for reader in readers {
1083            match reader(&state, principal, &key).await {
1084                Ok(true) => {
1085                    allowed = true;
1086                    break;
1087                }
1088                Ok(false) => {}
1089                Err(error) => return error.into_response(),
1090            }
1091        }
1092        if !allowed {
1093            return StatusCode::NOT_FOUND.into_response();
1094        }
1095    }
1096    let Ok((bytes, media_type)) = ImageStorage::from_state(&state).read(&ImageField::new(key))
1097    else {
1098        return StatusCode::NOT_FOUND.into_response();
1099    };
1100    let mut response = Response::new(Body::from(bytes));
1101    response.headers_mut().insert(
1102        header::CONTENT_TYPE,
1103        header::HeaderValue::from_static(media_type),
1104    );
1105    response.headers_mut().insert(
1106        header::X_CONTENT_TYPE_OPTIONS,
1107        header::HeaderValue::from_static("nosniff"),
1108    );
1109    response.headers_mut().insert(
1110        header::CACHE_CONTROL,
1111        header::HeaderValue::from_static("private, no-store"),
1112    );
1113    response
1114}
1115
1116#[cfg(all(test, feature = "sqlite"))]
1117mod tests {
1118    use super::*;
1119    use axum::http::Request;
1120    use che_orm::{Database, DatabaseQuery, Model, ModelSerializer};
1121    use tower::ServiceExt;
1122
1123    #[derive(Debug, Model)]
1124    #[orm(table = "image_cleanup_items")]
1125    struct ImageItem {
1126        #[orm(primary_key)]
1127        id: i64,
1128        image: Option<ImageField>,
1129    }
1130
1131    #[derive(Debug, Model)]
1132    #[orm(table = "image_metadata_items")]
1133    struct ImageMetadataItem {
1134        #[orm(primary_key)]
1135        id: i64,
1136        image: Option<ImageField>,
1137        url: Option<String>,
1138    }
1139
1140    #[derive(ModelSerializer)]
1141    #[serializer(model = ImageItem)]
1142    struct ImageItemSerializer {
1143        #[serializer(read_only)]
1144        id: i64,
1145        #[serializer(read_only)]
1146        image: Option<ImageField>,
1147    }
1148
1149    #[derive(Clone)]
1150    struct ImageViewSet;
1151
1152    impl ViewSet for ImageViewSet {
1153        type Model = ImageItem;
1154        type Serializer = ImageItemSerializer;
1155        type ListSerializer = Self::Serializer;
1156        type QuerySet = DatabaseQuery<ImageItem>;
1157        type FilterSet = crate::FilterSet<ImageItem>;
1158        type Permission = crate::AllowAny;
1159
1160        fn get_queryset(&self) -> Self::QuerySet {
1161            DatabaseQuery::new(ImageItem::query())
1162        }
1163        fn path(&self) -> &'static str {
1164            "/image-items"
1165        }
1166        fn signal_access(&self, action: ViewAction) -> Option<crate::SignalAccess> {
1167            (action == ViewAction::Delete).then_some(crate::SignalAccess::Authenticated)
1168        }
1169    }
1170
1171    #[test]
1172    fn image_field_validates_resizes_and_stays_inside_storage_root() {
1173        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1174        let storage = ImageStorage::new(&root);
1175        let mut png = Cursor::new(Vec::new());
1176        image::DynamicImage::new_rgb8(24, 12)
1177            .write_to(&mut png, ImageFormat::Png)
1178            .unwrap();
1179        let policy = ImagePolicy::new("previews", 1024 * 1024, 100).thumbnail(8);
1180        let field = storage.save(&png.into_inner(), &policy).unwrap();
1181        assert!(field.key().starts_with("previews/"));
1182        let (bytes, media_type) = storage.read(&field).unwrap();
1183        assert_eq!(media_type, "image/png");
1184        assert_eq!(
1185            image::load_from_memory(&bytes).unwrap().dimensions(),
1186            (8, 4)
1187        );
1188        assert!(storage.read(&ImageField::new("../outside.png")).is_err());
1189        assert!(storage.save(b"not an image", &policy).is_err());
1190        storage.remove(&field).unwrap();
1191        assert!(storage.read(&field).is_err());
1192        fs::remove_dir_all(root).unwrap();
1193    }
1194
1195    #[test]
1196    fn failed_post_commit_deletion_is_queued_and_retried() {
1197        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1198        let storage = ImageStorage::new(&root);
1199        let path = root.join("avatars/blocked.png");
1200        fs::create_dir_all(&path).unwrap();
1201        let key = ImageField::new("avatars/blocked.png");
1202        assert!(storage.remove(&key).is_err());
1203        assert_eq!(
1204            fs::read_dir(root.join(".pending-image-deletions"))
1205                .unwrap()
1206                .count(),
1207            1
1208        );
1209        fs::remove_dir(path).unwrap();
1210        assert_eq!(storage.retry_pending_cleanup().unwrap(), 1);
1211        assert_eq!(
1212            fs::read_dir(root.join(".pending-image-deletions"))
1213                .unwrap()
1214                .count(),
1215            0
1216        );
1217        fs::remove_dir_all(root).unwrap();
1218    }
1219
1220    #[tokio::test]
1221    async fn viewset_deletion_removes_owned_image_after_database_delete() {
1222        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1223        let mut state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1224        state.config.media.root = root.to_string_lossy().into_owned();
1225        state.database().create_table::<ImageItem>().await.unwrap();
1226        let mut png = Cursor::new(Vec::new());
1227        image::DynamicImage::new_rgb8(1, 1)
1228            .write_to(&mut png, ImageFormat::Png)
1229            .unwrap();
1230        let storage = ImageStorage::from_state(&state);
1231        let image = storage
1232            .save(
1233                &png.into_inner(),
1234                &ImagePolicy::new("items", 1024 * 1024, 10),
1235            )
1236            .unwrap();
1237        let item = state
1238            .database()
1239            .create::<ImageItem>()
1240            .set(ImageItem::IMAGE, Some(image.clone()))
1241            .execute()
1242            .await
1243            .unwrap();
1244        let hooks: Vec<std::sync::Arc<dyn MutationHook<ImageViewSet>>> =
1245            vec![std::sync::Arc::new(ImageCleanup::<ImageViewSet> {
1246                id: "item-image",
1247                image: |item| item.image.as_ref(),
1248            })];
1249        let app = crate::rest::router::router_with_hooks(
1250            state.clone(),
1251            ImageViewSet,
1252            Router::new(),
1253            hooks,
1254        );
1255        let result = app
1256            .oneshot(
1257                Request::builder()
1258                    .method("DELETE")
1259                    .uri(format!("/image-items/{}/", item.id))
1260                    .body(Body::empty())
1261                    .unwrap(),
1262            )
1263            .await
1264            .unwrap();
1265        assert_eq!(result.status(), StatusCode::NO_CONTENT);
1266        assert!(
1267            state
1268                .database()
1269                .get::<ImageItem>(item.id)
1270                .await
1271                .unwrap()
1272                .is_none()
1273        );
1274        assert!(storage.read(&image).is_err());
1275        fs::remove_dir_all(root).unwrap();
1276    }
1277
1278    #[tokio::test]
1279    async fn failed_post_commit_cleanup_does_not_fail_delete_or_suppress_signal() {
1280        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1281        let mut state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1282        state.config.media.root = root.to_string_lossy().into_owned();
1283        state.database().create_table::<ImageItem>().await.unwrap();
1284        let image = ImageField::new("items/blocked.png");
1285        let blocked = root.join(image.key());
1286        fs::create_dir_all(&blocked).unwrap();
1287        let item = state
1288            .database()
1289            .create::<ImageItem>()
1290            .set(ImageItem::IMAGE, Some(image))
1291            .execute()
1292            .await
1293            .unwrap();
1294        let hooks: Vec<std::sync::Arc<dyn MutationHook<ImageViewSet>>> =
1295            vec![std::sync::Arc::new(ImageCleanup::<ImageViewSet> {
1296                id: "item-image",
1297                image: |item| item.image.as_ref(),
1298            })];
1299        let mut receiver = state.signals().subscribe("image-items.deleted");
1300        let app = crate::rest::router::router_with_hooks(
1301            state.clone(),
1302            ImageViewSet,
1303            Router::new(),
1304            hooks,
1305        );
1306        let response = app
1307            .oneshot(
1308                Request::builder()
1309                    .method("DELETE")
1310                    .uri(format!("/image-items/{}/", item.id))
1311                    .body(Body::empty())
1312                    .unwrap(),
1313            )
1314            .await
1315            .unwrap();
1316        assert_eq!(response.status(), StatusCode::NO_CONTENT);
1317        assert!(
1318            state
1319                .database()
1320                .get::<ImageItem>(item.id)
1321                .await
1322                .unwrap()
1323                .is_none()
1324        );
1325        assert_eq!(receiver.try_recv().unwrap()["id"], item.id);
1326        assert_eq!(
1327            fs::read_dir(root.join(".pending-image-deletions"))
1328                .unwrap()
1329                .count(),
1330            1
1331        );
1332        fs::remove_dir(blocked).unwrap();
1333        assert_eq!(
1334            ImageStorage::from_state(&state)
1335                .retry_pending_cleanup()
1336                .unwrap(),
1337            1
1338        );
1339        fs::remove_dir_all(root).unwrap();
1340    }
1341
1342    #[tokio::test]
1343    async fn replace_discards_image_when_model_disappears() {
1344        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1345        let mut state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1346        state.config.media.root = root.to_string_lossy().into_owned();
1347        state.database().create_table::<ImageItem>().await.unwrap();
1348        let mut png = Cursor::new(Vec::new());
1349        image::DynamicImage::new_rgb8(1, 1)
1350            .write_to(&mut png, ImageFormat::Png)
1351            .unwrap();
1352        let result = ImageStorage::from_state(&state)
1353            .replace::<ImageItem>(
1354                &state,
1355                42,
1356                ImageItem::IMAGE,
1357                None,
1358                &png.into_inner(),
1359                &ImagePolicy::new("items", 1024 * 1024, 10),
1360            )
1361            .await;
1362        assert!(matches!(result, Err(AppError::NotFound)));
1363        assert_eq!(fs::read_dir(root.join("items")).unwrap().count(), 0);
1364        fs::remove_dir_all(root).unwrap();
1365    }
1366
1367    #[tokio::test]
1368    async fn stale_replacement_and_clear_cannot_overwrite_winner_or_leave_files() {
1369        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1370        let mut state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1371        state.config.media.root = root.to_string_lossy().into_owned();
1372        state.database().create_table::<ImageItem>().await.unwrap();
1373        let item = state
1374            .database()
1375            .create::<ImageItem>()
1376            .set(ImageItem::IMAGE, None::<ImageField>)
1377            .execute()
1378            .await
1379            .unwrap();
1380        let storage = ImageStorage::from_state(&state);
1381        let mut png = Cursor::new(Vec::new());
1382        image::DynamicImage::new_rgb8(1, 1)
1383            .write_to(&mut png, ImageFormat::Png)
1384            .unwrap();
1385        let policy = ImagePolicy::new("items", 1024 * 1024, 10);
1386        let winner = storage
1387            .replace(
1388                &state,
1389                item.id,
1390                ImageItem::IMAGE,
1391                None,
1392                png.get_ref(),
1393                &policy,
1394            )
1395            .await
1396            .unwrap();
1397        assert!(matches!(
1398            storage
1399                .replace(
1400                    &state,
1401                    item.id,
1402                    ImageItem::IMAGE,
1403                    None,
1404                    png.get_ref(),
1405                    &policy
1406                )
1407                .await,
1408            Err(AppError::Conflict(_))
1409        ));
1410        assert!(matches!(
1411            storage.clear(&state, item.id, ImageItem::IMAGE, None).await,
1412            Err(AppError::Conflict(_))
1413        ));
1414        assert_eq!(
1415            state
1416                .database()
1417                .get::<ImageItem>(item.id)
1418                .await
1419                .unwrap()
1420                .unwrap()
1421                .image
1422                .as_ref(),
1423            Some(&winner)
1424        );
1425        assert_eq!(fs::read_dir(root.join("items")).unwrap().count(), 1);
1426        storage
1427            .clear(&state, item.id, ImageItem::IMAGE, Some(&winner))
1428            .await
1429            .unwrap();
1430        assert_eq!(fs::read_dir(root.join("items")).unwrap().count(), 0);
1431        fs::remove_dir_all(root).unwrap();
1432    }
1433
1434    #[tokio::test]
1435    async fn conditional_image_and_metadata_update_commit_together() {
1436        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1437        let mut state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1438        state.config.media.root = root.to_string_lossy().into_owned();
1439        state
1440            .database()
1441            .create_table::<ImageMetadataItem>()
1442            .await
1443            .unwrap();
1444        let item = state
1445            .database()
1446            .create::<ImageMetadataItem>()
1447            .set(ImageMetadataItem::IMAGE, None::<ImageField>)
1448            .set(ImageMetadataItem::URL, None::<String>)
1449            .execute()
1450            .await
1451            .unwrap();
1452        let mut png = Cursor::new(Vec::new());
1453        image::DynamicImage::new_rgb8(1, 1)
1454            .write_to(&mut png, ImageFormat::Png)
1455            .unwrap();
1456        let storage = ImageStorage::from_state(&state);
1457        let policy = ImagePolicy::new("items", 1024 * 1024, 10);
1458        let write = |image: &ImageField, pending: ValidatedWrite<ImageMetadataItem>| {
1459            Ok(pending.set(ImageMetadataItem::URL, Some(image.key().to_owned())))
1460        };
1461        let winner = storage
1462            .replace_with(
1463                &state,
1464                item.id,
1465                ImageMetadataItem::IMAGE,
1466                None,
1467                png.get_ref(),
1468                &policy,
1469                write,
1470            )
1471            .await
1472            .unwrap();
1473        assert!(matches!(
1474            storage
1475                .replace_with(
1476                    &state,
1477                    item.id,
1478                    ImageMetadataItem::IMAGE,
1479                    None,
1480                    png.get_ref(),
1481                    &policy,
1482                    write
1483                )
1484                .await,
1485            Err(AppError::Conflict(_))
1486        ));
1487        let actual = state
1488            .database()
1489            .get::<ImageMetadataItem>(item.id)
1490            .await
1491            .unwrap()
1492            .unwrap();
1493        assert_eq!(actual.image.as_ref(), Some(&winner));
1494        assert_eq!(actual.url.as_deref(), Some(winner.key()));
1495        assert_eq!(fs::read_dir(root.join("items")).unwrap().count(), 1);
1496        fs::remove_dir_all(root).unwrap();
1497    }
1498
1499    #[tokio::test]
1500    async fn replacement_succeeds_when_old_file_cleanup_must_be_queued() {
1501        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1502        let mut state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1503        state.config.media.root = root.to_string_lossy().into_owned();
1504        state.database().create_table::<ImageItem>().await.unwrap();
1505        let old = ImageField::new("items/blocked.png");
1506        let blocked = root.join(old.key());
1507        fs::create_dir_all(&blocked).unwrap();
1508        let item = state
1509            .database()
1510            .create::<ImageItem>()
1511            .set(ImageItem::IMAGE, Some(old.clone()))
1512            .execute()
1513            .await
1514            .unwrap();
1515        let mut png = Cursor::new(Vec::new());
1516        image::DynamicImage::new_rgb8(1, 1)
1517            .write_to(&mut png, ImageFormat::Png)
1518            .unwrap();
1519        let storage = ImageStorage::from_state(&state);
1520        let image = storage
1521            .replace(
1522                &state,
1523                item.id,
1524                ImageItem::IMAGE,
1525                Some(&old),
1526                png.get_ref(),
1527                &ImagePolicy::new("items", 1024 * 1024, 10),
1528            )
1529            .await
1530            .unwrap();
1531        assert_eq!(
1532            state
1533                .database()
1534                .get::<ImageItem>(item.id)
1535                .await
1536                .unwrap()
1537                .unwrap()
1538                .image
1539                .as_ref(),
1540            Some(&image)
1541        );
1542        assert_eq!(
1543            fs::read_dir(root.join(".pending-image-deletions"))
1544                .unwrap()
1545                .count(),
1546            1
1547        );
1548        fs::remove_dir(blocked).unwrap();
1549        assert_eq!(storage.retry_pending_cleanup().unwrap(), 1);
1550        storage.remove(&image).unwrap();
1551        fs::remove_dir_all(root).unwrap();
1552    }
1553
1554    #[tokio::test]
1555    async fn nested_media_keys_are_captured_without_a_leading_slash() {
1556        let router = Router::new().route(
1557            "/media/{*key}",
1558            get(|AxumPath(key): AxumPath<String>| async move { key }),
1559        );
1560        let response = router
1561            .oneshot(
1562                Request::builder()
1563                    .uri("/media/avatars/photo.png")
1564                    .body(Body::empty())
1565                    .unwrap(),
1566            )
1567            .await
1568            .unwrap();
1569        assert_eq!(response.status(), StatusCode::OK);
1570        let body = axum::body::to_bytes(response.into_body(), 1024)
1571            .await
1572            .unwrap();
1573        assert_eq!(&body[..], b"avatars/photo.png");
1574    }
1575
1576    #[tokio::test]
1577    async fn media_route_requires_authentication() {
1578        let state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1579        let router = Router::new()
1580            .route("/media/{*key}", get(download_image))
1581            .layer(Extension(state))
1582            .layer(Extension(MediaAccess::default()));
1583        let response = router
1584            .oneshot(
1585                Request::builder()
1586                    .uri("/media/avatars/photo.png")
1587                    .body(Body::empty())
1588                    .unwrap(),
1589            )
1590            .await
1591            .unwrap();
1592        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
1593    }
1594
1595    #[tokio::test]
1596    async fn declared_image_field_uploads_replaces_and_clears() {
1597        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1598        let mut state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1599        state.config.media.root = root.to_string_lossy().into_owned();
1600        state.database().create_table::<ImageItem>().await.unwrap();
1601        let item = state
1602            .database()
1603            .create::<ImageItem>()
1604            .set(ImageItem::IMAGE, None::<ImageField>)
1605            .execute()
1606            .await
1607            .unwrap();
1608        let mut config = ViewSetConfig::<ImageViewSet>::new("/image-items");
1609        config
1610            .image_field(ImageFieldEndpoint::<ImageViewSet>::new(
1611                "photo",
1612                ImageItem::IMAGE,
1613                |item: &ImageItem| item.image.as_ref(),
1614                ImagePolicy::new("photos", 1024 * 1024, 32),
1615            ))
1616            .unwrap();
1617        let (extensions, metadata, _, hooks) = config.into_parts();
1618        assert_eq!(metadata[0].operations.len(), 2);
1619        assert_eq!(
1620            metadata[0].operations[0].path,
1621            "/image-items/{id}/images/photo/"
1622        );
1623        assert!(metadata[0].operations[0].multipart);
1624        assert_eq!(
1625            metadata[0].operations[0].openapi["requestBody"]["content"]["multipart/form-data"]["schema"]
1626                ["required"][0],
1627            "file"
1628        );
1629        assert!(metadata[0].operations[1].openapi["requestBody"]["content"]["multipart/form-data"]["schema"]["properties"].is_null());
1630        let app =
1631            crate::rest::router::router_with_hooks(state.clone(), ImageViewSet, extensions, hooks);
1632        let mut png = Cursor::new(Vec::new());
1633        image::DynamicImage::new_rgb8(2, 2)
1634            .write_to(&mut png, ImageFormat::Png)
1635            .unwrap();
1636        let multipart = |file: Option<&[u8]>| {
1637            let mut data = Vec::new();
1638            if let Some(file) = file {
1639                data.extend_from_slice(b"--test\r\nContent-Disposition: form-data; name=\"file\"; filename=\"photo.png\"\r\nContent-Type: image/png\r\n\r\n");
1640                data.extend_from_slice(file);
1641                data.extend_from_slice(b"\r\n");
1642            }
1643            data.extend_from_slice(b"--test--\r\n");
1644            data
1645        };
1646        let path = format!("/image-items/{}/images/photo/", item.id);
1647        let request = |method, data| {
1648            Request::builder()
1649                .method(method)
1650                .uri(&path)
1651                .header("Content-Type", "multipart/form-data; boundary=test")
1652                .body(Body::from(data))
1653                .unwrap()
1654        };
1655        let response = app
1656            .clone()
1657            .oneshot(request("PUT", multipart(Some(&png.get_ref()[..]))))
1658            .await
1659            .unwrap();
1660        assert_eq!(response.status(), StatusCode::OK);
1661        let first = state
1662            .database()
1663            .get::<ImageItem>(item.id)
1664            .await
1665            .unwrap()
1666            .unwrap()
1667            .image
1668            .unwrap();
1669        assert!(ImageStorage::from_state(&state).read(&first).is_ok());
1670        let response = app
1671            .clone()
1672            .oneshot(request("PUT", multipart(Some(&png.get_ref()[..]))))
1673            .await
1674            .unwrap();
1675        assert_eq!(response.status(), StatusCode::OK);
1676        let next = state
1677            .database()
1678            .get::<ImageItem>(item.id)
1679            .await
1680            .unwrap()
1681            .unwrap()
1682            .image
1683            .unwrap();
1684        assert_ne!(next, first);
1685        assert!(ImageStorage::from_state(&state).read(&first).is_err());
1686        let response = app
1687            .oneshot(request("DELETE", multipart(None)))
1688            .await
1689            .unwrap();
1690        assert_eq!(response.status(), StatusCode::NO_CONTENT);
1691        assert!(
1692            state
1693                .database()
1694                .get::<ImageItem>(item.id)
1695                .await
1696                .unwrap()
1697                .unwrap()
1698                .image
1699                .is_none()
1700        );
1701        assert!(ImageStorage::from_state(&state).read(&next).is_err());
1702        fs::remove_dir_all(root).unwrap();
1703    }
1704
1705    #[derive(serde::Serialize)]
1706    struct CreatedImage {
1707        key: String,
1708    }
1709
1710    impl ApiSchema for CreatedImage {
1711        fn api_schema() -> ApiSchemaDefinition {
1712            ApiSchemaDefinition {
1713                name: "CreatedImage",
1714                openapi: serde_json::json!({"type":"object","properties":{"key":{"type":"string"}},"required":["key"]}),
1715                typescript: "export interface CreatedImage { key: string; }",
1716            }
1717        }
1718    }
1719
1720    fn authorize_create<'a>(
1721        _state: &'a AppState,
1722        _who: Option<&'a CurrentPrincipal>,
1723        form: &'a ImageForm,
1724    ) -> ImageFuture<'a, ()> {
1725        Box::pin(async move {
1726            if form.text("target")? != Some("allowed") {
1727                return Err(AppError::Forbidden("invalid target".into()));
1728            }
1729            Ok(())
1730        })
1731    }
1732
1733    fn create_image<'a>(
1734        _state: &'a AppState,
1735        _who: Option<&'a CurrentPrincipal>,
1736        image: &'a ImageField,
1737        form: &'a ImageForm,
1738    ) -> ImageFuture<'a, CreatedImage> {
1739        Box::pin(async move {
1740            if form.text("fail")? == Some("true") {
1741                return Err(AppError::BadRequest("invalid link".into()));
1742            }
1743            Ok(CreatedImage {
1744                key: image.key().into(),
1745            })
1746        })
1747    }
1748
1749    #[tokio::test]
1750    async fn declared_image_creation_checks_domain_data_and_cleans_failed_uploads() {
1751        let root = std::env::temp_dir().join(format!("che-rest-media-{}", rand::random::<u64>()));
1752        let mut state = AppState::from_database(Database::connect_in_memory().await.unwrap());
1753        state.config.media.root = root.to_string_lossy().into_owned();
1754        let mut config = ViewSetConfig::<ImageViewSet>::new("/image-items");
1755        config
1756            .extend(ImageCreateEndpoint::<ImageViewSet, CreatedImage>::new(
1757                ImagePolicy::new("items", 1024 * 1024, 10),
1758                authorize_create,
1759                create_image,
1760                "upload",
1761                "image",
1762            ))
1763            .unwrap();
1764        let (extensions, operations, _, hooks) = config.into_parts();
1765        assert_eq!(operations[0].operations[0].path, "/image-items/upload/");
1766        let app =
1767            crate::rest::router::router_with_hooks(state.clone(), ImageViewSet, extensions, hooks);
1768        let mut png = Cursor::new(Vec::new());
1769        image::DynamicImage::new_rgb8(1, 1)
1770            .write_to(&mut png, ImageFormat::Png)
1771            .unwrap();
1772        let form = |target: &str, fail: bool| {
1773            let mut data = format!(
1774                "--test\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\n{target}\r\n"
1775            )
1776            .into_bytes();
1777            if fail {
1778                data.extend_from_slice(
1779                    b"--test\r\nContent-Disposition: form-data; name=\"fail\"\r\n\r\ntrue\r\n",
1780                );
1781            }
1782            data.extend_from_slice(b"--test\r\nContent-Disposition: form-data; name=\"file\"; filename=\"a.png\"\r\nContent-Type: image/png\r\n\r\n");
1783            data.extend_from_slice(png.get_ref());
1784            data.extend_from_slice(b"\r\n--test--\r\n");
1785            Request::builder()
1786                .method("POST")
1787                .uri("/image-items/upload/")
1788                .header("Content-Type", "multipart/form-data; boundary=test")
1789                .body(Body::from(data))
1790                .unwrap()
1791        };
1792        assert_eq!(
1793            app.clone()
1794                .oneshot(form("denied", false))
1795                .await
1796                .unwrap()
1797                .status(),
1798            StatusCode::FORBIDDEN
1799        );
1800        assert_eq!(
1801            app.clone()
1802                .oneshot(form("allowed", true))
1803                .await
1804                .unwrap()
1805                .status(),
1806            StatusCode::BAD_REQUEST
1807        );
1808        assert_eq!(fs::read_dir(root.join("items")).unwrap().count(), 0);
1809        assert_eq!(
1810            app.oneshot(form("allowed", false)).await.unwrap().status(),
1811            StatusCode::CREATED
1812        );
1813        assert_eq!(fs::read_dir(root.join("items")).unwrap().count(), 1);
1814        fs::remove_dir_all(root).unwrap();
1815    }
1816}
1817
1818/// A registry belongs to one router build, never to the reusable application state.
1819pub(crate) type MediaAccess = std::sync::Arc<std::sync::RwLock<MediaAccessRegistry>>;
1820type MediaReader = std::sync::Arc<
1821    dyn for<'a> Fn(&'a AppState, &'a CurrentPrincipal, &'a str) -> ImageFuture<'a, bool>
1822        + Send
1823        + Sync,
1824>;
1825#[derive(Default)]
1826pub(crate) struct MediaAccessRegistry {
1827    strict: bool,
1828    readers: Vec<MediaReader>,
1829}
1830pub(crate) fn register_media_access<V: ViewSet>(
1831    registry: &MediaAccess,
1832    viewset: V,
1833    hooks: crate::rest::router::MutationHooks<V>,
1834) {
1835    let mut registry = registry.write().expect("media access registry");
1836    registry.strict |= V::Permission::default().object_scoped();
1837    if V::Serializer::fields()
1838        .iter()
1839        .any(|field| !field.write_only && field.rust_type.contains("ImageField"))
1840    {
1841        let reader: MediaReader = std::sync::Arc::new(move |state, principal, key| {
1842            let viewset = viewset.clone();
1843            let hooks = hooks.clone();
1844            Box::pin(
1845                async move { can_download::<V>(state, principal, key, &viewset, &hooks).await },
1846            )
1847        });
1848        registry.readers.push(reader);
1849    }
1850}
1851fn can_download<'a, V: ViewSet>(
1852    state: &'a AppState,
1853    principal: &'a CurrentPrincipal,
1854    key: &'a str,
1855    viewset: &'a V,
1856    hooks: &'a crate::rest::router::MutationHooks<V>,
1857) -> ImageFuture<'a, bool> {
1858    Box::pin(async move {
1859        let schema = V::Model::schema();
1860        let mut image_filter: Option<che_orm::Expr> = None;
1861        for field in V::Serializer::fields()
1862            .iter()
1863            .filter(|field| !field.write_only && field.rust_type.contains("ImageField"))
1864        {
1865            let Some(column) = schema
1866                .columns
1867                .iter()
1868                .find(|column| column.name == field.source || column.field_name == field.source)
1869            else {
1870                continue;
1871            };
1872            let filter = che_orm::Expr::Compare {
1873                left: Box::new(che_orm::Expr::Column(che_orm::ColumnRef::new(
1874                    V::Model::table_name(),
1875                    column.name,
1876                ))),
1877                op: che_orm::CompareOp::Eq,
1878                right: Box::new(che_orm::Expr::Value(che_orm::DatabaseValue::Text(
1879                    key.into(),
1880                ))),
1881            };
1882            image_filter = Some(match image_filter {
1883                Some(previous) => previous.or(filter),
1884                None => filter,
1885            });
1886        }
1887        let Some(filter) = image_filter else {
1888            return Ok(false);
1889        };
1890        let permission = V::Permission::default();
1891        match permission
1892            .check_request(state.into(), Some(principal), ViewAction::Retrieve)
1893            .await
1894        {
1895            Err(AppError::Unauthorized(_) | AppError::Forbidden(_)) => return Ok(false),
1896            result => result?,
1897        }
1898        let query = match hooks
1899            .scoped_queryset(state, viewset, Some(principal), ViewAction::Retrieve)
1900            .await
1901        {
1902            Ok(query) => query.filter(filter),
1903            Err(AppError::Unauthorized(_) | AppError::Forbidden(_)) => return Ok(false),
1904            Err(error) => return Err(error),
1905        };
1906        // Use exactly the REST queryset, including instance-owned restrictions,
1907        // relation loading, and mutation backend read filters.
1908        for item in query.all(state.database()).await? {
1909            match permission
1910                .check_object(
1911                    state.into(),
1912                    Some(principal),
1913                    ViewAction::Retrieve,
1914                    V::QuerySet::item_model(&item),
1915                )
1916                .await
1917            {
1918                Ok(()) => return Ok(true),
1919                Err(AppError::Unauthorized(_) | AppError::Forbidden(_)) => {}
1920                Err(error) => return Err(error),
1921            }
1922        }
1923        Ok(false)
1924    })
1925}