The HiveMind HTTP Protocol provides an alternative REST-based implementation for message exchange in the HiveMind ecosystem.
This plugin integrates with the hivemind-core
framework. It is not a standalone project, and its behavior is controlled by the hivemind-core
configuration.
To enable and configure the HiveMind HTTP Protocol, update the network_protocol
entry in the hivemind-core
configuration file. Below is an example configuration:
"network_protocol": {
"hivemind-websocket-plugin": {
"host": "0.0.0.0",
"port": 5678
},
"hivemind-http-plugin": {
"host": "0.0.0.0",
"port": 5679
}
}
from hivemind_bus_client.http_client import HiveMindHTTPClient, BinaryDataCallbacks
from hivemind_bus_client.message import HiveMessage, HiveMessageType
from ovos_bus_client.message import Message
class BinaryDataHandler(BinaryDataCallbacks):
def handle_receive_tts(self, bin_data: bytes,
utterance: str,
lang: str,
file_name: str):
# we can play it or save to file or whatever
print(f"got {len(bin_data)} bytes of TTS audio")
print(f"utterance: {utterance}", f"lang: {lang}", f"file_name: {file_name}")
# got 33836 bytes of TTS audio
# utterance: hello world lang: en-US file_name: 5eb63bbbe01eeed093cb22bb8f5acdc3.wav
# not passing key etc so it uses hivemind identity file for details
client = HiveMindHTTPClient(host="http://localhost", port=5679,
bin_callbacks=BinaryDataHandler())
client.emit(HiveMessage(HiveMessageType.BUS,
Message("speak:synth", {"utterance": "hello world"})))
Authentication is handled via an HTTP authorization
parameter in the request. The value should be a Base64-encoded string in the format useragent:access_key
.
Endpoint: /connect
Method: POST
Request Parameters:
authorization
(string, mandatory): Base64-encodeduseragent:access_key
.
Response:
200 OK
:{ "status": "Connected" }
400 Bad Request
:{ "error": "Missing authorization" }
500 Internal Server Error
:{ "error": "Connection failed" }
Endpoint: /disconnect
Method: POST
Request Parameters:
authorization
(string, mandatory): Base64-encodeduseragent:access_key
.
Response:
200 OK
:{ "status": "Disconnected" }
400 Bad Request
:{ "error": "Missing authorization" }
500 Internal Server Error
:{ "error": "Disconnection failed" }
Endpoint: /send_message
Method: POST
Request Parameters:
authorization
(string, mandatory): Base64-encodeduseragent:access_key
.message
(string, mandatory): Encoded message payload.
Response:
200 OK
:{ "status": "message sent" }
400 Bad Request
:{ "error": "Missing message" }
500 Internal Server Error
:{ "error": "Message sending failed" }
Endpoint: /get_messages
Method: GET
Request Parameters:
authorization
(string, mandatory): Base64-encodeduseragent:access_key
.
Response:
200 OK
:{ "messages": ["message1", "message2"] }
400 Bad Request
:{ "error": "Missing authorization" }
500 Internal Server Error
:{ "error": "Failed to retrieve messages" }
Endpoint: /get_binary_messages
Method: GET
Request Parameters:
authorization
(string, mandatory): Base64-encodeduseragent:access_key
.
Response:
200 OK
:{ "messages": ["Base64Message1", "Base64Message2"] }
400 Bad Request
:{ "error": "Missing authorization" }
500 Internal Server Error
:{ "error": "Failed to retrieve messages" }
- The
connect
anddisconnect
endpoints enable state management in scenarios where persistent connections are not feasible - Binary messages are Base64-encoded to ensure compatibility with REST APIs, which are text-based protocols.
Contributions are welcome! Please submit a pull request or open an issue for bug reports or feature requests.
This project is licensed under the Apache 2.0 License. See the LICENSE
file for more details.