iowap-server 2.0.0__py3-none-any.whl

iowap_server-2.0.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: iowap-server
+Version: 2.0.0
+Summary: IOWAP Relay Server — API, Scheduler, Auth, Dashboard, Metrics
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-multipart>=0.0.18
+Requires-Dist: bcrypt>=4.1
+Requires-Dist: itsdangerous>=2.1
+Requires-Dist: zeroconf>=0.63
+Requires-Dist: slowapi>=0.1
+Requires-Dist: markdown>=3.6
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: uvloop
+Requires-Dist: uvloop>=0.19; extra == "uvloop"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Dynamic: license-file
+
+# iowap-server
+
+**IOWAP Relay Server — API, Scheduler, Auth, Dashboard, Metrics**
+
+The relay server is the central coordinator in the IOWAP ecosystem. Nodes register their capabilities via heartbeat, and the relay matches tasks to capable nodes. It is a **purpose-agnostic scheduler** — it knows nothing about the work itself, only who can do what.
+
+## Features
+
+- **Capability Registry** — nodes heartbeat their capabilities, relay maintains a live registry
+- **Task Scheduler** — match tasks to capable nodes, claim/release lifecycle with retry
+- **Auth & Security** — token-based node auth, CSRF-protected dashboard, TLS support
+- **Dashboard** — web UI for node overview, task monitoring, capability browsing, metrics
+- **SSE Events** — real-time event stream for connected nodes
+- **Status System** — node/task/stage status registry with valid transitions
+- **Event Bus** — publish/subscribe internal events for monitoring & extensibility
+- **PostgreSQL + SQLite** — production (Postgres) and dev (SQLite) backends
+- **Docker** — `docker compose up` for one-command deployment
+- **Observability** — `/metrics` (Prometheus), `/ready` health checks, structured JSON logs
+
+## Quick Start (Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/iowap-org/iowap-server/main/install.sh | bash
+```
+
+The installer asks **native (systemd)** vs. **Docker (GHCR image)**, configures the
+database (SQLite default, PostgreSQL local/remote) and environment (homelab HTTP /
+internet TLS), creates the master admin seed, and prints the dashboard login URL.
+
+**Docker (manual)** — pre-built image on GHCR:
+
+```bash
+docker volume create relay-data
+docker run -d --name iowap-server --restart unless-stopped \
+  -p 8788:8788 \
+  -e RELAY_MASTER_SEED="$(openssl rand -hex 24)" \
+  -e RELAY_SESSION_SECRET="$(openssl rand -base64 32)" \
+  -e RELAY_SESSION_COOKIE_SECURE=false \
+  -v relay-data:/app/.relay \
+  ghcr.io/iowap-org/iowap-server:latest
+```
+
+Compose files live in [iowap-org/iowap-docker](https://github.com/iowap-org/iowap-docker) (`server/docker-compose.yml`).
+
+**Manual (source)**:
+
+```bash
+git clone --recursive https://github.com/iowap-org/iowap-server.git
+cd iowap-server
+pip install -e .            # or: pip install -e ".[postgres]"
+relay-server --host 0.0.0.0 --port 8788
+```
+
+Server starts on `http://localhost:8788` — the dashboard login is under
+`/relay/v2/dashboard/login` (master seed acts as the bootstrap admin until the
+first human admin exists).
+
+## Configuration
+
+| Env | Default | Description |
+|-----|---------|-------------|
+| `RELAY_PORT` | 8788 | Server listen port |
+| `RELAY_DB_TYPE` | sqlite | Database backend (sqlite / postgres) |
+| `RELAY_MASTER_SEED` | — | Deterministic master seed for token generation |
+| `TLS_CERTFILE` | — | TLS cert path (enables HTTPS, disables mDNS) |
+| `POSTGRES_*` | — | PostgreSQL connection (when `RELAY_DB_TYPE=postgres`) |
+
+See [iowap-docs → server/setup.md](https://github.com/iowap-org/iowap-docs/blob/main/server/setup.md) for full reference.
+
+## Architecture
+
+```
+┌──────────┐   heartbeat + capabilities    ┌───────────┐
+│  Nodes   │ ◄─────────────────────────►   │   Relay   │
+│ (any)    │   claim + complete tasks      │   Server  │
+└──────────┘                               └─────┬─────┘
+                                                  │
+                                          ┌───────┴───────┐
+                                          │   Dashboard   │
+                                          │  (HTMX/HTML)  │
+                                          └───────────────┘
+```
+
+## Docs
+
+Full documentation in [iowap-org/iowap-docs](https://github.com/iowap-org/iowap-docs):
+
+- [getting-started.md](https://github.com/iowap-org/iowap-docs/blob/main/getting-started.md) — first steps
+- [server/setup.md](https://github.com/iowap-org/iowap-docs/blob/main/server/setup.md) — full setup guide
+- [server/docker.md](https://github.com/iowap-org/iowap-docs/blob/main/server/docker.md) — Docker deployment
+- [reference/api.md](https://github.com/iowap-org/iowap-docs/blob/main/reference/api.md) — API reference
+- [server/dashboard.md](https://github.com/iowap-org/iowap-docs/blob/main/server/dashboard.md) — dashboard usage
+- [server/admin.md](https://github.com/iowap-org/iowap-docs/blob/main/server/admin.md) — administration
+
+## License
+
+MIT — see [LICENSE](LICENSE).

iowap_server-2.0.0.dist-info/RECORD

@@ -0,0 +1,108 @@
+iowap_server-2.0.0.dist-info/licenses/LICENSE,sha256=jqWgc-nPTXXB5PYfNCScU8u8c1ixMcrg0SFZLcejJ8c,1068
+relay_server/README.md,sha256=LJ8jzcBKDS4j6sb-jKeRbX--Ygb8aczELKR8kXWeiIk,4637
+relay_server/__init__.py,sha256=QODLAIMc9b1Erd-uOVJhMyE9ZSpheiwHrdR2Hr3_Fzk,78
+relay_server/cli.py,sha256=KrnG-UcItqpL8N2RDVF1oo1wLE--DWWmma_Ri7iWIss,3388
+relay_server/config.py,sha256=hdwNuLSib2LNlPAZ5U9mdB5gHD4vehMzJ289pvEng7U,9307
+relay_server/main.py,sha256=4bjTnkXQw6IIETY60cpshhveMnVRE2UPi2mmwer_2wI,18296
+relay_server/api/__init__.py,sha256=AHgeCPa3roNWGhsU5Oo_c9NM-YJnU5fpmVYKF0_Hwgg,53
+relay_server/api/v2/__init__.py,sha256=x_QwacN6wbuzeGyF4r-ID6TW2HtAeXM2FUf-XtZtCDk,1489
+relay_server/api/v2/admin.py,sha256=svXHEiSjIsnJzxAjor27RwycBH6w5bLx7DijrZT8VpM,8047
+relay_server/api/v2/auth.py,sha256=Y0wO9sak3EkgbNv70xzW0r_ibJlXVOHFK6xwCR2VCr4,14341
+relay_server/api/v2/cluster.py,sha256=lATKqe4YnQd4DYlcaaCdlS1qOrgJX3NqZY-_WL8w_Bo,19007
+relay_server/api/v2/dashboard.py,sha256=FcJT3LDCAQpYXivQLunWkZDjrRPbvbXR7zyqPi1pxzc,41563
+relay_server/api/v2/discovery.py,sha256=F4RMCEx9F_qAFBTkaWk7__5FKP73M-_SJMbEhXjdGfA,5759
+relay_server/api/v2/docs.py,sha256=HINHvfhjw_eegaXNVBu42faYAX0G-XtmWTeQEMhGnw8,7741
+relay_server/api/v2/events.py,sha256=viyIlrHPstq-qbIQrm_FlGLf3aKvW1Ulzl8Z3g7Hyx0,1998
+relay_server/api/v2/presence.py,sha256=ErXlIORIaV0sl_k7XHpJH-c8VwRMIRBt35cVgosWbGw,1543
+relay_server/api/v2/scheduler.py,sha256=U581sjmWzfEdqHSRKFJEAgZD3hRzA0e2jfnYagS8zvw,9913
+relay_server/api/v2/security.py,sha256=Fp-zNzsAHJEvTGpzVgeNhv2OiGNurbP8tXgnkk2-JDU,8617
+relay_server/api/v2/storage.py,sha256=OtwPT7xbWTT_jnxNy7fAhsu8zTxqQrOfv1dmT0-sPwo,11279
+relay_server/core/__init__.py,sha256=HdOQ7tmV-GKrY_m_PZpXSusDLX4uurFqboEuBV1Nisk,36
+relay_server/core/artifacts.py,sha256=DvifTj6u_ZVLHN7P8-cOm6OWC5ZtDlAkoP2Hlr5vsnc,13263
+relay_server/core/auth.py,sha256=4xIuOpkWnhy0gCbLVuDvHFI8EWhCGuFXMEegJONqKa4,21871
+relay_server/core/chunked_upload.py,sha256=-AH7SNKGstP3BeMCszw9ST3P3tPSMizzr1c_f1g3zgo,9730
+relay_server/core/db.py,sha256=YbaZBL4Y2c-WhYzIeAqai4Vdc_TjRItVYiN53OrXM9Y,63710
+relay_server/core/db_postgres.py,sha256=byjLhWZIE5XitFEYbbCFwFeA89Ct8Uw5bAuGi1ICRxs,3114
+relay_server/core/discovery.py,sha256=-LQQvhaHCAEthq5FLRnZPIMopnj_A9sR9Zi6bFhAATQ,34985
+relay_server/core/events.py,sha256=Y40oyegjBpIYA-SZfRb97LhL96Uvp9mtu914rfzxqZk,6976
+relay_server/core/logging_setup.py,sha256=m_suoLvAjZIesWS97msZt102DR5Mq0QjJ4N4Q1q1swk,1096
+relay_server/core/maintenance.py,sha256=ftSJrQW3FL956x1wG8YUx2vCW8Xo6U5U5M5lTQChD6g,13372
+relay_server/core/metrics.py,sha256=txw-5_tosvyolxeMZ4voTf-OweJQJ16QkZTFfVfVvws,13558
+relay_server/core/net_guard.py,sha256=SGQmOP56JNo80awuna-s3aornVM5vLJZpJETREtZ4kc,9113
+relay_server/core/node_registry.py,sha256=HF47AZHspof7PIBfx24BCI34lJDjzzvwqPzdT3yICvI,8835
+relay_server/core/presence.py,sha256=sQPNai9vOS63wr7OOF0KQdQlUH-Opz-cDu5oC2oKNSM,5882
+relay_server/core/route_registry.py,sha256=bE5ViJCum2_Nt9JarAS8Jvpl67wubczNvtuO_N8ybxg,20499
+relay_server/core/scheduler.py,sha256=a3FXOcRqDS9znBsrVd247CaZSQNdTrDJ2_mth1Apg4U,56862
+relay_server/core/session.py,sha256=pQLOQUArGzX_METWcxLI34rZz0wBsrRoOCEETOYHA1g,3171
+relay_server/core/status.py,sha256=xOH5ec_-CjzL0wohi_2gCryYP__P3aKMFOlV9WaHiQ4,12884
+relay_server/core/tables.py,sha256=dZulTnyTGF8L0fABECyTwyRSz46ohJU6222zTKPH5Wg,15270
+relay_server/core/users.py,sha256=rUjzfANmmd0h_7C3tbLBa2Ba_8IAk8gvOqGxCgDyo9g,13632
+relay_server/core/zeroconf.py,sha256=VYuhCr9tzZKckACCQgISXB-kqHJ7LPhqV3BRNcq85PY,5438
+relay_server/docs/CONTRIBUTING.md,sha256=jR1bQUZwDLKxXRrv20McvZeELtSXzTVv39530h9KmgQ,3300
+relay_server/docs/README.md,sha256=gb-2_gO44adGdKabcK5uFwu8IU6wPxo6bCcfjqDhI9w,4985
+relay_server/docs/getting-started.md,sha256=zahuvcLu4Tu3UWz9zJij4soSBAASUQZZ3VW6THLmPjY,3896
+relay_server/docs/captures/README.md,sha256=PkZlOtWalZe7vPgLXjyF2DlDX0CB1GVC31cszODi3NY,1816
+relay_server/docs/captures/capabilities-20261016.md,sha256=OYm0Dfm5osEBq2Z3Us3FLx-WfI6wDaYJd3kMeNxZUQo,50191
+relay_server/docs/captures/health-20261016.md,sha256=Dz17o64gq52kn5VrcZcLJzH3Jy65FnAYj1uQaa4yeyo,349
+relay_server/docs/captures/nodes-20261016.md,sha256=JkIDsZ7FqZUneUveOjNvYBDQ0_BjNjK02mKNhy3mJDY,2829
+relay_server/docs/clients/mcp.md,sha256=-07yS-n2TU-dgD4sXpI5tuVupEUCtqp0IYVbb3khxTE,3895
+relay_server/docs/concepts/artifacts.md,sha256=RBPfCAem44yTCITlUb5ZArUo6aDFVkimcpC9tc-Kalw,2875
+relay_server/docs/concepts/capabilities.md,sha256=ALPPIpSO65S1tDG3VVyAB2TgF5aKZaQkZdE06uCr2uQ,6468
+relay_server/docs/concepts/flow.md,sha256=JsbdAYAbNsJj7IA7MYiWCM1QFHX7UpB82YglvB0QW9w,4916
+relay_server/docs/concepts/glossary.md,sha256=1XA63JHH2EEGP0Iu0zmhiPRs26WZB-rSuhBcHc5CK-Q,4404
+relay_server/docs/concepts/nodes.md,sha256=S-LhUsW22tRAfe80zRKVDSb0YBN33GiLlDG_Fp254Rk,5855
+relay_server/docs/concepts/observability.md,sha256=LQsi3F7iRWrfUA5vY0vLDGf_6OPylEsV2zojc2Vviuo,2768
+relay_server/docs/concepts/overview.md,sha256=yIGU5V16cKPM2SuhxHWfQ3PnMExJMbgXyl9yT3R4KpY,5473
+relay_server/docs/concepts/security.md,sha256=T8QPVd4OK9r_uRqwDj4jHOB7kasJa4DttMcJt8nRcpU,3413
+relay_server/docs/concepts/tasks.md,sha256=HFI0NT7zdMPyOD3edbNOx7ZGMF2Y_El_jgrB6bWOoms,5103
+relay_server/docs/concepts/tokens.md,sha256=7V1eBtWl01G8yLCTLJ4hOviKPtbYJrn_Zj9nrp6if6I,3004
+relay_server/docs/federation/concept.md,sha256=BDi_hL5_zmZT9ec4nkeX7Kt-7jnPKqQQlTEEc4tySYE,2979
+relay_server/docs/flow/runner.md,sha256=pFuArVn4c0-AaubkmYqyNyBr3bDtBZSXM5B6enPJA1w,4369
+relay_server/docs/node/capabilities.md,sha256=FX3kqVpwfxp-kdXa7QoykQW0NMskeYmRs8uz1HbTpRE,7589
+relay_server/docs/node/cli.md,sha256=HrwuUCAzYA60-ld516egAv0DR1GeYqJL_0gBTZmdJZc,4740
+relay_server/docs/node/config.md,sha256=qyv_SuMxUW0FjqV1xyiLvqqjHpfLOc9aS6qlLaZvoLI,4611
+relay_server/docs/node/operations.md,sha256=g0oEgs1OlVzVCZF5BixUUvVU3v78qmnLOmWnSvLKjtM,4184
+relay_server/docs/node/setup.md,sha256=V6bcBoYRLM8tcktE9KY-hN0f1UlcEXaRBLFDd9RsVak,6506
+relay_server/docs/node/tokens.md,sha256=xtkn8Q3CTR1CFitsc8nASX9du_0eOFGv70lCCkcLe_8,3160
+relay_server/docs/node/handlers/contract.md,sha256=JmKnbVWTH_OyRndKjn4I_IbYtjLvFvZCsGxK5vTn9co,6165
+relay_server/docs/node/handlers/primitives.md,sha256=TMBFXHV25i7fYOOslC99bVa2LCHf07AaY2v0wlEBRE8,5883
+relay_server/docs/node/integrations/hermes.md,sha256=tI6cFrMN7NXcR5yRUALmkZ5SB-q_cxUrYULTTojNESE,6617
+relay_server/docs/node/integrations/home-assistant.md,sha256=nW1P7HlyEVhI0xoA5MGF86VimYERaF3Y2YiIjArQpZA,8811
+relay_server/docs/reference/api.md,sha256=Fk0ZS9GZHC1t9HH2xyWkk5Wh_wrhJz7KVYL3UztPhYc,19531
+relay_server/docs/reference/database-backends.md,sha256=GUVwN3wuEca2Bthw_mmqWZg0rkFMh42yM8bl31j3I4I,4550
+relay_server/docs/reference/design-board.md,sha256=Zm36WJ9tU63yggOzUC9lp0ikQO0UbKWy-YW0Ykfkb70,1829
+relay_server/docs/server/admin.md,sha256=a5ACcEWWc0c8kKiTbAXLIow1P8KiLKXeJFVGshYQ46o,3895
+relay_server/docs/server/dashboard.md,sha256=--VsQxIgY3zct5Ow8_OeV-YPnMR7EYIkXUP3KgCd92M,4446
+relay_server/docs/server/database.md,sha256=WftrCxnyglL-E22L11NhffsQ8d6U8z7rVI-kVkmefag,2751
+relay_server/docs/server/docker.md,sha256=lzTkiCYteOPhsGdsDTyl9c0DV5BK55PyxXyREQqH7TI,4680
+relay_server/docs/server/setup.md,sha256=Xb884sWBS6AltZTF4b2dAVvpPFQsN4qAkt0X2ucqkXI,8828
+relay_server/docs/storage/qnap.md,sha256=nM9AyW99Q3QWHOjzyWjE3F0VMzZtj5PDJpPT6IylS0g,3619
+relay_server/docs/storage/storage.md,sha256=iFjQaoSAudFZKRFfF5h91emBYy5PFQaJUVqEgJCslqU,6608
+relay_server/models/__init__.py,sha256=RnV2yNyVPrHXvdGyVE1kC2jDUhiE4WPCVw4eRfH5lYQ,16843
+relay_server/models/capability.py,sha256=rUveWJAmmqWauAQMSjzSgZpW7anbKncW6a0lUee5X30,4936
+relay_server/models/discovery.py,sha256=w6sQf2fylHmfAunyV1K-9_Sp3R6n_xwtJlVhTmjupBM,2372
+relay_server/models/task.py,sha256=lgEK74v1j0Q_rie8iJR-TXbseTs-5QH_jwCG0kGS-8Q,6077
+relay_server/static/admin.css,sha256=4PYdxBbEClkJ3dvJb_USoOhpYiL3_tfNhLrLlI3MH-I,17329
+relay_server/static/admin.html,sha256=J8lZEFSuv5brN2_5teXIKJRvfbtZyrjRhyJ59d0RRQ8,9504
+relay_server/static/admin.js,sha256=EDhNco6rbePqqCRXKot2tTMfKqF0sZnKwIBZDOj2D_M,31639
+relay_server/static/bootstrap.html,sha256=uVirYWB427yN5mDB1DR2dqiCEUg8Ur7j2h6EPOSFQT0,2697
+relay_server/static/bootstrap.js,sha256=g4DxT_YHVCubrv6QfHxSKx_5Gnlmae8zxYJp5YhX2xo,3654
+relay_server/static/change-password.html,sha256=_57L8uPgRXhl8X6u_6usLelnywKcnyeqVPvtZkmQkN0,2307
+relay_server/static/change-password.js,sha256=Cvk1vNVLc55r1c3PkGILwgyhHQ7qmyiOdqDcMSelP8g,2155
+relay_server/static/cluster.css,sha256=yZK2-pe5yd6PN2nX7vY0_M_eZ0yvFtMSd0KR5jopx60,18391
+relay_server/static/dashboard.html,sha256=J_DuzwsLi75ls8yi9ZNJAilZH2ceTZEv3hAXjE8HtBQ,3544
+relay_server/static/dashboard.js,sha256=oatrfNEo73wtGp_Up-1E7LchBJaCotDbTWTpuJjqAFE,787
+relay_server/static/login.html,sha256=plfZHj0XsUT3K7l5RHxRj3DLG2QHQPC5rrbrLSw0Lcc,3500
+relay_server/static/login.js,sha256=gbl34W-pKilYsjLRq1cedxREIdW8HD9TMUJoGs-8soA,822
+relay_server/static/metrics.html,sha256=V3fALtBFYOdG8vyTDN-5F93_gfZur06oANOqYmYHM8I,4511
+relay_server/static/metrics.js,sha256=cJLByF3zzqXXaEO1R334fNrlioIGm-JkvBUg3i-E_KQ,7464
+relay_server/static/node-profile.html,sha256=tXvvNt8nEucAtEL6rBO_iMjDyH41PF1xpZLjTrmjRc4,1669
+relay_server/static/node-profile.js,sha256=DLE5Lnyddkq5FTu1V0tNdjWiK6x3FmuxnAvQjpTXZ6U,9116
+relay_server/static/user-profile.html,sha256=1S4pGEj-eGomjkBc7UcvWLpfHDKDLCzVfcEQJVyBVeg,1774
+relay_server/static/user-profile.js,sha256=FDzkFuFVt-lPWK09gh5h5ImqFQbf3ofKaMQJzUJ6yn8,5003
+relay_server/utils/__init__.py,sha256=qHkwUQnAipyD7orncfDbJCaQ47mc02h90FgWy9ad_2o,25
+iowap_server-2.0.0.dist-info/METADATA,sha256=VWbLUGwMdd9f8u_SwSY6TTTwzQnen5guJl2zsZKPH1M,5658
+iowap_server-2.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+iowap_server-2.0.0.dist-info/entry_points.txt,sha256=536srCRdIISldb77GnWGY_S8R2SpiOREmbeSOQwuNC8,95
+iowap_server-2.0.0.dist-info/top_level.txt,sha256=SL2AwoTq5YPH36IduXs42cTGL0ZEtz6h0Y_SjYcUEgU,13
+iowap_server-2.0.0.dist-info/RECORD,,

iowap_server-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

iowap_server-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+relay-recovery = relay_server.cli:main
+relay-server = relay_server.main:main

iowap_server-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 iowap-org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iowap_server-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+relay_server

relay_server/README.md

@@ -0,0 +1,97 @@
+# iowap-server
+
+**IOWAP Relay Server — API, Scheduler, Auth, Dashboard, Metrics**
+
+The relay server is the central coordinator in the IOWAP ecosystem. Nodes register their capabilities via heartbeat, and the relay matches tasks to capable nodes. It is a **purpose-agnostic scheduler** — it knows nothing about the work itself, only who can do what.
+
+## Features
+
+- **Capability Registry** — nodes heartbeat their capabilities, relay maintains a live registry
+- **Task Scheduler** — match tasks to capable nodes, claim/release lifecycle with retry
+- **Auth & Security** — token-based node auth, CSRF-protected dashboard, TLS support
+- **Dashboard** — web UI for node overview, task monitoring, capability browsing, metrics
+- **SSE Events** — real-time event stream for connected nodes
+- **Status System** — node/task/stage status registry with valid transitions
+- **Event Bus** — publish/subscribe internal events for monitoring & extensibility
+- **PostgreSQL + SQLite** — production (Postgres) and dev (SQLite) backends
+- **Docker** — `docker compose up` for one-command deployment
+- **Observability** — `/metrics` (Prometheus), `/ready` health checks, structured JSON logs
+
+## Quick Start (Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/iowap-org/iowap-server/main/install.sh | bash
+```
+
+The installer asks **native (systemd)** vs. **Docker (GHCR image)**, configures the
+database (SQLite default, PostgreSQL local/remote) and environment (homelab HTTP /
+internet TLS), creates the master admin seed, and prints the dashboard login URL.
+
+**Docker (manual)** — pre-built image on GHCR:
+
+```bash
+docker volume create relay-data
+docker run -d --name iowap-server --restart unless-stopped \
+  -p 8788:8788 \
+  -e RELAY_MASTER_SEED="$(openssl rand -hex 24)" \
+  -e RELAY_SESSION_SECRET="$(openssl rand -base64 32)" \
+  -e RELAY_SESSION_COOKIE_SECURE=false \
+  -v relay-data:/app/.relay \
+  ghcr.io/iowap-org/iowap-server:latest
+```
+
+Compose files live in [iowap-org/iowap-docker](https://github.com/iowap-org/iowap-docker) (`server/docker-compose.yml`).
+
+**Manual (source)**:
+
+```bash
+git clone --recursive https://github.com/iowap-org/iowap-server.git
+cd iowap-server
+pip install -e .            # or: pip install -e ".[postgres]"
+relay-server --host 0.0.0.0 --port 8788
+```
+
+Server starts on `http://localhost:8788` — the dashboard login is under
+`/relay/v2/dashboard/login` (master seed acts as the bootstrap admin until the
+first human admin exists).
+
+## Configuration
+
+| Env | Default | Description |
+|-----|---------|-------------|
+| `RELAY_PORT` | 8788 | Server listen port |
+| `RELAY_DB_TYPE` | sqlite | Database backend (sqlite / postgres) |
+| `RELAY_MASTER_SEED` | — | Deterministic master seed for token generation |
+| `TLS_CERTFILE` | — | TLS cert path (enables HTTPS, disables mDNS) |
+| `POSTGRES_*` | — | PostgreSQL connection (when `RELAY_DB_TYPE=postgres`) |
+
+See [iowap-docs → server/setup.md](https://github.com/iowap-org/iowap-docs/blob/main/server/setup.md) for full reference.
+
+## Architecture
+
+```
+┌──────────┐   heartbeat + capabilities    ┌───────────┐
+│  Nodes   │ ◄─────────────────────────►   │   Relay   │
+│ (any)    │   claim + complete tasks      │   Server  │
+└──────────┘                               └─────┬─────┘
+                                                  │
+                                          ┌───────┴───────┐
+                                          │   Dashboard   │
+                                          │  (HTMX/HTML)  │
+                                          └───────────────┘
+```
+
+## Docs
+
+Full documentation in [iowap-org/iowap-docs](https://github.com/iowap-org/iowap-docs):
+
+- [getting-started.md](https://github.com/iowap-org/iowap-docs/blob/main/getting-started.md) — first steps
+- [server/setup.md](https://github.com/iowap-org/iowap-docs/blob/main/server/setup.md) — full setup guide
+- [server/docker.md](https://github.com/iowap-org/iowap-docs/blob/main/server/docker.md) — Docker deployment
+- [reference/api.md](https://github.com/iowap-org/iowap-docs/blob/main/reference/api.md) — API reference
+- [server/dashboard.md](https://github.com/iowap-org/iowap-docs/blob/main/server/dashboard.md) — dashboard usage
+- [server/admin.md](https://github.com/iowap-org/iowap-docs/blob/main/server/admin.md) — administration
+
+## License
+
+MIT — see [LICENSE](LICENSE).

relay_server/__init__.py

@@ -0,0 +1,3 @@
+"""IOWAP v2.0 — Distributed agent cluster server."""
+
+__version__ = "2.0.0"

relay_server/api/__init__.py

@@ -0,0 +1 @@
+"""API routers — flat structure, no versioning."""

relay_server/api/v2/__init__.py

@@ -0,0 +1,26 @@
+"""API v2 routers — only core services."""
+
+from fastapi import APIRouter
+
+from relay_server.api.v2.admin import router as admin_router
+from relay_server.api.v2.auth import router as auth_router
+from relay_server.api.v2.cluster import router as cluster_router
+from relay_server.api.v2.dashboard import router as dashboard_router
+from relay_server.api.v2.discovery import router as discovery_router
+from relay_server.api.v2.docs import router as docs_router
+from relay_server.api.v2.events import router as events_router
+from relay_server.api.v2.presence import router as presence_router
+from relay_server.api.v2.scheduler import router as scheduler_router
+from relay_server.api.v2.storage import router as storage_router
+
+router = APIRouter()
+router.include_router(docs_router, prefix="/docs", tags=["docs"])
+router.include_router(auth_router, prefix="/auth", tags=["auth"])
+router.include_router(admin_router, prefix="/admin", tags=["admin"])
+router.include_router(discovery_router, prefix="/discovery", tags=["discovery"])
+router.include_router(scheduler_router, prefix="/scheduler", tags=["scheduler"])
+router.include_router(presence_router, prefix="/presence", tags=["presence"])
+router.include_router(events_router, prefix="/events", tags=["events"])
+router.include_router(dashboard_router, prefix="/dashboard", tags=["dashboard"])
+router.include_router(cluster_router, prefix="/cluster", tags=["cluster"])
+router.include_router(storage_router, prefix="/storage", tags=["storage"])

relay_server/api/v2/admin.py

@@ -0,0 +1,236 @@
+"""Administration router for node approval and cluster management."""
+
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from relay_server.api.v2.security import (
+    check_dashboard_permission,
+    require_admin_or_dashboard_user,
+    require_dashboard_user,
+)
+from relay_server.core.auth import approve_node
+from relay_server.core.db import log_audit_event, q
+from relay_server.models import AuthContext, NodeApproval, TokenResponse
+
+router = APIRouter()
+
+
+@router.get("/nodes")
+async def admin_list_nodes(ctx: AuthContext = Depends(require_admin_or_dashboard_user)):
+    check_dashboard_permission(ctx, "dashboard:view")
+    from relay_server.core.db import get_conn
+
+    conn = get_conn()
+    try:
+        rows = conn.execute(
+            q("SELECT node_id, node_name, endpoint, capabilities, status, role, last_seen "
+            "FROM nodes WHERE node_id != ? ORDER BY registered_at DESC", ("__dashboard_admin__",)),
+        ).fetchall()
+        return {
+            "nodes": [
+                {
+                    "node_id": r["node_id"],
+                    "node_name": r["node_name"],
+                    "endpoint": r["endpoint"],
+                    "capabilities": _parse_caps(r["capabilities"]),
+                    "status": r["status"],
+                    "role": r["role"],
+                    "last_seen": r["last_seen"],
+                }
+                for r in rows
+            ]
+        }
+    finally:
+        conn.close()
+
+
+@router.post("/nodes/{node_id}/approve", response_model=TokenResponse)
+async def admin_approve_node(
+    node_id: str,
+    body: NodeApproval,
+    ctx: AuthContext = Depends(require_admin_or_dashboard_user),
+):
+    check_dashboard_permission(ctx, "nodes:approve")
+    caps = [c.model_dump() for c in body.capabilities] if body.capabilities else None
+    token = approve_node(
+        node_id=node_id,
+        role=body.role,
+        capabilities=caps,
+        endpoint=body.endpoint,
+    )
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Pending node not found or already approved",
+        )
+    log_audit_event(
+        actor_id=ctx.node_id,
+        actor_name=ctx.node_name,
+        action="node.approve",
+        resource_type="node",
+        resource_id=node_id,
+        details=f"role={body.role}",
+    )
+    return _build_token_response(token)
+
+
+@router.post("/nodes/{node_id}/token", response_model=TokenResponse)
+async def admin_issue_node_token(
+    node_id: str,
+    ctx: AuthContext = Depends(require_admin_or_dashboard_user),
+):
+    """Issue a new runtime token for an already approved node."""
+    check_dashboard_permission(ctx, "nodes:token")
+    from relay_server.config import settings
+    from relay_server.core.auth import _create_token
+    from relay_server.core.db import get_conn
+
+    conn = get_conn()
+    try:
+        row = conn.execute(
+            q("SELECT node_id, node_name, role FROM nodes WHERE node_id = ? AND status IN (?, ?)", (node_id, "approved", "offline")),
+        ).fetchone()
+        if not row:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Approved/offline node not found",
+            )
+        # Invalidate old runtime tokens for this node to avoid ambiguity.
+        conn.execute(
+            q("DELETE FROM node_tokens WHERE node_id = ? AND token_type = ?", (node_id, "runtime")),
+        )
+        conn.commit()
+        token = _create_token(
+            node_id=row["node_id"],
+            node_name=row["node_name"],
+            role=row["role"],
+            token_type="runtime",
+            pending=False,
+            ttl_hours=settings.token_ttl_hours,
+        )
+    finally:
+        conn.close()
+
+    log_audit_event(
+        actor_id=ctx.node_id,
+        actor_name=ctx.node_name,
+        action="node.issue_token",
+        resource_type="node",
+        resource_id=node_id,
+    )
+    return _build_token_response(token)
+
+
+@router.delete("/nodes/{node_id}")
+async def admin_delete_node(
+    node_id: str,
+    ctx: AuthContext = Depends(require_admin_or_dashboard_user),
+):
+    """Delete a node and all its associated tokens and presence data."""
+    check_dashboard_permission(ctx, "nodes:delete")
+    from relay_server.core.db import get_conn
+
+    conn = get_conn()
+    try:
+        row = conn.execute(
+            q("SELECT node_id FROM nodes WHERE node_id = ?", (node_id,)),
+        ).fetchone()
+        if not row:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Node not found",
+            )
+
+        # Clean up dependent records before removing the node itself
+        # (foreign keys are enabled, so deleting in the right order is required).
+        conn.execute(q("DELETE FROM node_tokens WHERE node_id = ?", (node_id,)))
+        conn.execute(q("DELETE FROM presence WHERE node_id = ?", (node_id,)))
+        conn.execute(
+            q("UPDATE tasks SET owner_node_id = NULL WHERE owner_node_id = ?", (node_id,)),
+        )
+        # F-19: fail (not orphan) the deleted node's claimed stages + their
+        # tasks. The helper clears the claim fields on the failed rows and
+        # publishes task-level events inline; the stage-level events follow
+        # after commit below (D-2).
+        from relay_server.core.scheduler import fail_stages_of_deleted_node
+
+        now = datetime.now(UTC).isoformat()
+        failed_stage_ids = fail_stages_of_deleted_node(conn, node_id, now)
+        # D-13 (F-REV-1): terminal stages keep their claim columns as
+        # completion history (complete_stage never clears them), so the
+        # claimed-only helper above leaves those FK rows dangling. Clear the
+        # remaining node references WITHOUT touching any status — exactly
+        # what main's status-agnostic NULL-claim UPDATE did for these rows.
+        conn.execute(
+            q("UPDATE task_stages SET claimed_by = NULL, claimed_at = NULL, "
+            "claim_expires_at = NULL WHERE claimed_by = ? AND status != 'claimed'",
+            (node_id,)),
+        )
+        conn.execute(
+            q("UPDATE artifacts SET created_by = NULL WHERE created_by = ?", (node_id,)),
+        )
+        conn.execute(q("DELETE FROM nodes WHERE node_id = ?", (node_id,)))
+        conn.commit()
+        # Events AFTER commit so consumers see the final rows.
+        from relay_server.core.events import event_bus
+
+        for stage_id in failed_stage_ids:
+            event_bus.publish_sync(
+                "stage_failed", {"stage_id": stage_id, "reason": "node_deleted"}
+            )
+            event_bus.publish_sync(
+                "status_changed",
+                {
+                    "entity_type": "stage",
+                    "entity_id": stage_id,
+                    "old_status": "claimed",
+                    "new_status": "failed",
+                },
+            )
+    finally:
+        conn.close()
+
+    log_audit_event(
+        actor_id=ctx.node_id,
+        actor_name=ctx.node_name,
+        action="node.delete",
+        resource_type="node",
+        resource_id=node_id,
+    )
+    return {"deleted": True, "node_id": node_id}
+
+
+def _build_token_response(token: str) -> TokenResponse:
+    info = validate_token_safe(token)
+    return TokenResponse(
+        node_id=info["node_id"],
+        node_name=info["node_name"],
+        status=info["status"],
+        token_type="runtime",
+        token=token,
+        expires_at=info.get("expires_at", ""),
+    )
+
+
+def validate_token_safe(token: str):
+    from relay_server.core.auth import validate_token
+
+    info = validate_token(token, require_approved=False)
+    if not info:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Token created but could not be validated",
+        )
+    return info
+
+
+def _parse_caps(value):
+    import json
+
+    if not value:
+        return []
+    try:
+        return json.loads(value)
+    except Exception:
+        return []