mirror of
https://github.com/azaion/loader.git
synced 2026-04-23 10:56:34 +00:00
Oleksandr Bezdieniezhnykh
66 lines
3.6 KiB
Markdown
66 lines
3.6 KiB
Markdown
# Azaion.Loader — Solution
|
|
|
|
## 1. Product Solution Description
|
|
|
|
Azaion.Loader is a lightweight HTTP microservice that runs on edge devices to manage the secure distribution of encrypted Docker images and AI model resources. It acts as a bridge between the centralized Azaion Resource API, an S3-compatible CDN, and the local Docker daemon.
|
|
|
|
```mermaid
|
|
graph LR
|
|
Client([HTTP Client]) --> Loader[Azaion.Loader<br/>FastAPI]
|
|
Loader --> API[Azaion Resource API]
|
|
Loader --> CDN[S3 CDN]
|
|
Loader --> Docker[Docker Daemon]
|
|
Loader --> FS[Local Filesystem]
|
|
```
|
|
|
|
The service provides three core capabilities:
|
|
1. **Authentication** — proxy login to the Azaion Resource API, extracting user roles from JWT
|
|
2. **Resource management** — encrypted download/upload of AI models using a binary-split scheme (small part via API, large part via CDN)
|
|
3. **Docker unlock** — download a key fragment, decrypt an encrypted Docker image archive, and load it into the local Docker daemon
|
|
|
|
## 2. Architecture
|
|
|
|
### Solution Table
|
|
|
|
| Solution | Tools | Advantages | Limitations | Requirements | Security | Cost | Fit |
|
|
|----------|-------|-----------|-------------|-------------|----------|------|-----|
|
|
| Cython + FastAPI microservice | Python 3.11, Cython 3.1.3, FastAPI, boto3, cryptography | IP protection via compiled extensions; fast HTTP; Python ecosystem access | Single-threaded blocking I/O for large files; Cython debugging difficulty | ARM64 edge device, Docker socket access | AES-256-CBC encryption, hardware-bound keys, split-storage scheme | Minimal — single container, no database | High — purpose-built for edge deployment with security constraints |
|
|
|
|
### Component Architecture
|
|
|
|
| # | Component | Modules | Responsibility |
|
|
|---|-----------|---------|----------------|
|
|
| 01 | Core Models | constants, credentials, user, unlock_state | Shared types, constants, logging |
|
|
| 02 | Security | security, hardware_service | AES-256-CBC crypto, key derivation, HW fingerprint |
|
|
| 03 | Resource Management | api_client, cdn_manager, binary_split | Auth, resource download/upload, Docker unlock |
|
|
| 04 | HTTP API | main | FastAPI endpoints (thin controller) |
|
|
|
|
### Key Design Patterns
|
|
|
|
- **Binary-split storage**: Resources are encrypted then split — small part on authenticated API, large part on CDN. Compromise of either alone is insufficient.
|
|
- **Hardware-bound keys**: Download encryption keys derive from user credentials + machine hardware fingerprint (CPU, GPU, RAM, drive serial).
|
|
- **Compiled extensions**: Security-sensitive Cython modules compile to `.so` files, protecting IP and key derivation logic.
|
|
- **Lazy initialization**: `ApiClient` and Cython imports are lazy-loaded to minimize startup time and avoid import-time side effects.
|
|
|
|
## 3. Testing Strategy
|
|
|
|
**Current state**: No test suite exists. No test framework is configured. No test files are present in the codebase.
|
|
|
|
**Integration points that would benefit from testing**:
|
|
- API authentication flow (login → JWT decode → User creation)
|
|
- Binary-split encrypt/decrypt round-trip
|
|
- CDN upload/download operations
|
|
- Hardware fingerprint collection (platform-specific)
|
|
- Docker image unlock state machine
|
|
|
|
## 4. References
|
|
|
|
| Artifact | Path | Description |
|
|
|----------|------|-------------|
|
|
| Dockerfile | `Dockerfile` | Container build with Cython compilation + Docker CLI |
|
|
| CI config | `.woodpecker/build-arm.yml` | ARM64 Docker build pipeline |
|
|
| Dependencies | `requirements.txt` | Python/Cython package list |
|
|
| Build config | `setup.py` | Cython extension compilation |
|
|
| Architecture doc | `_docs/02_document/architecture.md` | Full architecture document |
|
|
| System flows | `_docs/02_document/system-flows.md` | All system flow diagrams |
|