loader/_docs/02_document/modules/main.md

Module: main

Purpose

FastAPI application entry point providing HTTP endpoints for health checks, authentication, encrypted resource loading/uploading, and a multi-step Docker image unlock workflow.

Public Interface

FastAPI Application

app = FastAPI(title="Azaion.Loader")

Endpoints

Method	Path	Request Body	Response	Description
GET	/health	—	{"status": "healthy"}	Liveness probe
GET	/status	—	StatusResponse	Auth status + model cache dir
POST	/login	LoginRequest	{"status": "ok"}	Set credentials on API client
POST	/load/{filename}	LoadRequest	binary (octet-stream)	Download + decrypt resource
POST	/upload/{filename}	multipart (file + folder)	{"status": "ok"}	Encrypt + upload resource (big/small split)
POST	/unlock	LoginRequest	{"state": "..."}	Start background unlock workflow
GET	/unlock/status	—	{"state": "...", "error": ...}	Poll unlock progress

Pydantic Models

Model	Fields
LoginRequest	email: str, password: str
LoadRequest	filename: str, folder: str
HealthResponse	status: str
StatusResponse	status: str, authenticated: bool, modelCacheDir: str

Module-level State

Name	Type	Description
api_client	ApiClient or None	Lazy-initialized singleton
unlock_state	UnlockState	Current unlock workflow state
unlock_error	Optional[str]	Last unlock error message
unlock_lock	threading.Lock	Thread safety for unlock state mutations

Internal Logic

get_api_client()

Lazy singleton pattern: creates ApiClient(RESOURCE_API_URL) on first call.

Unlock Workflow (_run_unlock)

Background task (via FastAPI BackgroundTasks) that runs these steps:

1. Check if Docker images already loaded → if yes, set ready
2. Authenticate with API (login)
3. Download key fragment from /binary-split/key-fragment
4. Decrypt archive at IMAGES_PATH → .tar
5. docker load the tar file
6. Clean up tar file
7. Set state to ready (or error on failure)

State transitions are guarded by unlock_lock (threading.Lock).

/unlock Endpoint

• If already ready → return immediately
• If already in progress → return current state
• If no encrypted archive found → check if images already loaded; if not, 404
• Otherwise, starts _run_unlock as a background task

Dependencies

• Internal: unlock_state (UnlockState enum), api_client (lazy import), binary_split (lazy import)
• External: os, threading (stdlib), fastapi, pydantic

Consumers

None — this is the entry point module.

Data Models

LoginRequest, LoadRequest, HealthResponse, StatusResponse (Pydantic models defined inline).

Configuration

Env Variable	Default	Description
RESOURCE_API_URL	https://api.azaion.com	Azaion resource API base URL
IMAGES_PATH	/opt/azaion/images.enc	Path to encrypted Docker images
API_VERSION	latest	Expected Docker image version tag

External Integrations

• Azaion Resource API: via ApiClient (authenticated resource download/upload)
• Docker CLI: via binary_split (docker load, image inspect)
• File system: encrypted archive at IMAGES_PATH

Security

• Login endpoint returns 401 on auth failure
• All resource endpoints use authenticated API client
• Unlock state is thread-safe via threading.Lock
• Lazy imports of Cython modules (api_client, binary_split) to avoid import-time side effects

Tests

No tests found.