Skip to content

operations.md

Latest commit

 

History

History
95 lines (74 loc) · 3.33 KB

operations.md

File metadata and controls

95 lines (74 loc) · 3.33 KB
Raw

Operations

When to use HTTP vs WebSocket

Scenario Recommended transport
Normal satellite or client WebSocket (default)
Environment blocks long-lived TCP HTTP
IoT device behind HTTP-only proxy HTTP
Need TTS/STT binary streaming WebSocket + audio-binary-protocol

Polling interval

The client library (HiveMindHTTPClient) handles polling internally. For custom clients, poll /get_messages and /get_binary_messages every 1–5 seconds. Polling too frequently wastes resources; polling too slowly increases response latency.

Multi-replica deployments

HTTP keeps a short-lived server session because replies are buffered until the client polls for them. With the default memory backend, all requests for one client must reach the same listener process. Use one of these options before benchmarking or running multiple HTTP listener replicas:

  • enable sticky sessions in the reverse proxy using the hivemind_http_replica cookie or X-HiveMind-HTTP-Replica header
  • configure Redis-backed HTTP session state

Redis mode shares the connected flag and pending reply queues across replicas:

{
  "network_protocol": {
    "hivemind-http-plugin": {
      "port": 5679,
      "session_backend": "redis",
      "session_redis_url": "redis://redis:6379/0",
      "session_prefix": "hivemind-http",
      "session_ttl_s": 3600,
      "queue_ttl_s": 300
    }
  }
}

When the listener already uses hivemind-redis-db-plugin for its client database, session_redis_url may be omitted. The HTTP plugin derives the Redis host, port, db, username, password, and a per-hub key prefix from the existing server database config.

The same can be configured with environment variables:

Variable Purpose
HIVEMIND_HTTP_SESSION_BACKEND=redis Enable shared HTTP state.
HIVEMIND_HTTP_REDIS_URL=redis://... Optional override for the Redis connection URL.
HIVEMIND_HTTP_REPLICA_ID=pod-name Optional value exposed in headers/cookie.

Install the optional dependency when Redis mode is used:

pip install 'hivemind-http-protocol[redis]'

With protocol v3 the Noise session lives in the replica that performed the handshake: the CipherStates are per connection and are not in redis. A client must therefore reach the same replica for the life of its session (the hivemind_http_replica cookie or the X-HiveMind-HTTP-Replica header), or a frame routed to another replica is refused with 409 No Noise session and the client has to handshake again. Redis mode still shares the connected flag and the reply queues; it does not make v3 sessions replica-independent.

Port selection

The default WebSocket transport uses port 5678. Use 5679 (or any other available port) for the HTTP transport to avoid conflicts when running both:

{
  "network_protocol": {
    "hivemind-websocket-plugin": {"port": 5678},
    "hivemind-http-plugin": {"port": 5679}
  }
}

Authoring a transport plugin

See hivemind-websocket-protocol: authoring a transport plugin for the NetworkProtocol ABC and pyproject.toml entry-point registration pattern. The MQTT transport in this same cluster is another concrete example.

← Architecture · Home