Skip to content

SmrtHub Communication Bridge

Status: Draft (2025-11-24) Owner: Platform Engineering / Runtime Integration

Purpose

Document the contract between C# desktop components and the Python core so both sides evolve without drift. This bridge is the only supported way for runtime apps, services, and tooling to exchange data with python_core.

Topology

  • Server: python_core/net/bridge_server.py hosts a Flask + WebSocket server.
  • Binding: HTTP on http://127.0.0.1:5001 by default. Binding can be overridden via Smrt.Config but must remain loopback.
  • Transport: JSON over HTTP for commands; WebSockets (/events/ws) for push notifications.
  • Process ownership: SmrtHubSupervisor ensures the Python runtime is alive before desktop apps attempt to call the bridge.

REST endpoints

Method Path Purpose
POST /api/clipboard/process Send clipboard payloads (text/image/html fragments) for detection and routing.
POST /api/triggers/execute Execute declarative automation triggers.
POST /api/smrthub/update Push UI/status changes coming from Python into HubWindow indicators.
GET /api/status/health Poll the Python runtime for readiness; returns build hash, uptime, and module status.
GET /api/config/workspace Retrieve the active SmrtSpace configuration snapshot.
PUT /api/config/update Apply configuration updates validated by Smrt.Config.

Responses are JSON with a status field ("ok" or "error") plus payload-specific data.

WebSocket events

  • /events/ws streams JSON packets such as clipboard_processed, save_completed, runtime_warning, and heartbeat.
  • Clients must authenticate by sending the shared session token (generated by the supervisor) as the first message.
  • Events always include source, timestamp, and trace_id fields for logging parity with Smrt.Logging.

Security expectations

  1. Bind only to loopback; firewall rules that expose the port externally are unsupported.
  2. Session tokens live in Smrt.Config secure storage; do not persist or log them.
  3. Payloads are validated in Python before acting; C# callers should still reject oversized attachments (100 MB limit for clipboard uploads).
  4. If TLS is ever required, terminate locally (e.g., localhost certificate) and update this README.

Extending the bridge

  • Add a new handler under python_core/net/routes/.
  • Define request/response dataclasses in the same module so schemas stay explicit.
  • Mirror the change in the corresponding C# client (usually Smrt.SpaceBridge helpers or per-app service wrappers).
  • Update integration tests under python_core/tests and any C# tests that mock the bridge.
  • Document the new endpoint in this README and regenerate the MkDocs Architecture section so it stays in sync.

Failure handling

  • C# callers should treat 5xx responses as transient: log via Smrt.Logging, emit supervisor telemetry, and retry with exponential backoff when safe.
  • Python bridge logs land in Logs/python-net/*; use Support Bundle exports when sharing traces.
  • If the port is occupied, the supervisor restarts the Python runtime once; repeated failures escalate via the Trigger Manager.

When to update this document

  • Ports, authentication, or transport layers change.
  • New REST/WebSocket contracts are added or retired.
  • Security posture changes (e.g., TLS, mutual auth).
  • Supervisor ownership or bootstrap sequencing changes.