From 0bdaae266fa11ddbc7f0075b5a7e8ec83132c7a7 Mon Sep 17 00:00:00 2001 From: John Dempsey <1750243+mcfnord@users.noreply.github.com> Date: Mon, 10 Jul 2023 18:37:40 -0700 Subject: [PATCH 1/7] ip server connection tips in script and product --- docs/JSON-RPC.md | 11 +++++++++++ tools/generate_json_rpc_docs.py | 11 +++++++++++ 2 files changed, 22 insertions(+) diff --git a/docs/JSON-RPC.md b/docs/JSON-RPC.md index 3f82ced8b2..70f110805f 100644 --- a/docs/JSON-RPC.md +++ b/docs/JSON-RPC.md @@ -29,6 +29,17 @@ 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. +**Tip:** On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. On Windows, you can download 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 index 42ea437a62..b267e8fa09 100755 --- a/tools/generate_json_rpc_docs.py +++ b/tools/generate_json_rpc_docs.py @@ -211,6 +211,17 @@ def to_markdown(self): - A **response** from Jamulus to the consumer. - A **notification** from Jamulus to the consumer. +**Tip:** On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. On Windows, you can download 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: From 7799c4c5a87097f42de900ce237adfa1818ddc37 Mon Sep 17 00:00:00 2001 From: John Dempsey <1750243+mcfnord@users.noreply.github.com> Date: Tue, 11 Jul 2023 13:53:24 -0700 Subject: [PATCH 2/7] Update tools/generate_json_rpc_docs.py Co-authored-by: ann0see <20726856+ann0see@users.noreply.github.com> --- tools/generate_json_rpc_docs.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/tools/generate_json_rpc_docs.py b/tools/generate_json_rpc_docs.py index b267e8fa09..79c8a94c23 100755 --- a/tools/generate_json_rpc_docs.py +++ b/tools/generate_json_rpc_docs.py @@ -211,7 +211,13 @@ def to_markdown(self): - A **response** from Jamulus to the consumer. - A **notification** from Jamulus to the consumer. -**Tip:** On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. On Windows, you can download and use the `ncat` CLI tool. This snippet uses [jayson](https://www.npmjs.com/package/jayson) to connect using Node.js: +## Connecting to the JSON-RPC server + +On **Linux**, you can use the `nc` CLI tool. + +On **Windows**, you can download and use the `ncat` CLI tool. + +To control the JSON-RPC server programmatically, you can use a package like [jayson](https://www.npmjs.com/package/jayson) for Node.js line this: ``` const jayson = require("jayson/promise"); From 74bfa372d8b04180efda3618d9e1c28df4007c31 Mon Sep 17 00:00:00 2001 From: John Dempsey <1750243+mcfnord@users.noreply.github.com> Date: Tue, 11 Jul 2023 13:56:22 -0700 Subject: [PATCH 3/7] Update docs/JSON-RPC.md --- docs/JSON-RPC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/JSON-RPC.md b/docs/JSON-RPC.md index 70f110805f..63835ac98a 100644 --- a/docs/JSON-RPC.md +++ b/docs/JSON-RPC.md @@ -29,7 +29,7 @@ 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. -**Tip:** On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. On Windows, you can download and use the `ncat` CLI tool. This snippet uses [jayson](https://www.npmjs.com/package/jayson) to connect using Node.js: +**Connection Tips:** 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"); From ec9d9d4633c31c4303a21ec69f83761328d9b4d2 Mon Sep 17 00:00:00 2001 From: John Dempsey <1750243+mcfnord@users.noreply.github.com> Date: Tue, 11 Jul 2023 14:04:45 -0700 Subject: [PATCH 4/7] iterated draft --- docs/JSON-RPC.md | 8 +++++++- tools/generate_json_rpc_docs.py | 8 +++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/JSON-RPC.md b/docs/JSON-RPC.md index 70f110805f..5d30a863ea 100644 --- a/docs/JSON-RPC.md +++ b/docs/JSON-RPC.md @@ -29,7 +29,13 @@ 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. -**Tip:** On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. On Windows, you can download and use the `ncat` CLI tool. This snippet uses [jayson](https://www.npmjs.com/package/jayson) to connect using Node.js: +## 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"); diff --git a/tools/generate_json_rpc_docs.py b/tools/generate_json_rpc_docs.py index b267e8fa09..da0a9a32ec 100755 --- a/tools/generate_json_rpc_docs.py +++ b/tools/generate_json_rpc_docs.py @@ -211,7 +211,13 @@ def to_markdown(self): - A **response** from Jamulus to the consumer. - A **notification** from Jamulus to the consumer. -**Tip:** On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. On Windows, you can download and use the `ncat` CLI tool. This snippet uses [jayson](https://www.npmjs.com/package/jayson) to connect using Node.js: +## 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"); From fcdd4b8579d08e66c8cf9c794226215053c73e40 Mon Sep 17 00:00:00 2001 From: John Dempsey <1750243+mcfnord@users.noreply.github.com> Date: Tue, 11 Jul 2023 14:24:34 -0700 Subject: [PATCH 5/7] disambiguate by changing primary name --- docs/JSON-RPC.md | 18 +++++++++--------- tools/generate_json_rpc_docs.py | 18 +++++++++--------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/JSON-RPC.md b/docs/JSON-RPC.md index 5d30a863ea..0f529ea7b6 100644 --- a/docs/JSON-RPC.md +++ b/docs/JSON-RPC.md @@ -1,5 +1,5 @@ -# Jamulus JSON-RPC Documentation +# Jamulus JSON-RPC Interface Documentation -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 --jsonrpcsecretfile /file/with/a/secret.txt` options. -This will start a JSON-RPC server on the specified port on the localhost. +A JSON-RPC interface is available for both Jamulus client and server that allows programmatic access. +To add the JSON-RPC interface, run Jamulus with the `--jsonrpcport --jsonrpcsecretfile /file/with/a/secret.txt` options. +This will start a JSON-RPC interface 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. It can be generated like this: @@ -17,21 +17,21 @@ It can be generated like this: $ openssl rand -base64 10 > /file/with/a/secret.txt ``` -The JSON-RPC server defaults to listening on the local loopback network interface (127.0.0.1). +The JSON-RPC interface defaults to listening on the local loopback network interface (127.0.0.1). This can be optionally changed by using the `--jsonrpcbindip ` command line option. ## Wire protocol -The JSON-RPC server is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol, using [streaming newline-delimited JSON over TCP](https://clue.engineering/2018/introducing-reactphp-ndjson) as the transport. There are three main types of messages being exchanged: +The JSON-RPC interface is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol, using [streaming newline-delimited JSON over TCP](https://clue.engineering/2018/introducing-reactphp-ndjson) as the transport. There are three main types of messages being exchanged: - A **request** from the consumer to Jamulus. - A **response** from Jamulus to the consumer. - A **notification** from Jamulus to the consumer. -## Connect to a JSON-RPC server +## Connect to a JSON-RPC interface -On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. +On Linux, you can connect to a JSON-RPC interface using the `nc` CLI tool. On Windows, [you can download](https://nmap.org/ncat/) and use the `ncat` CLI tool. @@ -48,7 +48,7 @@ client.request('jamulusserver/getServerInfo', {}) ## Example -After opening a TCP connection to the JSON-RPC server, the connection must be authenticated: +After opening a TCP connection to the JSON-RPC interface server, the connection must be authenticated: ```json {"id":1,"jsonrpc":"2.0","method":"jamulus/apiAuth","params":{"secret": "...the secret from the file in --jsonrpcsecretfile..."}} diff --git a/tools/generate_json_rpc_docs.py b/tools/generate_json_rpc_docs.py index da0a9a32ec..5212742d70 100755 --- a/tools/generate_json_rpc_docs.py +++ b/tools/generate_json_rpc_docs.py @@ -181,7 +181,7 @@ def to_markdown(self): items.sort(key=lambda item: item.name) PREAMBLE = """ -# Jamulus JSON-RPC Documentation +# Jamulus JSON-RPC Interface Documentation -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 --jsonrpcsecretfile /file/with/a/secret.txt` options. -This will start a JSON-RPC server on the specified port on the localhost. +A JSON-RPC interface is available for both Jamulus client and server that allows programmatic access. +To add the JSON-RPC interface, run Jamulus with the `--jsonrpcport --jsonrpcsecretfile /file/with/a/secret.txt` options. +This will start a JSON-RPC interface 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. It can be generated like this: @@ -199,21 +199,21 @@ def to_markdown(self): $ openssl rand -base64 10 > /file/with/a/secret.txt ``` -The JSON-RPC server defaults to listening on the local loopback network interface (127.0.0.1). +The JSON-RPC interface defaults to listening on the local loopback network interface (127.0.0.1). This can be optionally changed by using the `--jsonrpcbindip ` command line option. ## Wire protocol -The JSON-RPC server is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol, using [streaming newline-delimited JSON over TCP](https://clue.engineering/2018/introducing-reactphp-ndjson) as the transport. There are three main types of messages being exchanged: +The JSON-RPC interface is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol, using [streaming newline-delimited JSON over TCP](https://clue.engineering/2018/introducing-reactphp-ndjson) as the transport. There are three main types of messages being exchanged: - A **request** from the consumer to Jamulus. - A **response** from Jamulus to the consumer. - A **notification** from Jamulus to the consumer. -## Connect to a JSON-RPC server +## Connect to a JSON-RPC interface -On Linux, you can connect to a JSON-RPC server using the `nc` CLI tool. +On Linux, you can connect to a JSON-RPC interface using the `nc` CLI tool. On Windows, [you can download](https://nmap.org/ncat/) and use the `ncat` CLI tool. @@ -230,7 +230,7 @@ def to_markdown(self): ## Example -After opening a TCP connection to the JSON-RPC server, the connection must be authenticated: +After opening a TCP connection to the JSON-RPC interface server, the connection must be authenticated: ```json {"id":1,"jsonrpc":"2.0","method":"jamulus/apiAuth","params":{"secret": "...the secret from the file in --jsonrpcsecretfile..."}} From a84537af0192c0dd3f3162d08b4888930a5d4f17 Mon Sep 17 00:00:00 2001 From: John Dempsey <1750243+mcfnord@users.noreply.github.com> Date: Tue, 11 Jul 2023 14:32:16 -0700 Subject: [PATCH 6/7] reverting --- tools/generate_json_rpc_docs.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/tools/generate_json_rpc_docs.py b/tools/generate_json_rpc_docs.py index 5212742d70..070ab134d3 100755 --- a/tools/generate_json_rpc_docs.py +++ b/tools/generate_json_rpc_docs.py @@ -181,7 +181,7 @@ def to_markdown(self): items.sort(key=lambda item: item.name) PREAMBLE = """ -# Jamulus JSON-RPC Interface Documentation +# Jamulus JSON-RPC Server Documentation -A JSON-RPC interface is available for both Jamulus client and server that allows programmatic access. -To add the JSON-RPC interface, run Jamulus with the `--jsonrpcport --jsonrpcsecretfile /file/with/a/secret.txt` options. -This will start a JSON-RPC interface server on the specified port on the localhost. +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 --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. It can be generated like this: @@ -199,21 +199,21 @@ def to_markdown(self): $ openssl rand -base64 10 > /file/with/a/secret.txt ``` -The JSON-RPC interface defaults to listening on the local loopback network interface (127.0.0.1). +The JSON-RPC server defaults to listening on the local loopback network interface (127.0.0.1). This can be optionally changed by using the `--jsonrpcbindip ` command line option. ## Wire protocol -The JSON-RPC interface is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol, using [streaming newline-delimited JSON over TCP](https://clue.engineering/2018/introducing-reactphp-ndjson) as the transport. There are three main types of messages being exchanged: +The JSON-RPC server is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol, using [streaming newline-delimited JSON over TCP](https://clue.engineering/2018/introducing-reactphp-ndjson) as the transport. There are three main types of messages being exchanged: - A **request** from the consumer to Jamulus. - A **response** from Jamulus to the consumer. - A **notification** from Jamulus to the consumer. -## Connect to a JSON-RPC interface +## Connect to a JSON-RPC server -On Linux, you can connect to a JSON-RPC interface using the `nc` CLI tool. +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. @@ -230,7 +230,7 @@ def to_markdown(self): ## Example -After opening a TCP connection to the JSON-RPC interface server, the connection must be authenticated: +After opening a TCP connection to the JSON-RPC server, the connection must be authenticated: ```json {"id":1,"jsonrpc":"2.0","method":"jamulus/apiAuth","params":{"secret": "...the secret from the file in --jsonrpcsecretfile..."}} From fe9befbfd3649c7e7abab7b2069216578cc48083 Mon Sep 17 00:00:00 2001 From: John Dempsey <1750243+mcfnord@users.noreply.github.com> Date: Tue, 11 Jul 2023 14:33:48 -0700 Subject: [PATCH 7/7] propogate --- docs/JSON-RPC.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/JSON-RPC.md b/docs/JSON-RPC.md index 0f529ea7b6..36cc18e087 100644 --- a/docs/JSON-RPC.md +++ b/docs/JSON-RPC.md @@ -1,5 +1,5 @@ -# Jamulus JSON-RPC Interface Documentation +# Jamulus JSON-RPC Server Documentation -A JSON-RPC interface is available for both Jamulus client and server that allows programmatic access. -To add the JSON-RPC interface, run Jamulus with the `--jsonrpcport --jsonrpcsecretfile /file/with/a/secret.txt` options. -This will start a JSON-RPC interface server on the specified port on the localhost. +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 --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. It can be generated like this: @@ -17,21 +17,21 @@ It can be generated like this: $ openssl rand -base64 10 > /file/with/a/secret.txt ``` -The JSON-RPC interface defaults to listening on the local loopback network interface (127.0.0.1). +The JSON-RPC server defaults to listening on the local loopback network interface (127.0.0.1). This can be optionally changed by using the `--jsonrpcbindip ` command line option. ## Wire protocol -The JSON-RPC interface is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol, using [streaming newline-delimited JSON over TCP](https://clue.engineering/2018/introducing-reactphp-ndjson) as the transport. There are three main types of messages being exchanged: +The JSON-RPC server is based on the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) protocol, using [streaming newline-delimited JSON over TCP](https://clue.engineering/2018/introducing-reactphp-ndjson) as the transport. There are three main types of messages being exchanged: - A **request** from the consumer to Jamulus. - A **response** from Jamulus to the consumer. - A **notification** from Jamulus to the consumer. -## Connect to a JSON-RPC interface +## Connect to a JSON-RPC server -On Linux, you can connect to a JSON-RPC interface using the `nc` CLI tool. +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. @@ -48,7 +48,7 @@ client.request('jamulusserver/getServerInfo', {}) ## Example -After opening a TCP connection to the JSON-RPC interface server, the connection must be authenticated: +After opening a TCP connection to the JSON-RPC server, the connection must be authenticated: ```json {"id":1,"jsonrpc":"2.0","method":"jamulus/apiAuth","params":{"secret": "...the secret from the file in --jsonrpcsecretfile..."}}