Module region_hook 

Region hook extension point for observing SST writes and manifest mutations.

Design

The RegionHook trait provides two methods with clear separation of concerns:

• on_sst_files_written: Fires when mito2 physically writes SST data files. Provides per-file SstInfo + FileMeta — the richest available metadata (row counts, index metadata, Parquet metadata, etc.).

• on_manifest_updated: Fires after any manifest write is successfully committed. Receives the full RegionMetaActionList so consumers can inspect what changed (file additions/removals, schema changes, truncation, partition expression changes, etc.).

Hook implementations are registered via the Plugins system:

plugins.insert(Arc::new(MyHook) as RegionHookRef);

Coverage

Scenario	on_sst_files_written	on_manifest_updated
Flush (memtable → SST)	✅ Yes	✅ Yes
Local compaction	✅ Yes	✅ Yes
Remote compaction	✅ (compactor node) ¹	✅ (compactor node) ¹
RegionEdit / bulk ingestion	❌ (files pre-written)	✅ Yes
Copy region	❌ (object-store copy)	✅ Yes
Apply staging	❌ (delegates to edit)	✅ Yes ²
Alter (schema change)	❌ (no SST files)	✅ Yes
Truncate	❌ (removes files)	✅ Yes
Enter staging	❌ (no SST files)	✅ Yes
Async index build	❌ (index files only)	✅ Yes

¹ Remote compaction runs on a dedicated compactor node via open_compaction_region(). The caller must pass plugins via OpenCompactionRegionRequest to enable hooks on the compactor node. ² Apply staging fires on_manifest_updated twice: once when the staging SST files are committed via RegionEdit, and once when exit_staging_on_success merges all staged manifest actions into the live manifest.

The following paths do not trigger any hook:

• Follower region sync / catchup (manifest read-only; followers don’t author changes)
• GC / checkpoint / drop / remap (internal bookkeeping, not logical state changes)

Invocation points

on_sst_files_written is invoked at the SST write site (flush task or compaction task), immediately after SST files are written but before the manifest is committed.

on_manifest_updated is funneled through ManifestContext::update_locked, the sole caller of the low-level RegionManifestManager::update, which packages each successful write into a PendingManifestHook. The caller owns the write lock, drops it, and then fires the receipt — the hook must never run under the lock. ManifestContext::update_manifest is the common case: it acquires the lock, delegates to update_locked, and fires the receipt in one go. Multi-step sequences (staging-exit, role-state backfill) call update_locked directly under their own held guard.

Non-logical writes (GC, staging bookkeeping) call the manager’s own methods directly and intentionally do not fire the hook.

Future work

A future on_files_removed hook may be added to observe file lifecycle end (GC, drop, truncate, compaction removal). This is not yet implemented.

Structs

PendingManifestHook 🔒

A deferred RegionHook::on_manifest_updated notification produced by a logical manifest write via ManifestContext::update_locked.

SstFileInfo

Information about a single SST data file written during flush or compaction.

Traits

RegionHook

Hook for observing region mutations in mito2.

Type Aliases

RegionHookRef