Metadata-Version: 2.4
Name: backend.ai-common
Version: 25.17.0rc1
Summary: Backend.AI commons library
Home-page: https://github.com/lablup/backend.ai
Author: Lablup Inc. and contributors
License: LGPLv3
Project-URL: Documentation, https://docs.backend.ai/
Project-URL: Source, https://github.com/lablup/backend.ai
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Requires-Python: >=3.13,<3.14
Description-Content-Type: text/markdown
Requires-Dist: PyJWT~=2.10.1
Requires-Dist: aiodns==3.2
Requires-Dist: aiofiles~=24.1.0
Requires-Dist: aiohttp~=3.12.15
Requires-Dist: aiomonitor~=0.7.0
Requires-Dist: aiotools~=2.2.3
Requires-Dist: async_timeout~=4.0
Requires-Dist: asynctest>=0.13.0
Requires-Dist: asyncudp>=0.11
Requires-Dist: attrs>=25.3
Requires-Dist: backend.ai-logging==25.17.0rc1
Requires-Dist: backend.ai-plugin==25.17.0rc1
Requires-Dist: callosum~=1.0.3
Requires-Dist: click~=8.1.7
Requires-Dist: etcd-client-py~=0.4.1
Requires-Dist: graphql-core~=3.2.6
Requires-Dist: hiredis>=3.0.0
Requires-Dist: ifaddr~=0.2
Requires-Dist: janus~=2.0
Requires-Dist: lark~=1.1.5
Requires-Dist: msgpack~=1.1.0
Requires-Dist: multidict~=6.6.4
Requires-Dist: orjson~=3.10.16
Requires-Dist: packaging>=24.1
Requires-Dist: prometheus-client~=0.21.1
Requires-Dist: psutil~=7.0
Requires-Dist: pydantic[email]~=2.11.3
Requires-Dist: pyhumps~=3.8.0
Requires-Dist: pyroscope-io~=0.8.8
Requires-Dist: python-dateutil>=2.9
Requires-Dist: redis[hiredis]==4.5.5
Requires-Dist: temporenc~=0.1.0
Requires-Dist: tenacity>=9.0
Requires-Dist: tomli~=2.0.1
Requires-Dist: toml~=0.10.2
Requires-Dist: trafaret~=2.1
Requires-Dist: typeguard~=4.3
Requires-Dist: types-aiofiles
Requires-Dist: types-psutil
Requires-Dist: types-python-dateutil
Requires-Dist: types-redis
Requires-Dist: types-six
Requires-Dist: types-toml
Requires-Dist: valkey-glide~=2.0.1
Requires-Dist: yarl~=1.19.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

Backend.AI Common Package
=========================

← [Back to Backend.AI Architecture](../README.md)

[![PyPI release version](https://badge.fury.io/py/backend.ai-common.svg)](https://pypi.org/project/backend.ai-common/)
![Supported Python versions](https://img.shields.io/pypi/pyversions/backend.ai-common.svg)
[![Gitter](https://badges.gitter.im/lablup/backend.ai-common.svg)](https://gitter.im/lablup/backend.ai-common)

## 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/](./events/README.md)** - 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/](./bgtask/README.md)** - 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 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

```console
$ pip install backend.ai-common
```

## For development

```console
$ pip install -U pip setuptools
$ pip install -U -r requirements/dev.txt
```

### Running test suite

```console
$ 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

- [Event Dispatcher System](./events/README.md)
- [Background Task Handler System](./bgtask/README.md)
- [Manager Component](../manager/README.md)
- [Agent Component](../agent/README.md)
- [Storage Proxy Component](../storage/README.md)
