State Machine

The koala loader and retriever both use a state machine pattern to process SIPs and retrieval requests. Each state represents a discrete step in the pipeline, and states transition to the next based on the outcome of the previous step.

Loader Pipeline

State Transition Diagram

InitState (start)
    │
    ├── [clamav enabled + socket exists] ──→ VirusScanState
    │       │
    │       ├── [virus found] ──→ LoaderErrorState (via KoalaError)
    │       ├── [clamav unreachable + continue_on_error] ──→ DetermineSIPTypeState
    │       └── [scan clean] ──→ ExtractState
    │
    └── [clamav disabled or no socket] ──→ ExtractState

ExtractState ──→ DetermineSIPTypeState

DetermineSIPTypeState
    │
    ├── [external_asset_id exists in DB + empty content folder] ──→ ValidateUpdateMetadataState
    ├── [external_asset_id exists in DB + non-empty content folder] ──→ HandleMigrationState
    └── [external_asset_id NOT in DB] ──→ ValidateMetadataState

ValidateUpdateMetadataState ──→ UpdateMetadataArchivalStorageState ──→ UpdateMDQIState

HandleMigrationState ──→ ValidateMetadataState  (loops back with asset_version set)

ValidateMetadataState ──→ ValidateFileTypesState ──→ CreateAIPState ──→ StoreAIPState ──→ UpdateMDQIState

UpdateMDQIState
    │
    ├── [metadata update] ──→ CleanupState
    └── [normal ingest] ──→ UpdateDataManagementState

UpdateDataManagementState ──→ CleanupState

CleanupState
    │
    ├── [callback_url configured] ──→ CallbackUrlState
    └── [no callback_url] ──→ DoneState (end)

CallbackUrlState ──→ DoneState (end)

DoneState (end) -- returns (None, cargo)

LoaderErrorState (error) -- recoverable, breaks loop
FatalState (fatal)       -- non-recoverable, raises exception

Retriever Pipeline

State Transition Diagram

InitState (start) ──→ PrepareFolderState ──→ RetrieveAssetState

RetrieveAssetState
    │
    ├── [fullmetadata] ──→ EditMetadataState
    ├── [asset / checkconsistency] ──→ UnpackState
    ├── [simple_retrieve] ──→ AssembleAliasPathState
    └── [retrieveall] ──→ AssembleAliasPathState

UnpackState
    │
    ├── [checkconsistency] ──→ ConvertState
    └── [other] ──→ EditMetadataState

ConvertState ──→ ValidateMetadataState ──→ CleanupState ──→ OKState (end)

EditMetadataState
    │
    ├── [fullmetadata or unpacked dip_format] ──→ AssembleAliasPathState
    └── [other] ──→ CreateDIPState

CreateDIPState ──→ AssembleAliasPathState

AssembleAliasPathState
    │
    ├── [callback_url configured] ──→ CallbackUrlState
    └── [no callback_url] ──→ ReadyState (end)

CallbackUrlState ──→ OKState (end)

ReadyState (end) -- returns (None, cargo)
OKState (end)    -- returns (None, cargo)

RetrieverErrorState (error) -- returns (None, cargo)
FatalState (fatal)          -- non-recoverable