This release is a pre-release and may not be stable for production use.
Backend.AI Common Package
← Back to Backend.AI Architecture
Overview
The Backend.AI Common package provides utilities, infrastructure, and shared components used across all Backend.AI components (Manager, Agent, Storage Proxy, Webserver, App Proxy, etc.).
Package Structure
Entry Point System
Core event-based communication and asynchronous task processing framework for Backend.AI.
-
events/ - Event Dispatcher System
- Asynchronous event-based communication between components
- Broadcast and Anycast event type support
- Message queue-based event delivery
- Event handler registration and routing
-
bgtask/ - Background Task Handler System
- Process long-running tasks asynchronously
- Issue Task IDs and track tasks
- Progress monitoring and Heartbeat
- Notify via event publishing upon completion
Infrastructure Components
Client and abstraction layer for integration with external services and systems.
-
clients/ - External service client wrappers
- Agent client (ZeroMQ RPC)
- Storage Proxy client (HTTP)
- Valkey/Redis client
- etcd client
-
message_queue/ - Message queue interface and implementation
- Provide message publish/subscribe interface
- Currently implemented based on Valkey/Redis streams
- Consumer Group management
- Future support for other message queue systems planned
-
service_discovery/ - Service registration and integration
- etcd-based service registration and discovery
- Provide service information for Prometheus metrics collection
- Automatic health check and update
- Future expansion of additional service discovery features planned
-
resilience/ - Inter-layer communication resilience patterns
- Generalize request processing between layers
- Retry, Timeout, Circuit Breaker
- Automatic metric collection
- Fallback support
Data and Types
Common structures for data exchange and type definitions between components.
-
dto/ - Data Transfer Objects (for inter-component communication)
- Data structures used for inter-component communication
- Request/Response models
- Event payloads
- Recommended to use Pydantic-based
-
types.py - Common type definitions (for internal logic)
- Domain types used within components (SessionId, AgentId, AccessKey, etc.)
- Shared Enum types
- Common constants
- Mainly used in internal business logic
Utilities
Utility modules for development convenience and common functionality.
-
metrics/ - Metrics collection and Prometheus integration
- Metric observer pattern
- Prometheus metric types (Counter, Gauge, Histogram)
- HTTP metrics middleware
-
auth/ - Authentication utilities
- Authentication between Webserver (Gateway) and Manager
- JWT token generation/verification
- Signature generation/verification
- API Key management
-
web/ - Web utilities
- HTTP helper functions
- CORS configuration
- Request/response processing
-
middlewares/ - Common middlewares
- Commonly used across all components
- Authentication middleware
- Logging middleware
- Error handling middleware
-
configs/ - Configuration management utilities
- Configuration processing commonly used internally
- Configuration file parsing (TOML, YAML)
- Environment variable processing
- Configuration validation
Other Components
-
contexts/ - Context management utilities
- ContextVar-based request and user tracking
- Current request ID tracking
- Current user information management
- Context propagation
-
data/ - Common data utilities
- Data-based value processing used in internal logic
- Data transformation and validation
- Common data type handling
-
exception.py - Common exception classes
- Base exceptions for all Backend.AI services
- Exception definitions must inherit from BackendAIError
- Domain-specific exception classes
- Communicate error situations externally
-
utils.py - Other utility functions
- String processing
- Time conversion
- Other helper functions
Installation
$ pip install backend.ai-common
For development
$ pip install -U pip setuptools
$ pip install -U -r requirements/dev.txt
Running test suite
$ python -m pytest
With the default halfstack setup, you may need to set the environment variable BACKEND_ETCD_ADDR
to specify the non-standard etcd service port (e.g., localhost:8110).
The tests for common.redis module requires availability of local TCP ports 16379, 16380, 16381,
26379, 26380, and 26381 to launch a temporary Redis sentinel cluster via docker compose.
In macOS, they require a local redis-server executable to be installed, preferably via brew,
because docker compose in macOS does not support host-mode networking and Redis cannot be
configured to use different self IP addresses to announce to the cluster nodes and clients.
Related Documentation
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file backend_ai_common-26.8.0rc1.tar.gz.
File metadata
- Download URL: backend_ai_common-26.8.0rc1.tar.gz
- Upload date:
- Size: 569.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.2.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f5b5da1abcbcb24286f533eba0ef086b09d5bc0ef90939afab853415135bced2
|
|
| MD5 |
c60158f53e35e358b300dd758aba4dcf
|
|
| BLAKE2b-256 |
80e1ac5e4cedff89f761c69998d0db35ee08b878a223e3fcf886bddf4730f9ed
|
File details
Details for the file backend_ai_common-26.8.0rc1-py3-none-any.whl.
File metadata
- Download URL: backend_ai_common-26.8.0rc1-py3-none-any.whl
- Upload date:
- Size: 889.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.2.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1e8aaebedb7434021a188ebccc441782bd669d500fbc8de058ef2910c747f1bc
|
|
| MD5 |
09440f56226b7d8a989fea715640a01e
|
|
| BLAKE2b-256 |
b6146595cc0d398669093a71999986c189ac8ab550af8328dab31ac34a7fc63b
|
