Metadata-Version: 2.4
Name: backend.ai-appproxy-coordinator
Version: 25.18.0rc2
Summary: Backend.AI AppProxy Coordinator
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: Jinja2~=3.1.6
Requires-Dist: PyJWT~=2.10.1
Requires-Dist: SQLAlchemy[postgresql_asyncpg]~=1.4.54
Requires-Dist: aiohttp_cors~=0.8.1
Requires-Dist: aiohttp_jinja2~=1.6
Requires-Dist: aiohttp~=3.12.15
Requires-Dist: aiomonitor~=0.7.0
Requires-Dist: aiotools~=2.2.3
Requires-Dist: alembic~=1.13.2
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: attrs>=25.3
Requires-Dist: backend.ai-appproxy-common==25.18.0rc2
Requires-Dist: backend.ai-cli==25.18.0rc2
Requires-Dist: backend.ai-common==25.18.0rc2
Requires-Dist: backend.ai-logging==25.18.0rc2
Requires-Dist: backend.ai-plugin==25.18.0rc2
Requires-Dist: click~=8.1.7
Requires-Dist: memray~=1.17.2
Requires-Dist: prometheus-client~=0.21.1
Requires-Dist: pydantic[email]~=2.11.3
Requires-Dist: pyroscope-io~=0.8.8
Requires-Dist: python-dateutil>=2.9
Requires-Dist: redis[hiredis]==4.5.5
Requires-Dist: setproctitle~=1.3.5
Requires-Dist: tenacity>=9.0
Requires-Dist: tomli-w~=1.2.0
Requires-Dist: types-Jinja2
Requires-Dist: types-python-dateutil
Requires-Dist: types-redis
Requires-Dist: uvloop~=0.22.1; sys_platform != "Windows"
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 App Proxy Coordinator

## Purpose

The App Proxy Coordinator manages routing information for App Proxy Workers, coordinates worker instances, and handles service port mappings for compute session services (Jupyter, SSH, TensorBoard, etc.).

## Key Responsibilities

### 1. Worker Management
- Register and track App Proxy Worker instances
- Monitor worker health and availability
- Distribute routing information to workers
- Handle worker failover

### 2. Route Management
- Manage service port mappings (session → service → port)
- Update routing tables dynamically
- Propagate route changes to workers
- Handle route conflicts and resolution

### 3. Service Discovery
- Maintain service registry
- Provide route lookup for workers
- Update routes when sessions change
- Clean up routes for terminated sessions

## Entry Points

App Proxy Coordinator has 1 entry point to receive and process requests.

### 1. REST API

**Framework**: aiohttp (async HTTP server)

**Port**: 6030 (default)

**Primary Purpose**:
- Worker management (registration, monitoring)
- Routing information management (session-to-service port mapping)

**Key Features**:
- HTTP/HTTPS-based communication
- Centralized service routing information management
- Real-time route updates
- Persistent routing information storage in PostgreSQL

**Processing Flow**:

#### Worker Registration Flow
```
Worker → POST /workers/register → Coordinator
                                      ↓
                                  Register worker in DB
                                      ↓
                                  Return worker ID and routes
```

#### Route Creation Flow
```
Manager → POST /routes → Coordinator
                             ↓
                         Store route in DB
                             ↓
                         Notify all workers
                             ↓
                         Workers update local routing table
```

**Integrated Architecture**:

```
┌──────────────┐
│   Manager    │
│              │
└──────┬───────┘
       │ Route Management (REST)
       ▼
┌─────────────────────────────────────┐
│  App Proxy Coordinator (Port 6030)  │
│  - Worker registration              │
│  - Route management                 │
│  - Service port mapping             │
│  - Route propagation                │
└─────────┬───────────────────────────┘
          │
          ▼ Worker Registration & Route Updates
    ┌─────┴─────┬─────────┬─────────┐
    ▼           ▼         ▼         ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│Worker 1│ │Worker 2│ │Worker 3│ │Worker N│
└────────┘ └────────┘ └────────┘ └────────┘
```
