refactor(lifecycle hooks): simplify integration of new services
* make more coherent lifecycles
* remove specific implementation on different handlers (they do not need to know existence of ThumbnailSerice nor AudioMetadataService)
* reduce risk of orphean objects
* ensure additional services are correctly wired (ex: Thumbnail generation was not covering all upload cases)
* more details on docs/architecture/file-and-blob-lifecycle.md :
```rust
// application/ports/file_lifecycle.rs
pub trait FileLifecycleHook {
fn on_file_created(file_id, blob_hash, content_type, is_new_blob);
fn on_file_updated(file_id, blob_hash, content_type);
fn on_file_copied(file_id, blob_hash, content_type, source_id)
fn on_file_deleted(file_id);
}
// application/ports/blob_lifecycle.rs
pub trait BlobLifecycleHook {
fn on_blob_created(blob_hash, content_type);
fn on_blob_deleted(blob_hash);
}
```
This commit is contained in:
Edouard Vanbelle
@@ -1,35 +1,26 @@
|
||||
use std::future::Future;
|
||||
use std::pin::Pin;
|
||||
/// Observer notified by [`DedupService`] when a blob is stored for the first
|
||||
/// time or permanently removed (ref_count reaches zero).
|
||||
///
|
||||
/// Register with [`BlobLifecycleService`] during DI wiring; it fans out to all
|
||||
/// registered hooks. Every implementor **must** provide both methods —
|
||||
/// use an explicit one-liner noop for events the implementor does not care about.
|
||||
/// This forces conscious acknowledgement of every lifecycle event rather than
|
||||
/// silent omission.
|
||||
///
|
||||
/// All methods are synchronous. Background work must be spawned inside the
|
||||
/// implementor via `tokio::spawn`; the calling service never awaits hook
|
||||
/// completion.
|
||||
pub trait BlobLifecycleHook: Send + Sync {
|
||||
/// Called after a genuinely new blob has been written to storage (no dedup
|
||||
/// hit — first time this content hash is seen).
|
||||
///
|
||||
/// `blob_hash` — BLAKE3 hex identifying the blob.
|
||||
/// `content_type` — MIME type if known at write time, `None` otherwise.
|
||||
fn on_blob_created(&self, blob_hash: &str, content_type: Option<&str>);
|
||||
|
||||
/// Observer notified by [`DedupService`] when a genuinely new blob is stored
|
||||
/// for the first time (no dedup hit).
|
||||
///
|
||||
/// Register with [`DedupService::add_blob_creation_hook`] during DI wiring.
|
||||
pub trait BlobCreationHook: Send + Sync {
|
||||
/// Called after the new blob's chunks and manifest have been written.
|
||||
/// `blob_hash` is the BLAKE3 hex, `content_type` is the MIME type if known.
|
||||
/// Must be best-effort — must not propagate errors.
|
||||
fn on_blob_created<'a>(
|
||||
&'a self,
|
||||
blob_hash: &'a str,
|
||||
content_type: Option<&'a str>,
|
||||
) -> Pin<Box<dyn Future<Output = ()> + Send + 'a>>;
|
||||
}
|
||||
/// Observer notified by [`DedupService`] when a blob's ref_count reaches zero
|
||||
/// and it is permanently removed from storage.
|
||||
///
|
||||
/// Implement this trait on any service that needs to react to blob deletion
|
||||
/// (e.g. thumbnail cleanup, CDN invalidation, audit logging). Register with
|
||||
/// [`DedupService::add_blob_hook`] during DI wiring.
|
||||
///
|
||||
/// The boxed-future return keeps the trait dyn-compatible so multiple
|
||||
/// implementations can be stored as `Vec<Arc<dyn BlobDeletionHook>>`.
|
||||
pub trait BlobDeletionHook: Send + Sync {
|
||||
/// Called after the blob file has been removed from disk.
|
||||
/// `blob_hash` is the BLAKE3 hex string identifying the blob.
|
||||
/// Must be best-effort — must not propagate errors.
|
||||
fn on_blob_deleted<'a>(
|
||||
&'a self,
|
||||
blob_hash: &'a str,
|
||||
) -> Pin<Box<dyn Future<Output = ()> + Send + 'a>>;
|
||||
/// Called after a blob's ref_count reaches zero and it has been permanently
|
||||
/// removed from storage.
|
||||
///
|
||||
/// `blob_hash` — BLAKE3 hex identifying the (now deleted) blob.
|
||||
fn on_blob_deleted(&self, blob_hash: &str);
|
||||
}
|
||||
|
||||
@@ -1,57 +1,71 @@
|
||||
use std::future::Future;
|
||||
use std::pin::Pin;
|
||||
|
||||
/// Observer notified by [`FileUploadService`] when a new file record is created
|
||||
/// (including dedup hits where the blob already exists).
|
||||
/// Observer notified by file services when a file record is created, copied,
|
||||
/// updated, or permanently deleted.
|
||||
///
|
||||
/// Register with [`FileUploadService::with_file_created_hook`] during DI wiring.
|
||||
pub trait FileCreatedHook: Send + Sync {
|
||||
/// Called after the file record has been persisted.
|
||||
/// `file_id` — opaque file UUID string.
|
||||
/// `blob_hash` — BLAKE3 hex of the blob (may already exist on disk for dedup hits).
|
||||
/// `content_type` — MIME type of the content.
|
||||
/// Must be best-effort — must not propagate errors.
|
||||
fn on_file_created<'a>(
|
||||
&'a self,
|
||||
file_id: &'a str,
|
||||
blob_hash: &'a str,
|
||||
content_type: &'a str,
|
||||
) -> Pin<Box<dyn Future<Output = ()> + Send + 'a>>;
|
||||
}
|
||||
|
||||
/// Observer notified by [`FileUploadService`] when an existing file's blob is
|
||||
/// replaced (WebDAV PUT overwrite, WOPI PutFile, Nextcloud chunked upload).
|
||||
/// Register with [`FileLifecycleService`] during DI wiring; it fans out to all
|
||||
/// registered hooks. Every implementor **must** provide all four methods —
|
||||
/// use an explicit one-liner noop for events the implementor does not care about.
|
||||
/// This forces conscious acknowledgement of every lifecycle event rather than
|
||||
/// silent omission.
|
||||
///
|
||||
/// Implement this trait on any service that needs to react to a content swap
|
||||
/// (e.g. thumbnail invalidation + regeneration, search index update).
|
||||
/// Register with [`FileUploadService::with_file_updated_hook`] during DI wiring.
|
||||
///
|
||||
/// The boxed-future return keeps the trait dyn-compatible so multiple
|
||||
/// implementations can be stored as `Vec<Arc<dyn FileUpdatedHook>>`.
|
||||
pub trait FileUpdatedHook: Send + Sync {
|
||||
/// Called after the new blob has been stored and the file record updated.
|
||||
/// All methods are synchronous. Background work must be spawned inside the
|
||||
/// implementor via `tokio::spawn`; the calling service never awaits hook
|
||||
/// completion.
|
||||
pub trait FileLifecycleHook: Send + Sync {
|
||||
/// Called after a new file record has been persisted.
|
||||
///
|
||||
/// `file_id` is an opaque file UUID string, `blob_hash` is the BLAKE3 hex
|
||||
/// of the new blob, `content_type` is the MIME type of the new content.
|
||||
/// Must be best-effort — must not propagate errors.
|
||||
fn on_file_updated<'a>(
|
||||
&'a self,
|
||||
file_id: &'a str,
|
||||
blob_hash: &'a str,
|
||||
content_type: &'a str,
|
||||
) -> Pin<Box<dyn Future<Output = ()> + Send + 'a>>;
|
||||
}
|
||||
|
||||
/// Observer notified by [`FileManagementService`] when a file is permanently
|
||||
/// deleted (either directly or after being emptied from trash).
|
||||
///
|
||||
/// Register with [`FileManagementService::with_file_deleted_hook`] during DI wiring.
|
||||
pub trait FileDeletedHook: Send + Sync {
|
||||
/// Called after the file record has been removed.
|
||||
/// `file_id` — opaque file UUID string.
|
||||
/// Must be best-effort — must not propagate errors.
|
||||
fn on_file_deleted<'a>(
|
||||
&'a self,
|
||||
file_id: &'a str,
|
||||
) -> Pin<Box<dyn Future<Output = ()> + Send + 'a>>;
|
||||
/// `blob_hash` — BLAKE3 hex of the content blob.
|
||||
/// `content_type` — MIME type.
|
||||
/// `is_new_blob` — `true` if the blob was stored for the first time (no
|
||||
/// dedup hit); `false` if the blob already existed (re-upload of identical
|
||||
/// content). Implementors can use this to skip re-generating artefacts that
|
||||
/// are keyed by `blob_hash` and already exist on disk.
|
||||
///
|
||||
/// For explicit file copies use [`on_file_copied`] instead — it supplies
|
||||
/// the source file id so per-file metadata can be cloned directly.
|
||||
fn on_file_created(
|
||||
&self,
|
||||
file_id: &str,
|
||||
blob_hash: &str,
|
||||
content_type: &str,
|
||||
is_new_blob: bool,
|
||||
);
|
||||
|
||||
/// Called after a file has been created as an explicit copy of an existing file.
|
||||
///
|
||||
/// `file_id` — opaque file UUID string of the **new** copy.
|
||||
/// `blob_hash` — BLAKE3 hex of the shared content blob.
|
||||
/// `content_type` — MIME type.
|
||||
/// `source_file_id` — opaque file UUID string of the **original** file.
|
||||
///
|
||||
/// Implementors may use `source_file_id` to efficiently clone per-file
|
||||
/// metadata (audio tags, etc.) from the original rather than re-deriving
|
||||
/// it from the blob. If the original has not yet been processed, fall back
|
||||
/// to a blob-hash-based lookup or schedule a retry — the implementor owns
|
||||
/// race handling.
|
||||
fn on_file_copied(
|
||||
&self,
|
||||
file_id: &str,
|
||||
blob_hash: &str,
|
||||
content_type: &str,
|
||||
source_file_id: &str,
|
||||
);
|
||||
|
||||
/// Called after an existing file's blob has been replaced (WebDAV PUT
|
||||
/// overwrite, WOPI PutFile, Nextcloud chunked upload finalization).
|
||||
///
|
||||
/// `file_id` — opaque file UUID string.
|
||||
/// `blob_hash` — BLAKE3 hex of the **new** blob.
|
||||
/// `content_type` — MIME type of the new content.
|
||||
fn on_file_updated(&self, file_id: &str, blob_hash: &str, content_type: &str);
|
||||
|
||||
/// Called after a file record has been permanently removed (direct delete
|
||||
/// or emptied from trash).
|
||||
///
|
||||
/// NOTE: due to deduplication the blob may still exist if other files
|
||||
/// reference it. Use [`BlobLifecycleHook::on_blob_deleted`] when your
|
||||
/// side-effect is content-addressed (e.g. removing blob-keyed thumbnails).
|
||||
///
|
||||
/// `file_id` — opaque file UUID string.
|
||||
fn on_file_deleted(&self, file_id: &str);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user