Update deps and publish config schema

k0swe · Mar 17, 2024 · 91d1c41 · 91d1c41
1 parent a698985
commit 91d1c41
Show file tree

Hide file tree

Showing 14 changed files with 299 additions and 91 deletions.
diff --git a/Makefile b/Makefile
@@ -1,4 +1,5 @@
-VERSION = $(shell < debian/changelog head -1 | egrep -o "[0-9]+\.[0-9]+\.[0-9]+")
+export ROOT_DIR = $(shell git rev-parse --show-toplevel)
+VERSION = $(shell head -1 < debian/changelog | egrep -o "[0-9]+\.[0-9]+\.[0-9]+")
 GITCOMMIT = $(shell git rev-parse --short HEAD 2> /dev/null || true)
 
 GENERATED = kel-agent kel-agent_*.pkg win/kel-agent_*.msi win/kel-agent.wixobj autorevision.cache \
@@ -39,27 +40,27 @@ deb-orig-tarball: autorevision.cache
 	cd .. && tar -cvJf kel-agent_$(VERSION).orig.tar.xz --exclude-vcs --exclude=debian --exclude=.github --exclude=.idea kel-agent
 
 # TODO: This target can be removed once the package is in Debian stable and Ubuntu stable
-../golang-github-k0swe-wsjtx-go-dev_4.0.1-1_all.deb:
-	wget https://github.com/k0swe/wsjtx-go/releases/download/v4.0.1/golang-github-k0swe-wsjtx-go-dev_4.0.1-1_all.deb \
-	-O ../golang-github-k0swe-wsjtx-go-dev_4.0.1-1_all.deb
+../golang-github-k0swe-wsjtx-go-dev_4.0.6-1_all.deb:
+	wget https://github.com/k0swe/wsjtx-go/releases/download/v4.0.1/golang-github-k0swe-wsjtx-go-dev_4.0.6-1_all.deb \
+	-O ../golang-github-k0swe-wsjtx-go-dev_4.0.6-1_all.deb
 
 # TODO: This target can be removed once the package is in Debian stable and Ubuntu stable
-../golang-github-mazznoer-csscolorparser-dev_0.1.2-1_all.deb:
-	wget https://github.com/k0swe/wsjtx-go/releases/download/v4.0.1/golang-github-mazznoer-csscolorparser-dev_0.1.2-1_all.deb \
-	-O ../golang-github-mazznoer-csscolorparser-dev_0.1.2-1_all.deb
+../golang-github-mazznoer-csscolorparser-dev_0.1.3-1_all.deb:
+	wget https://github.com/k0swe/wsjtx-go/releases/download/v4.0.1/golang-github-mazznoer-csscolorparser-dev_0.1.3-1_all.deb \
+	-O ../golang-github-mazznoer-csscolorparser-dev_0.1.3-1_all.deb
 
 # TODO: This target can be removed once the package is in Debian stable and Ubuntu stable
 ../golang-github-adrg-xdg-dev_0.4.0-1_all.deb:
 	wget http://ftp.us.debian.org/debian/pool/main/g/golang-github-adrg-xdg/golang-github-adrg-xdg-dev_0.4.0-1_all.deb \
 	-O ../golang-github-adrg-xdg-dev_0.4.0-1_all.deb
 
 .PHONY: deb-package
-deb-package: deb-tarball ../golang-github-k0swe-wsjtx-go-dev_4.0.1-1_all.deb ../golang-github-adrg-xdg-dev_0.4.0-1_all.deb ../golang-github-mazznoer-csscolorparser-dev_0.1.2-1_all.deb
+deb-package: deb-tarball ../golang-github-k0swe-wsjtx-go-dev_4.0.6-1_all.deb ../golang-github-adrg-xdg-dev_0.4.0-1_all.deb ../golang-github-mazznoer-csscolorparser-dev_0.1.3-1_all.deb
 	# https://wiki.debian.org/sbuild
 	sbuild -d stable \
-      --extra-package=../golang-github-k0swe-wsjtx-go-dev_4.0.1-1_all.deb \
+      --extra-package=../golang-github-k0swe-wsjtx-go-dev_4.0.6-1_all.deb \
       --extra-package=../golang-github-adrg-xdg-dev_0.4.0-1_all.deb \
