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

Module: api_client

Purpose

Central API client that orchestrates authentication, encrypted resource download/upload (using a big/small binary-split scheme), and CDN integration for the Azaion resource API.

Public Interface

Classes

ApiClient (cdef class)

Attribute	Type	Description
credentials	Credentials	User email/password
user	User	Authenticated user (from JWT)
token	str	JWT bearer token
cdn_manager	CDNManager	CDN upload/download client
api_url	str	Base URL for the resource API

Methods

Method	Visibility	Signature	Description
__init__	def	(self, str api_url)	Initialize with API base URL
set_credentials_from_dict	cpdef	(self, str email, str password)	Set credentials + initialize CDN from cdn.yaml
set_credentials	cdef	(self, Credentials credentials)	Internal: set credentials, lazy-init CDN manager
login	cdef	(self)	POST /login, store JWT token
set_token	cdef	(self, str token)	Decode JWT claims → create User with role mapping
request	cdef	(self, str method, str url, object payload, bint is_stream)	Authenticated HTTP request with auto-retry on 401/403
load_bytes	cdef	(self, str filename, str folder) -> bytes	Download + decrypt resource using per-user+hw key
upload_file	cdef	(self, str filename, bytes resource, str folder)	POST multipart upload to /resources/{folder}; raises on HTTP error
load_big_file_cdn	cdef	(self, str folder, str big_part) -> bytes	Download large file part from CDN
load_big_small_resource	cpdef	(self, str resource_name, str folder) -> bytes	Reassemble resource from small (API) + big (CDN/local) parts
upload_big_small_resource	cpdef	(self, bytes resource, str resource_name, str folder)	Split-encrypt; CDN upload must succeed or raises; then small part via upload_file

Internal Logic

Authentication Flow

1. set_credentials_from_dict() → stores credentials, downloads cdn.yaml via load_bytes() (encrypted), parses YAML, initializes CDNManager
2. login() → POST /login with email/password → receives JWT token → set_token() decodes claims (nameid, unique_name, role) → creates User
3. request() → wraps all authenticated HTTP calls; on 401/403 auto-retries with fresh login

Big/Small Resource Split (download)

1. Downloads the "small" encrypted part via API (load_bytes() with per-user+hw key)
2. Checks if "big" part exists locally (cached file)
3. If local: concatenates small + big, decrypts with shared resource key
4. If decrypt fails (version mismatch): falls through to CDN download
5. If no local: downloads big part from CDN
6. Concatenates small + big, decrypts with shared resource key

Big/Small Resource Split (upload)

1. Encrypts entire resource with shared resource key
2. Splits: small part = min(SMALL_SIZE_KB * 1024, 30% of encrypted), big part = remainder
3. Calls cdn_manager.upload for the big part; raises if upload fails
4. Writes big part to local cache, then uploads small part to API via upload_file (non-2xx responses propagate)

JWT Role Mapping

Maps role claim string to RoleEnum: ApiAdmin, Admin, ResourceUploader, Validator, Operator, or NONE (default).

Dependencies

• Internal: constants, credentials, cdn_manager, hardware_service, security, user
• External: json, os (stdlib), jwt (pyjwt 2.10.1), requests (2.32.4), yaml (pyyaml 6.0.2)

Consumers

• main — creates ApiClient instance; calls set_credentials_from_dict, login, load_big_small_resource, upload_big_small_resource; reads .token

Data Models

Uses Credentials, User, RoleEnum, CDNCredentials, CDNManager from other modules.

Configuration

Source	Key	Usage
cdn.yaml	host	CDN endpoint URL
cdn.yaml	downloader_access_key/secret	CDN read credentials
cdn.yaml	uploader_access_key/secret	CDN write credentials

The CDN config file is itself downloaded encrypted from the API on first credential setup.

External Integrations

• Azaion Resource API: /login, /resources/get/{folder}, /resources/{folder} (upload)
• S3 CDN: via CDNManager for large file parts

Security

• JWT token stored in memory, decoded without signature verification (options={"verify_signature": False})
• Per-download encryption: resources encrypted with AES-256-CBC using a key derived from user credentials + hardware fingerprint
• Shared resource encryption: big/small split uses a fixed shared key
• Auto-retry on 401/403 re-authenticates transparently
• CDN config is downloaded encrypted, decrypted locally

Tests

No tests found.