Merge commit '10025f9fa5503865918cbae2af5366afe7fd7c54' as 'components/mycelium'

2025-08-16 21:12:34 +02:00
parent 9293ee45cb 10025f9fa5
commit 3d6caf7d91
132 changed files with 50951 additions and 0 deletions
--- a/components/mycelium/docs/message.md
+++ b/components/mycelium/docs/message.md
@@ -0,0 +1,161 @@
+# Message subsystem
+
+The message subsystem can be used to send arbitrary length messages to receivers. A receiver is any
+other node in the network. It can be identified both by its public key, or an IP address in its announced
+range. The message subsystem can be interacted with both via the HTTP API, which is
+[documented here](./api.yaml), or via the `mycelium` binary. By default, the messages do not interpret
+the data in any way. When using the binary, the message is slightly modified to include an optional
+topic at the start of the message. Note that in the HTTP API, all messages are encoded in base64. This
+might make it difficult to consume these messages without additional tooling.
+
+Messages can be categorized by topics, which can be configured with whitelisted subnets and socket forwarding paths.
+For detailed information on how to configure topics, see the [Topic Configuration Guide](./topic_configuration.md).
+
+## JSON-RPC API Examples
+
+These examples assume you have at least 2 nodes running, and that they are both part of the same network.
+
+Send a message on node1, waiting up to 2 minutes for a possible reply:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "pushMessage",
+  "params": [
+    {
+      "dst": {"pk": "bb39b4a3a4efd70f3e05e37887677e02efbda14681d0acd3882bc0f754792c32"},
+      "payload": "xuV+"
+    },
+    120
+  ],
+  "id": 1
+}
+```
+
+Using curl:
+
+```bash
+curl -X POST http://localhost:8990/rpc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "pushMessage",
+    "params": [
+      {
+        "dst": {"pk": "bb39b4a3a4efd70f3e05e37887677e02efbda14681d0acd3882bc0f754792c32"},
+        "payload": "xuV+"
+      },
+      120
+    ],
+    "id": 1
+  }'
+```
+
+Listen for a message on node2. Note that messages received while nothing is listening are added to
+a queue for later consumption. Wait for up to 1 minute.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "popMessage",
+  "params": [false, 60, null],
+  "id": 1
+}
+```
+
+Using curl:
+
+```bash
+curl -X POST http://localhost:8990/rpc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "popMessage",
+    "params": [false, 60, null],
+    "id": 1
+  }'
+```
+
+The system will (immediately) receive our previously sent message:
+
+```json
+{"id":"e47b25063912f4a9","srcIp":"34f:b680:ba6e:7ced:355f:346f:d97b:eecb","srcPk":"955bf6bea5e1150fd8e270c12e5b2fc08f08f7c5f3799d10550096cc137d671b","dstIp":"2e4:9ace:9252:630:beee:e405:74c0:d876","dstPk":"bb39b4a3a4efd70f3e05e37887677e02efbda14681d0acd3882bc0f754792c32","payload":"xuV+"}
+```
+
+To send a reply, we can post a message on the reply path, with the received message `id` (still on
+node2):
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "pushMessageReply",
+  "params": [
+    "e47b25063912f4a9",
+    {
+      "dst": {"pk":"955bf6bea5e1150fd8e270c12e5b2fc08f08f7c5f3799d10550096cc137d671b"},
+      "payload": "xuC+"
+    }
+  ],
+  "id": 1
+}
+```
+
+Using curl:
+
+```bash
+curl -X POST http://localhost:8990/rpc \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "pushMessageReply",
+    "params": [
+      "e47b25063912f4a9",
+      {
+        "dst": {"pk":"955bf6bea5e1150fd8e270c12e5b2fc08f08f7c5f3799d10550096cc137d671b"},
+        "payload": "xuC+"
+      }
+    ],
+    "id": 1
+  }'
+```
+
+If you did this fast enough, the initial sender (node1) will now receive the reply.
+
+## Mycelium binary examples
+
+As explained above, while using the binary the message is slightly modified to insert the optional
+topic. As such, when using the binary to send messages, it is suggested to make sure the receiver is
+also using the binary to listen for messages. The options discussed here are not covering all possibilities,
+use the `--help` flag (`mycelium message send --help` and `mycelium message receive --help`) for a
+full overview.
+
+Once again, send a message. This time using a topic (example.topic). Note that there are no constraints
+on what a valid topic is, other than that it is valid UTF-8, and at most 255 bytes in size. The `--wait`
+flag can be used to indicate that we are waiting for a reply. If it is set, we can also use an additional
+`--timeout` flag to govern exactly how long (in seconds) to wait for. The default is to wait forever.
+
+```bash
+mycelium message send 2e4:9ace:9252:630:beee:e405:74c0:d876 'this is a message' -t example.topic --wait
+```
+
+On the second node, listen for messages with this topic. If a different topic is used, the previous
+message won't be received. If no topic is set, all messages are received. An optional timeout flag
+can be specified, which indicates how long to wait for. Absence of this flag will cause the binary
+to wait forever.
+
+```bash
+mycelium message receive -t example.topic
+```
+
+Again, if the previous command was executed a message will be received immediately:
+
+```json
+{"id":"4a6c956e8d36381f","topic":"example.topic","srcIp":"34f:b680:ba6e:7ced:355f:346f:d97b:eecb","srcPk":"955bf6bea5e1150fd8e270c12e5b2fc08f08f7c5f3799d10550096cc137d671b","dstIp":"2e4:9ace:9252:630:beee:e405:74c0:d876","dstPk":"bb39b4a3a4efd70f3e05e37887677e02efbda14681d0acd3882bc0f754792c32","payload":"this is a message"}
+```
+
+And once again, we can use the ID from this message to reply to the original sender, who might be waiting
+for this reply (notice we used the hex encoded public key to identify the receiver here, rather than an IP):
+
+```bash
+mycelium message send 955bf6bea5e1150fd8e270c12e5b2fc08f08f7c5f3799d10550096cc137d671b "this is a reply" --reply-to 4a6c956e8d36381f
+```