-      --extra-package=../golang-github-mazznoer-csscolorparser-dev_0.1.2-1_all.deb
+      --extra-package=../golang-github-mazznoer-csscolorparser-dev_0.1.3-1_all.deb
 
 .PHONY: flatpak
 flatpak: kel-agent

diff --git a/README.md b/README.md
@@ -21,5 +21,5 @@ See the [Running documentation](RUNNING.md) for how to configure, execute and se
 
 ## Acknowledgements
 
-The wire logo for `kel-agent` was created by [Freepik](https://www.flaticon.com/authors/freepik)
-on [Flaticon](https://www.flaticon.com).
+The wire logo for `kel-agent` was created by [Freepik](https://www.flaticon.com/authors/freepik) on
+[Flaticon](https://www.flaticon.com).
diff --git a/RUNNING.md b/RUNNING.md
@@ -1,24 +1,45 @@
-# Running `kel-agent`
+# Configuring and Running `kel-agent`
 
-## Running on localhost
+`kel-agent` configuration is primarily done with a YAML file; the default location is
+platform-dependent but can be listed with `kel-agent -h`. Many options can also be set with
+command-line arguments.
 
-In the simplest case, `kel-agent` is running on the same computer as your radio programs and
-browser. In this case, you can have `kel-agent` bind to `localhost` which will only allow programs
-on the same computer to connect. This is straightforward, safe and the default.
+## Websocket Server
+
+Default configuration:
 
+```yaml
+websocket:
+  address: localhost
+  port: 8081
+  allowedOrigins:
+    - https://forester.radio
 ```
+
+### Running on localhost
+
+In the simplest case, `kel-agent` is running on the same computer as your radio programs and
+browser. In this case, you can have `kel-agent` bind to `address: localhost` which will only allow
+programs on the same computer to connect. This is straightforward, safe and the default.
+
+```shell
 $ kel-agent
-2020/10/10 18:50:32 kel-agent ready to serve at ws://localhost:8081
+7:19PM INF Serving websocket address=ws://localhost:8081/websocket
 ```
 
-To use a different port, add the `host` argument.
+To use a different port, use `websocket.port` YAML config or the `host` program argument.
 
+```yaml
+websocket:
+  port: 9988
 ```
-$ kel-agent -host localhost:9988
-2020/10/10 20:06:39 kel-agent ready to serve at ws://localhost:9988
+
+```shell
+$ kel-agent
+7:19PM INF Serving websocket address=ws://localhost:9988/websocket
 ```
 
-## Running on another machine
+### Running on another machine
 
 If you want to run your radio programs and `kel-agent` on one computer and your browser on another,
 this is possible. There are a couple of approaches. Neither is super easy, which I hope to fix.
@@ -27,7 +48,7 @@ NOTE: I do _not_ recommend serving this in a way that's exposed to the internet
 _no_ authentication. If exposed to the internet, anyone could potentially initiate transmissions
 with your radio.
 
-### SSH port forwarding
+#### SSH port forwarding
 
 This method is relatively simple and quick to execute, but is more brittle than serving secure
 websockets because there is some setup each time you want to use the agent remotely, and
@@ -36,15 +57,15 @@ conceptually a little harder. Your remote machine must be running an SSH server
 On the remote machine with your radio software, run `kel-agent` normally. It can be bound to
 `localhost`.
 
-```
+```shell
 $ kel-agent
-2020/10/10 18:50:32 kel-agent ready to serve at ws://localhost:8081
+7:19PM INF Serving websocket address=ws://localhost:8081/websocket
 ```
 
 On the machine with your browser, start a command line and establish an SSH tunnel with port
 forwarding:
 
-```
+```shell
 $ ssh -N -L localhost:8081:localhost:8081 radio-pi
 ```
 
@@ -59,14 +80,24 @@ Now your web application can be configured to connect to `localhost`. Traffic bo
 `localhost:8081` will get securely forwarded to the remote machine. Both the browser and `kel-agent`
 think they're talking to local processes, and you won't get mixed content warnings.
 
-### Secure Websocket with TLS
+#### Secure Websocket with TLS
 
 This method needs a little more set up ahead of time, but is easier to use once it's set up.
 
 First, you'll need `kel-agent` to bind to `0.0.0.0` to allow connections from other computers.
 Second, due to the mixed content policy which is standard in web browsers, you'll need to specify a
-TLS certificate and private key. Eventually I hope to make this easy, but for now you'll need to
-follow https://stackoverflow.com/a/60516812/587091. In short,
+TLS certificate and private key for `kel-agent` to use. The easy way to do this is to use the
+[Let's Encrypt](https://letsencrypt.org/) free public service to generate the private key and
+certificate for you, signed by LE's certificate authority and recognized by almost all browsers.
+Using LE usually assumes that there's a
+[web server exposed to the internet](https://letsencrypt.org/docs/challenge-types/#http-01-challenge)
+(again, I _don't_ recommend this with `kel-agent`). There's also a
+[`dns-01` challenge](https://letsencrypt.org/docs/challenge-types/) if you have a domain name that
+the remote computer can be addressed by, even if it's not accessible on the internet.
+
+If Let's Encrypt is not an option for you, you'll need to follow
+https://stackoverflow.com/a/60516812/587091 to manually generate your private key and certificate.
+In short,
 
 1. generate a CA key and root certificate, then
 2. a server key and certificate signing request with the server's hostname,
@@ -75,23 +106,60 @@ follow https://stackoverflow.com/a/60516812/587091. In short,
 
 Yeah, I really need to make this easier.
 
+```yaml
+websocket:
+  address: 0.0.0.0
+  port: 8081
+  cert: /home/joe/.config/kel-agent/fullchain.pem
+  key: /home/joe/.config/kel-agent/privkey.pem
 ```
-$ kel-agent -host 0.0.0.0:8081 -key server.key -cert server.crt
-2020/10/10 19:05:39 kel-agent ready to serve at wss://0.0.0.0:8081
+
+```shell
+$ kel-agent
+7:19PM INF Serving websocket address=wss://radio-pi.myhome.net:8081/websocket
 ```
 
+Notice that the log message doesn't just say `ws://` but `wss://` which means "secure websocket."
 Once running this way, your web application can be configured to connect directly to the remote
 computer.
 
-## Allowed origins
+### Allowed origins
 
 As part of the same-origin policy which is standard in web browsers, `kel-agent` will only accept
 browser connections from certain origins (basically, websites). By default, only the website
 `https://forester.radio` plus some local developer addresses are allowed to connect to `kel-agent`,
 but this can be customized if others develop web applications that use `kel-agent`. I'm happy to
 accept pull requests to expand the default list!
 
+```yaml
+websocket:
+  allowedOrigins:
+    - https://forester.radio
+    - https://someother.nifty.app
 ```
-$ kel-agent -origins "https://forester.radio,https://someother.nifty.app"
-2020/10/10 19:18:52 Allowed origins are [https://forester.radio https://someother.nifty.app]
+
+```shell
+$ kel-agent
+7:19PM INF allowed origins origins=["https://forester.radio","https://someother.nifty.app"]
 ```
+
+## WSJT-X
+
+`kel-agent` can be used with WSJT-X to automate the process of logging contacts. WSJT-X will attempt
+to connect to something listening on UDP port 2237 by default; `kel-agent` listens there and will
+pass the contact information to the web application.
+
+```yaml
+wsjtx:
+  enabled: true
+  address: 224.0.0.1
+  port: 2237
+```
+
+```shell
+$ kel-agent
+7:19PM INF Listening to WSJT-X on UDP address=224.0.0.1:2237
+```
+
+Note that 224.0.0.1 is the multicast address that WSJT-X uses by default on Linux and Mac. On
+Windows, `kel-agent` listens by default instead on 127.0.0.1. This matches WSJT-X's behavior.
diff --git a/assets/config-schema.json b/assets/config-schema.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/k0swe/kel-agent/internal/config/config",
+  "$ref": "#/$defs/Config",
+  "$defs": {
+    "Config": {
+      "properties": {
+        "websocket": {
+          "$ref": "#/$defs/WebsocketConfig"
+        },
+        "wsjtx": {
+          "$ref": "#/$defs/WsjtxConfig"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object"
+    },
+    "WebsocketConfig": {
+      "properties": {
+        "address": {
+          "type": "string"
+        },
+        "port": {
+          "type": "integer"
+        },
+        "key": {
+          "type": "string"
+        },
+        "cert": {
+          "type": "string"
+        },
+        "allowedOrigins": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object"
+    },
+    "WsjtxConfig": {
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "address": {
+          "type": "string"
+        },
+        "port": {
+          "type": "integer"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "enabled"
+      ]
+    }
+  }
+}
diff --git a/assets/modules.txt b/assets/modules.txt
@@ -1,42 +1,67 @@
+# dario.cat/mergo v1.0.0
+## explicit; go 1.13
+dario.cat/mergo
 # github.com/adrg/xdg v0.4.0
-## explicit
+## explicit; go 1.14
 github.com/adrg/xdg
 github.com/adrg/xdg/internal/pathutil
-# github.com/davecgh/go-spew v1.1.0
-github.com/davecgh/go-spew/spew
-# github.com/gorilla/websocket v1.5.0
+# github.com/bahlo/generic-list-go v0.2.0
+## explicit; go 1.18
+github.com/bahlo/generic-list-go
+# github.com/buger/jsonparser v1.1.1
+## explicit; go 1.13
+github.com/buger/jsonparser
+# github.com/davecgh/go-spew v1.1.1
 ## explicit
+github.com/davecgh/go-spew/spew
+# github.com/gorilla/websocket v1.5.1
+## explicit; go 1.20
 github.com/gorilla/websocket
-# dario.cat/mergo v0.3.13
-## explicit
-dario.cat/mergo
-# github.com/k0swe/wsjtx-go/v4 v4.0.1
-## explicit
+# github.com/invopop/jsonschema v0.12.0
+## explicit; go 1.18
+github.com/invopop/jsonschema
+# github.com/k0swe/wsjtx-go/v4 v4.0.6
+## explicit; go 1.19
 github.com/k0swe/wsjtx-go/v4
 # github.com/leemcloughlin/jdn v0.0.0-20201102080031-6f88db6a6bf2
+## explicit
 github.com/leemcloughlin/jdn
-# github.com/mattn/go-colorable v0.1.12
+# github.com/mailru/easyjson v0.7.7
+## explicit; go 1.12
+github.com/mailru/easyjson/buffer
+github.com/mailru/easyjson/jwriter
+# github.com/mattn/go-colorable v0.1.13
+## explicit; go 1.15
 github.com/mattn/go-colorable
-# github.com/mattn/go-isatty v0.0.14
+# github.com/mattn/go-isatty v0.0.20
+## explicit; go 1.15
 github.com/mattn/go-isatty
-# github.com/mazznoer/csscolorparser v0.1.2
+# github.com/mazznoer/csscolorparser v0.1.3
+## explicit; go 1.15
 github.com/mazznoer/csscolorparser
 # github.com/pmezard/go-difflib v1.0.0
-github.com/pmezard/go-difflib/difflib
-# github.com/rs/zerolog v1.27.0
 ## explicit
+github.com/pmezard/go-difflib/difflib
+# github.com/rs/zerolog v1.32.0
+## explicit; go 1.15
 github.com/rs/zerolog
 github.com/rs/zerolog/internal/cbor
 github.com/rs/zerolog/internal/json
 github.com/rs/zerolog/log
-# github.com/stretchr/testify v1.7.2
-## explicit
+# github.com/stretchr/testify v1.9.0
+## explicit; go 1.17
 github.com/stretchr/testify/assert
 github.com/stretchr/testify/require
 github.com/stretchr/testify/suite
-# golang.org/x/sys v0.0.0-20220610221304-9f5ed59c137d
-## explicit
-golang.org/x/sys/internal/unsafeheader
+# github.com/wk8/go-ordered-map/v2 v2.1.8
+## explicit; go 1.18
+github.com/wk8/go-ordered-map/v2
+# golang.org/x/net v0.22.0
+## explicit; go 1.18
+golang.org/x/net/internal/socks
+golang.org/x/net/proxy
+# golang.org/x/sys v0.18.0
+## explicit; go 1.18
 golang.org/x/sys/unix
 golang.org/x/sys/windows
 # gopkg.in/yaml.v3 v3.0.1

diff --git a/cmd/schema/main.go b/cmd/schema/main.go
@@ -0,0 +1,13 @@
+package main
+
+import (
+	"fmt"
+	"github.com/invopop/jsonschema"
+	"github.com/k0swe/kel-agent/internal/config"
+)
+
+func main() {
+	sch := jsonschema.Reflect(config.Config{})
+	schema, _ := sch.MarshalJSON()
+	fmt.Println(string(schema))
+}