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
Metadata
1 maintainer
Release files for backend.ai-common 26.9.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| backend_ai_common-26.9.2.tar.gz | 606.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| backend_ai_common-26.9.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.6 MB
Release files / backend_ai_common-26.9.2.tar.gz
| Download URL | backend_ai_common-26.9.2.tar.gz |
|---|---|
| Size | 606.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9228ad857605bfc3814c66faf87f14aff5f2948cbb8daf3d81ba0f8b53f6f797
|
|
BLAKE2b-256 checksum How to use checksums |
92052677fe3b314bc5b185e0a386dd8d1236288db8d4c0cbbad3fd090a5aaeb5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / backend_ai_common-26.9.2-py3-none-any.whl
| Download URL | backend_ai_common-26.9.2-py3-none-any.whl |
|---|---|
| Size | 953.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4bf983b103ee4c2afdc6d230ccbb4f0e525c0c154ea9c97c9b81fe4a490978db
|
|
BLAKE2b-256 checksum How to use checksums |
a3a0261d1b937d35c5b49119395f8168e829258815e577b4ebca5da947017a15
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
