Metadata-Version: 2.3
Name: cadbuildr-broker
Version: 0.2.1
Summary: WebRTC broker for CADbuildr - mediates communication between foundation library and viewer
Author: CADbuildr Team
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aiohttp (>=3.9.0,<4.0.0)
Requires-Dist: aiortc (>=1.9.0,<2.0.0)
Requires-Dist: click (>=8.1.0,<9.0.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Description-Content-Type: text/markdown

# CADbuildr Broker

WebRTC broker for CADbuildr that mediates communication between Foundation and a viewer page.

## Status

green

## Runtime contract

The broker is local-first. Keep heavy CAD data local.

- **Data path (heavy):** Foundation -> local broker `/send` -> WebRTC DataChannel -> viewer.
- **Signaling path (lightweight):** viewer/broker offer-answer exchange via signaling API.
- Signaling can be local or remote/authenticated.
- The broker does not need to relay CAD DAG payloads through cloud endpoints.

## Installation

### From PyPI

```bash
pip install cadbuildr-broker
```

### From monorepo (development)

```bash
cd py/packages/broker
poetry install
```

## Usage

Start with hosted Hub signaling (default):

```bash
cadbuildr-broker
```

Equivalent monorepo command:

```bash
cd py/packages/broker
poetry run cadbuildr-broker
```

Use local signaling (Hub on localhost) by overriding defaults:

```bash
cadbuildr-broker \
  --host localhost \
  --port 3000 \
  --signaling-scheme http
```

Or set an explicit signaling API base URL:

```bash
cadbuildr-broker \
  --signaling-base-url https://hub.cadbuildr.com/api/webrtc
```

Use remote signaling with auth:

```bash
CADBUILDR_SIGNALING_BEARER_TOKEN="<token>" \
cadbuildr-broker \
  --signaling-base-url https://hub.cadbuildr.com/api/webrtc
```

## CLI options

- `--host`: signaling host (default: `hub.cadbuildr.com`)
- `--port`: signaling port (default: `443`)
- `--signaling-scheme`: `http` or `https` (default: `https`)
- `--signaling-base-url`: full signaling API base URL, for example `https://hub.cadbuildr.com/api/webrtc`
- `--auth-bearer-token`: optional bearer token for signaling requests (or use env `CADBUILDR_SIGNALING_BEARER_TOKEN`)
- `--broker-port`: local HTTP port used by Foundation and screenshot upload (default: `5050`)

## What runs where

1. Broker polls signaling API for offers.
2. Viewer creates WebRTC offer and receives answer.
3. Foundation posts DAG to broker `/send` on localhost.
4. Broker forwards DAG to viewer via DataChannel.
5. Viewer posts screenshots/log payloads back to broker.

## Publishing

Recommended release flow:

```bash
cd py/packages/broker
poetry build
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish --repository testpypi
pip install -i https://test.pypi.org/simple cadbuildr-broker
poetry publish
```

If your environment uses token-based publishing, configure Poetry credentials before publishing.

