Add JSON- RPC server connection tips (#3101)

* ip server connection tips in script and product * Update tools/generate_json_rpc_docs.py Co-authored-by: ann0see <[email protected]> * Update docs/JSON-RPC.md * iterated draft * disambiguate by changing primary name * reverting * propogate --------- Co-authored-by: ann0see <[email protected]>
jamulussoftware · Jul 22, 2023 · 4237dcb · 4237dcb
1 parent 2505a31
commit 4237dcb
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 6 deletions.
diff --git a/docs/JSON-RPC.md b/docs/JSON-RPC.md
@@ -1,14 +1,14 @@
 
-# Jamulus JSON-RPC Documentation
+# Jamulus JSON-RPC Server Documentation
 
 <!--
 This file is automatically generated from the source code.
 Do not edit this file manually.
 See `tools/generate_json_rpc_docs.py` for details.
 -->
 
-A JSON-RPC interface is available for both Jamulus client and server to allow programmatic access.
-To use the JSON-RPC interface, run Jamulus with the `--jsonrpcport <port> --jsonrpcsecretfile /file/with/a/secret.txt` options.
+A JSON-RPC server can be added to both Jamulus client and Jamulus server to allow programmatic access.
+To add the JSON-RPC server, run Jamulus with the `--jsonrpcport <port> --jsonrpcsecretfile /file/with/a/secret.txt` options.
 This will start a JSON-RPC server on the specified port on the localhost.
 
 The file referenced by `--jsonrpcsecretfile` must contain a single line with a freely chosen string with at least 16 characters.
@@ -29,6 +29,23 @@ The JSON-RPC server is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/speci
 - A **response** from Jamulus to the consumer.
 - A **notification** from Jamulus to the consumer.
 
+## Connect to a JSON-RPC server
+
+On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. 
+
+On Windows, [you can download](https://nmap.org/ncat/) and use the `ncat` CLI tool.
+
+This snippet uses [jayson](https://www.npmjs.com/package/jayson) to connect using Node.js:
+
+```
+const jayson = require("jayson/promise");
+const client = new jayson.client.tcp({ host: "127.0.0.1", port: 22100 });
+
+client.request('jamulusserver/getServerInfo', {})
+.then(console.log)
+.catch(console.error)
+```
+
 ## Example
 
 After opening a TCP connection to the JSON-RPC server, the connection must be authenticated:

diff --git a/tools/generate_json_rpc_docs.py b/tools/generate_json_rpc_docs.py
@@ -181,16 +181,16 @@ def to_markdown(self):
 items.sort(key=lambda item: item.name)
 
 PREAMBLE = """
-# Jamulus JSON-RPC Documentation
+# Jamulus JSON-RPC Server Documentation
 
 <!--
 This file is automatically generated from the source code.
 Do not edit this file manually.
 See `tools/generate_json_rpc_docs.py` for details.
 -->
 
-A JSON-RPC interface is available for both Jamulus client and server to allow programmatic access.
-To use the JSON-RPC interface, run Jamulus with the `--jsonrpcport <port> --jsonrpcsecretfile /file/with/a/secret.txt` options.
+A JSON-RPC server can be added to both Jamulus client and Jamulus server to allow programmatic access.
+To add the JSON-RPC server, run Jamulus with the `--jsonrpcport <port> --jsonrpcsecretfile /file/with/a/secret.txt` options.
 This will start a JSON-RPC server on the specified port on the localhost.
 
 The file referenced by `--jsonrpcsecretfile` must contain a single line with a freely chosen string with at least 16 characters.
@@ -211,6 +211,23 @@ def to_markdown(self):
 - A **response** from Jamulus to the consumer.
 - A **notification** from Jamulus to the consumer.
 
+## Connect to a JSON-RPC server
+
+On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. 
+
+On Windows, [you can download](https://nmap.org/ncat/) and use the `ncat` CLI tool.
+
+This snippet uses [jayson](https://www.npmjs.com/package/jayson) to connect using Node.js:
+
+```
+const jayson = require("jayson/promise");
+const client = new jayson.client.tcp({ host: "127.0.0.1", port: 22100 });
+
+client.request('jamulusserver/getServerInfo', {})
+.then(console.log)
+.catch(console.error)
+```
+
 ## Example
 
 After opening a TCP connection to the JSON-RPC server, the connection must be authenticated: