hivemind-http-protocol 0.0.2a1__tar.gz → 0.0.2a3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/PKG-INFO +1 -1
- hivemind_http_protocol-0.0.2a3/README.md +121 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol/version.py +1 -1
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol.egg-info/PKG-INFO +1 -1
- hivemind_http_protocol-0.0.2a1/README.md +0 -158
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/LICENSE.md +0 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol/__init__.py +0 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol.egg-info/SOURCES.txt +0 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol.egg-info/dependency_links.txt +0 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol.egg-info/entry_points.txt +0 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol.egg-info/requires.txt +0 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol.egg-info/top_level.txt +0 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/setup.cfg +0 -0
- {hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/setup.py +0 -0
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# hivemind-http-protocol
|
|
2
|
+
|
|
3
|
+
REST/HTTP transport plugin for [hivemind-core](https://github.com/JarbasHiveMind/HiveMind-core).
|
|
4
|
+
|
|
5
|
+
An alternative to the default WebSocket transport. Clients use HTTP polling (POST to send,
|
|
6
|
+
GET to receive) instead of a persistent WebSocket connection. Suitable for environments where
|
|
7
|
+
long-lived TCP connections are not possible (firewalls, IoT gateways, HTTP-only proxies).
|
|
8
|
+
|
|
9
|
+
## Where it fits
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
hivemind-core
|
|
13
|
+
└── hivemind-plugin-manager (NetworkProtocolFactory loads plugins by entry-point)
|
|
14
|
+
└── hivemind-http-protocol ← this repo
|
|
15
|
+
└── Tornado HTTP server (REST endpoints)
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The plugin registers under the `hivemind.network.protocol` entry-point group as
|
|
19
|
+
`hivemind-http-plugin`. It can run alongside the WebSocket transport if both are listed
|
|
20
|
+
in the `network_protocol` config.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pip install hivemind-http-protocol
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Quickstart
|
|
29
|
+
|
|
30
|
+
Add to `~/.config/hivemind-core/server.json`:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"network_protocol": {
|
|
35
|
+
"module": "hivemind-http-plugin",
|
|
36
|
+
"hivemind-http-plugin": {
|
|
37
|
+
"host": "0.0.0.0",
|
|
38
|
+
"port": 5679
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Start hivemind-core:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
hivemind-core listen
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Running alongside WebSocket
|
|
51
|
+
|
|
52
|
+
Both transports can run at the same time by configuring them both:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"network_protocol": {
|
|
57
|
+
"hivemind-websocket-plugin": {
|
|
58
|
+
"host": "0.0.0.0",
|
|
59
|
+
"port": 5678
|
|
60
|
+
},
|
|
61
|
+
"hivemind-http-plugin": {
|
|
62
|
+
"host": "0.0.0.0",
|
|
63
|
+
"port": 5679
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Python client example
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from hivemind_bus_client.http_client import HiveMindHTTPClient, BinaryDataCallbacks
|
|
73
|
+
from hivemind_bus_client.message import HiveMessage, HiveMessageType
|
|
74
|
+
from ovos_bus_client.message import Message
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class MyBinaryCallbacks(BinaryDataCallbacks):
|
|
78
|
+
def handle_receive_tts(self, bin_data: bytes, utterance: str,
|
|
79
|
+
lang: str, file_name: str):
|
|
80
|
+
print(f"received {len(bin_data)} bytes of TTS for: {utterance}")
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
client = HiveMindHTTPClient(
|
|
84
|
+
host="http://localhost",
|
|
85
|
+
port=5679,
|
|
86
|
+
bin_callbacks=MyBinaryCallbacks(),
|
|
87
|
+
)
|
|
88
|
+
client.emit(HiveMessage(HiveMessageType.BUS,
|
|
89
|
+
Message("speak:synth", {"utterance": "hello world"})))
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Configuration reference
|
|
93
|
+
|
|
94
|
+
| Key | Default | Description |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| `host` | `0.0.0.0` | Bind address. |
|
|
97
|
+
| `port` | `5679` | Listen port. |
|
|
98
|
+
| `ssl` | `false` | Enable TLS. |
|
|
99
|
+
| `cert_dir` | `$XDG_DATA_HOME/hivemind` | Directory for TLS cert/key files. |
|
|
100
|
+
| `cert_name` | `hivemind` | Base filename for cert and key. |
|
|
101
|
+
|
|
102
|
+
## REST API
|
|
103
|
+
|
|
104
|
+
Authentication uses an HTTP `authorization` parameter (not a header) containing
|
|
105
|
+
a Base64-encoded `useragent:access_key` string.
|
|
106
|
+
|
|
107
|
+
| Endpoint | Method | Description |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| `/connect` | POST | Register a client session. Parameters: `authorization`. |
|
|
110
|
+
| `/disconnect` | POST | Remove a client session. Parameters: `authorization`. |
|
|
111
|
+
| `/send_message` | POST | Send a HiveMessage. Parameters: `authorization`, `message`. |
|
|
112
|
+
| `/get_messages` | GET | Poll for pending text messages. Parameters: `authorization`. |
|
|
113
|
+
| `/get_binary_messages` | GET | Poll for pending binary messages (Base64-encoded). Parameters: `authorization`. |
|
|
114
|
+
|
|
115
|
+
See [docs/api.md](docs/api.md) for full endpoint documentation.
|
|
116
|
+
|
|
117
|
+
## Docs
|
|
118
|
+
|
|
119
|
+
- [docs/api.md](docs/api.md) — REST endpoint reference
|
|
120
|
+
- [docs/architecture.md](docs/architecture.md) — handler lifecycle, polling model, TLS
|
|
121
|
+
- [docs/operations.md](docs/operations.md) — authoring a transport plugin
|
|
@@ -1,158 +0,0 @@
|
|
|
1
|
-
# HiveMind HTTP Protocol
|
|
2
|
-
|
|
3
|
-
The HiveMind HTTP Protocol provides an alternative REST-based implementation for message exchange in the HiveMind ecosystem.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## Configuration
|
|
9
|
-
|
|
10
|
-
This plugin integrates with the `hivemind-core` framework. It is not a standalone project, and its behavior is controlled by the `hivemind-core` configuration.
|
|
11
|
-
|
|
12
|
-
To enable and configure the HiveMind HTTP Protocol, update the `network_protocol` entry in the `hivemind-core` configuration file. Below is an example configuration:
|
|
13
|
-
|
|
14
|
-
```json
|
|
15
|
-
"network_protocol": {
|
|
16
|
-
"hivemind-websocket-plugin": {
|
|
17
|
-
"host": "0.0.0.0",
|
|
18
|
-
"port": 5678
|
|
19
|
-
},
|
|
20
|
-
"hivemind-http-plugin": {
|
|
21
|
-
"host": "0.0.0.0",
|
|
22
|
-
"port": 5679
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
## Client Library
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
```python
|
|
32
|
-
from hivemind_bus_client.http_client import HiveMindHTTPClient, BinaryDataCallbacks
|
|
33
|
-
from hivemind_bus_client.message import HiveMessage, HiveMessageType
|
|
34
|
-
from ovos_bus_client.message import Message
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
class BinaryDataHandler(BinaryDataCallbacks):
|
|
38
|
-
def handle_receive_tts(self, bin_data: bytes,
|
|
39
|
-
utterance: str,
|
|
40
|
-
lang: str,
|
|
41
|
-
file_name: str):
|
|
42
|
-
# we can play it or save to file or whatever
|
|
43
|
-
print(f"got {len(bin_data)} bytes of TTS audio")
|
|
44
|
-
print(f"utterance: {utterance}", f"lang: {lang}", f"file_name: {file_name}")
|
|
45
|
-
# got 33836 bytes of TTS audio
|
|
46
|
-
# utterance: hello world lang: en-US file_name: 5eb63bbbe01eeed093cb22bb8f5acdc3.wav
|
|
47
|
-
|
|
48
|
-
# not passing key etc so it uses hivemind identity file for details
|
|
49
|
-
client = HiveMindHTTPClient(host="http://localhost", port=5679,
|
|
50
|
-
bin_callbacks=BinaryDataHandler())
|
|
51
|
-
|
|
52
|
-
client.emit(HiveMessage(HiveMessageType.BUS,
|
|
53
|
-
Message("speak:synth", {"utterance": "hello world"})))
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
---
|
|
57
|
-
|
|
58
|
-
## REST API Documentation
|
|
59
|
-
|
|
60
|
-
### Authentication
|
|
61
|
-
|
|
62
|
-
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`.
|
|
63
|
-
|
|
64
|
-
### Endpoints
|
|
65
|
-
|
|
66
|
-
#### 1. Connect to the Server
|
|
67
|
-
|
|
68
|
-
**Endpoint:** `/connect`
|
|
69
|
-
**Method:** `POST`
|
|
70
|
-
|
|
71
|
-
**Request Parameters:**
|
|
72
|
-
- `authorization` (string, mandatory): Base64-encoded `useragent:access_key`.
|
|
73
|
-
|
|
74
|
-
**Response:**
|
|
75
|
-
- `200 OK`: `{ "status": "Connected" }`
|
|
76
|
-
- `400 Bad Request`: `{ "error": "Missing authorization" }`
|
|
77
|
-
- `500 Internal Server Error`: `{ "error": "Connection failed" }`
|
|
78
|
-
|
|
79
|
-
---
|
|
80
|
-
|
|
81
|
-
#### 2. Disconnect from the Server
|
|
82
|
-
|
|
83
|
-
**Endpoint:** `/disconnect`
|
|
84
|
-
**Method:** `POST`
|
|
85
|
-
|
|
86
|
-
**Request Parameters:**
|
|
87
|
-
- `authorization` (string, mandatory): Base64-encoded `useragent:access_key`.
|
|
88
|
-
|
|
89
|
-
**Response:**
|
|
90
|
-
- `200 OK`: `{ "status": "Disconnected" }`
|
|
91
|
-
- `400 Bad Request`: `{ "error": "Missing authorization" }`
|
|
92
|
-
- `500 Internal Server Error`: `{ "error": "Disconnection failed" }`
|
|
93
|
-
|
|
94
|
-
---
|
|
95
|
-
|
|
96
|
-
#### 3. Send a Message
|
|
97
|
-
|
|
98
|
-
**Endpoint:** `/send_message`
|
|
99
|
-
**Method:** `POST`
|
|
100
|
-
|
|
101
|
-
**Request Parameters:**
|
|
102
|
-
- `authorization` (string, mandatory): Base64-encoded `useragent:access_key`.
|
|
103
|
-
- `message` (string, mandatory): Encoded message payload.
|
|
104
|
-
|
|
105
|
-
**Response:**
|
|
106
|
-
- `200 OK`: `{ "status": "message sent" }`
|
|
107
|
-
- `400 Bad Request`: `{ "error": "Missing message" }`
|
|
108
|
-
- `500 Internal Server Error`: `{ "error": "Message sending failed" }`
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
#### 4. Retrieve Messages
|
|
113
|
-
|
|
114
|
-
**Endpoint:** `/get_messages`
|
|
115
|
-
**Method:** `GET`
|
|
116
|
-
|
|
117
|
-
**Request Parameters:**
|
|
118
|
-
- `authorization` (string, mandatory): Base64-encoded `useragent:access_key`.
|
|
119
|
-
|
|
120
|
-
**Response:**
|
|
121
|
-
- `200 OK`: `{ "messages": ["message1", "message2"] }`
|
|
122
|
-
- `400 Bad Request`: `{ "error": "Missing authorization" }`
|
|
123
|
-
- `500 Internal Server Error`: `{ "error": "Failed to retrieve messages" }`
|
|
124
|
-
|
|
125
|
-
---
|
|
126
|
-
|
|
127
|
-
#### 5. Retrieve Binary Messages
|
|
128
|
-
|
|
129
|
-
**Endpoint:** `/get_binary_messages`
|
|
130
|
-
**Method:** `GET`
|
|
131
|
-
|
|
132
|
-
**Request Parameters:**
|
|
133
|
-
- `authorization` (string, mandatory): Base64-encoded `useragent:access_key`.
|
|
134
|
-
|
|
135
|
-
**Response:**
|
|
136
|
-
- `200 OK`: `{ "messages": ["Base64Message1", "Base64Message2"] }`
|
|
137
|
-
- `400 Bad Request`: `{ "error": "Missing authorization" }`
|
|
138
|
-
- `500 Internal Server Error`: `{ "error": "Failed to retrieve messages" }`
|
|
139
|
-
|
|
140
|
-
---
|
|
141
|
-
|
|
142
|
-
## Notes
|
|
143
|
-
|
|
144
|
-
- The `connect` and `disconnect` endpoints enable state management in scenarios where persistent connections are not feasible
|
|
145
|
-
- Binary messages are Base64-encoded to ensure compatibility with REST APIs, which are text-based protocols.
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
---
|
|
149
|
-
|
|
150
|
-
## Contributing
|
|
151
|
-
|
|
152
|
-
Contributions are welcome! Please submit a pull request or open an issue for bug reports or feature requests.
|
|
153
|
-
|
|
154
|
-
---
|
|
155
|
-
|
|
156
|
-
## License
|
|
157
|
-
|
|
158
|
-
This project is licensed under the Apache 2.0 License. See the `LICENSE` file for more details.
|
|
File without changes
|
{hivemind_http_protocol-0.0.2a1 → hivemind_http_protocol-0.0.2a3}/hivemind_http_protocol/__init__.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|