feat(instance-proxy): add HTTP proxy for tool instances

Add API proxy endpoint so users can access running tool instances
through the backend API instead of internal Docker network.

Backend:
- Add container_name field to ToolInstance model
- Create /instances/{id}/proxy/{path:path} endpoint with ownership checks
- Proxy HTTP requests to containers via docker network using container names
- Support all HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
- Store proxy URL in instance.url instead of localhost
- Add Alembic migration 0007 for container_name column
- Add get_container_name() utility to docker.py

Frontend:
- Update Open button to use full proxy URL (API_BASE_URL + instance.url)

Closes instance-proxy OpenSpec change.
This commit is contained in:
Fusion
2026-05-20 10:37:21 +02:00
parent 25662e525c
commit 74b5d0dc8c
12 changed files with 498 additions and 6 deletions
@@ -0,0 +1,41 @@
## ADDED Requirements
### Requirement: Proxy endpoint exists for running instances
The API SHALL expose an endpoint that forwards HTTP requests to a running tool instance.
#### Scenario: Access running instance
- **WHEN** an authenticated user sends a GET request to `/instances/{id}/proxy/`
- **THEN** the request is forwarded to the instance's container
- **AND** the response is returned to the user
#### Scenario: Access instance subpath
- **WHEN** an authenticated user sends a request to `/instances/{id}/proxy/api/status`
- **THEN** the request is forwarded to `{container_url}/api/status`
- **AND** the response is returned to the user
### Requirement: Only instance owner can access proxy
The proxy endpoint SHALL verify that the authenticated user owns the instance before forwarding.
#### Scenario: Owner accesses instance
- **WHEN** the instance owner requests `/instances/{id}/proxy/`
- **THEN** the request is forwarded to the instance
#### Scenario: Non-owner attempts access
- **WHEN** a user who does not own the instance requests `/instances/{id}/proxy/`
- **THEN** the API returns 403 Forbidden
### Requirement: Proxy handles WebSocket upgrades
The proxy endpoint SHALL support WebSocket upgrade requests for real-time features.
#### Scenario: WebSocket connection to instance
- **WHEN** a user sends a request with `Upgrade: websocket` header
- **THEN** the API establishes a bidirectional WebSocket connection to the instance
- **AND** messages are relayed between user and instance
### Requirement: Frontend uses proxy URL for instance access
The frontend SHALL link to the proxy endpoint instead of the internal container URL.
#### Scenario: User clicks Open button
- **WHEN** a user clicks "Open" on a running instance
- **THEN** a new tab opens to `/instances/{id}/proxy/`
- **AND** the proxied instance content is displayed