Initial Alpha for GroovyMAME commands.

Author: BossRighteous

.gitignore

@@ -20,3 +20,9 @@
 # Go workspace file
 go.work
 go.work.sum
+
+cmd/cmdtest
+cmd/romparser
+dev-notes.txt
+config.json
+printargs.sh

README.md

@@ -1,68 +1,112 @@
 # GroovyMiSTerHTTP
 An HTTP client to allow remote GroovyMAME execution from MiSTer
 
-## Draft Data Contracts
+Actually it's going to be done over UDP but I'm not going to rename/readdress everything yet.
 
-### Groovy MiSTer
+## Alpha Setup Guide
+Assumes Go is installed, and I am using WSL2 on windows so my pathing and UDP is wonky but works.
+
+```
+git clone git@github.com:BossRighteous/GroovyMiSTerHTTP.git
+cd GroovyMiSTerHTTP
+cp ./spec/GmcServerConfig.json ./config.json
+// Edit JSON for mame bin paths and MiSTer IP
+go run cmd/groovymisterhttp/main.go "/path/to/GroovyMiSTerHTTP/config.json"
+```
+
+In new terminal screen, send UDP commands to server port
+```
+echo -n '{"cmd":"mame","vars":{"MACHINE_NAME":"circus"}}' >/dev/udp/localhost/32105
+
+echo -n '{"cmd":"unload"}' >/dev/udp/localhost/32105
+```
+
+### Groovy MiSTer Command (GMC) spec
 
 The Groovy MiSTer core does not currently support file browsing as there are no direct roms to load.
 The following data type is a proposed file structure the Groovy core can open as a rom-like and perform
-an HTTP RPC command against.
+UDP RPC commands against.
 
 ```
 Filename:
-{Text Title}.{GroovyMisterCommand}
-Contents: UTF-8 Text
-{UtilKeyword | MameSlug}
+{Human ReadableText Title}.gmc
+Contents: UTF-8 JSON Text
+{
+    "cmd": "mame",
+    "vars": {
+        "MACHINE_NAME": "circus"
+    }
+}
+```
 
-Examples:
-// Game Slug
-Hanabi de Doon! - Don-chan Puzzle.gmc
-doncdoon
+When the core opens the GMC file, it's contents will be streamed over UDP to the server.
+It is assumed this will be plain text, but the core will send the binary data as it. It is up
+to the server software to read and handle appropriately.
 
-// Util Keywords
-Test Connection.gmc
-connect
+This configuration is managed from the server bin via a settings JSON
+```
+{
+    "mister_host": "192.168.1.255",
+    "commands": [
+        {
+            "cmd": "mame",
+            "work_dir": "/path/to/groovymame",
+            "exec_bin": "./mame",
+            "exec_args": ["${MACHINE_NAME}"]
+        }
+    ]
+}
+```
 
-Unload Rom.gmc
-unload
+This allows the server to easily control it's command whitelist and intented variable replacements in args.
+Since the command will be executed outside of a shell context ENV and command line variable substitution isn't possible.
+Arg/Var replacement is done by the server. This also makes it much more difficult to inject escape sequences.
 
-Kill Server Process.gmc
-kill
+```
+/path/to/mybin positional -tf --foo="complex"
 
-Reboot Host Machine.gmc
-reboot
+... might become
+"cmd": "mycmd"
+"work_dir": "/path/to/",
+"exec_bin": "./mybin",
+"exec_args": ["positional", "-tf", "--foo=\"${FOO_VAL}\""]
 
-Shutdown Host Machine.gmc
-shutdown
+... and be executed by
+{"cmd":"mycmd", "vars":{"FOO_VAL":"custom"}}
 ```
 
-This is a minimal amount of information and should provide just enough data for the server to execute tasks without security concerns.
+GroovyMiSTer will know of the server by way of init beacon. Upon server boot, and every n seconds therafter,
+an init handshake will be sent to the Groovy core over UDP until the Core acknoledges.
+
+This enables the MiSTer to reply even in cases the server machine amy have a dynamic IP.
+Your GroovyMister enabled emulator will need to have it's own configuration including host/IP.
+
+The server will attempt to run asyncronous (long running processes) until exit or error.
+Any running processes will be terminated on receipt of the next GMC command over UDP.
 
-I initially considered a {command, args} schema but limiting args to single 'word' will make verification much easier.
+Messages including a stderr tail will be displayed on the MiSTer. This is under development for messaging data sources.
 
 #### Groovy MiSTer UX
 
+psakhis has conceptually reviewed the following and may go forward with something like the following
+
 Similar to many other cores a load rom menu setting may be implemented:
 ```
-Load Remote GroovyMAME *.gmc
+Load Remote Command *.gmc
 ```
 
 This will open a file browser interface, pointing to rom-like directory
 ```
-/media/fat/games/GroovyMAME/**.gmc
+/media/fat/games/Groovy/**.gmc
 ```
 
 Upon GMC file selection the core may
-- load the contents into string/chars CMD_STR
-- Check new ini/env key GROOVY_MAME_HOST (Example: "192.168.1.128")
-- Execute syncronous HTTP POST
-  - Address: "http://{GROOVY_MAME_HOST}:32105/cmd"
-  - Body: "{CMD_STR}"
-- For 200/ok response, close OSD, wait for game broadcast from PC server
-- ? For non-200 response, display error message from body or http status code
+- load binary contents up to 1024 bytes
+- Send bytes as UDP packet to acked Server socket
+- Server will manage process state and errors via text blitting back to the MiSTer
+
+#### File Browsing
 
-This could trivially be a GET request with query parameters as well. Depends on what the Core's build would best support.
 
 #### File Browsing
 I am making some assumptions here that there is a file browsing interface module the core
@@ -100,7 +144,7 @@ To keep the Core's command logic simplified, companion server-side scripts can b
         ...
 ```
 
-I've noted that .zip files are browseable as filesystem, so a single portable zip may reduce FS block fill and make the build/transfer simpler.
+I've noted that .zip files are browseable as filesystem, so a single portable zip may reduce FS block fill and make the build/transfer simpler. I don't know the limits to file density in a zip but could test this.
 
 This would allow the server binary to run a CLI command routine that
 - Asks for category/filter preferences
@@ -110,37 +154,4 @@ This would allow the server binary to run a CLI command routine that
 - Dupes into category hierarchies selected.
 - zips directory
 
-This could then be trivially SCPed and extracted.
-
-This could also be exposed as a special HTTP endpoint for a MiSTer Script to process against the remote
-
-### Groovy MiSTer HTTP Server
-
-This is a binary CLI app that will live on the GroovyMAME host machine.
-
-The IP address or hostname of the server machine should be defined in the MiSTer ini for GroovyMiSTer settings.
-
-The server binary itself should be placed in the GroovyMAME application directory for easier cross-platform build pathing. May include .ini configuration for the server's paths and ports to decouple.
-
-On execution the server will listen generically to any host, but specifically on port 32105. This port allows for additional GroovyMiSTer UDP expansion but occupies similar range.
-
-The server listens for commands on the ` POST /cmd` endpoint. It expects basic single word text data as defined and generated for the .gmc spec.
-Based on the command, a single subprocess may be terminated or replaced.
-
-For example: a command will
-- Compare POST body command to known UtilKeywords
-- Execute Utility routine on match
-- Else pattern match for MAME game slug
-    - Check GroovyMAME executable for game slug verification
-        - Fail if not verifiable
-    - Check for existing GroovyMAME subprocess, exit if operational
-    - Attempt to create new GroovyMAME subprocess based on game slug
-    - Runs as goroutine/async
-- Else fail
-- Return HTTP response
-
-The CLI app must be executed/ran on the Server before the GroovyMiSTer core can access it.
-
-For a delegated mini-pc this could be run on startup. The server process is extremely light weight and can safely run in the background without significant resource drain.
-
-PC, OSX, and Linux builds are possible from the single go repository.
+This could then be trivially SCPed and extracted.

cmd/groovymisterhttp/main.go

@@ -0,0 +1,62 @@
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/BossRighteous/GroovyMiSTerHTTP/pkg/command"
+	"github.com/BossRighteous/GroovyMiSTerHTTP/pkg/display"
+	"github.com/BossRighteous/GroovyMiSTerHTTP/pkg/server"
+)
+
+func main() {
+	configPath := "./config.json"
+	if len(os.Args) > 1 {
+		configPath = os.Args[1]
+	}
+
+	config, err := command.LoadConfigFromPath(configPath)
+	if err != nil {
+		log.Fatal("Config could not be loaded from path argument")
+	}
+
+	misterHost := config.MisterHost
+	cmdChan := make(chan command.GroovyMiSTerCommand)
+
+	cmdr := &command.CommandRunner{
+		Config:     config,
+		ResultChan: make(chan command.RunResult),
+	}
+
+	server.StartUdpClient(misterHost, cmdChan)
+
+	disp := display.NewMiSTerDisplay(misterHost)
+
+	for {
+		select {
+		case res := <-cmdr.ResultChan:
+			fmt.Println(res)
+			if res.BlitMessage {
+				if len(res.MessageLines) > 0 {
+					disp.BlitText(res.MessageLines)
+				} else if res.Message != "" {
+					disp.BlitText(display.ReflowText(res.Message))
+				} else {
+					disp.BlitText([]string{"Process Completed"})
+				}
+			}
+		case cmd := <-cmdChan:
+			disp.SafeClose()
+			fmt.Println(cmd.Raw)
+			res := cmdr.Run(cmd)
+			if res.BlitMessage {
+				if len(res.MessageLines) > 0 {
+					disp.BlitText(res.MessageLines)
+				} else {
+					disp.BlitText(display.ReflowText(res.Message))
+				}
+			}
+		}
+	}
+}

go.mod

@@ -0,0 +1,8 @@
+module github.com/BossRighteous/GroovyMiSTerHTTP
+
+go 1.18
+
+require (
+	github.com/golang/freetype v0.0.0-20170609003504-e2365dfdc4a0 // indirect
+	golang.org/x/image v0.18.0 // indirect
+)

go.sum

@@ -0,0 +1,4 @@
+github.com/golang/freetype v0.0.0-20170609003504-e2365dfdc4a0 h1:DACJavvAHhabrF08vX0COfcOBJRhZ8lUbR+ZWIs0Y5g=
+github.com/golang/freetype v0.0.0-20170609003504-e2365dfdc4a0/go.mod h1:E/TSTwGwJL78qG/PmXZO1EjYhfJinVAhrmmHX6Z8B9k=
+golang.org/x/image v0.18.0 h1:jGzIakQa/ZXI1I0Fxvaa9W7yP25TqT6cHIHn+6CqvSQ=
+golang.org/x/image v0.18.0/go.mod h1:4yyo5vMFQjVjUcVk4jEQcU9MGy/rulF5WvUILseCM2E=

pkg/command/config.go

@@ -0,0 +1,46 @@
+package command
+
+import (
+	"encoding/json"
+	"os"
+)
+
+type GMCConfigCommand struct {
+	Cmd      string   `json:"cmd"`
+	WorkDir  string   `json:"work_dir"`
+	ExecBin  string   `json:"exec_bin"`
+	ExecArgs []string `json:"exec_args"`
+}
+
+type GMCConfig struct {
+	MisterHost string             `json:"mister_host"`
+	Commands   []GMCConfigCommand `json:"commands"`
+	CmdMap     map[string]GMCConfigCommand
+}
+
+func LoadConfigFromPath(path string) (*GMCConfig, error) {
+	var config GMCConfig
+	dat, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	err = json.Unmarshal(dat, &config)
+	if err != nil {
+		return nil, err
+	}
+
+	for i := range config.Commands {
+		cmd := config.Commands[i]
+		config.CmdMap = make(map[string]GMCConfigCommand)
+		config.CmdMap[cmd.Cmd] = cmd
+	}
+
+	// Add built in commands
+	config.CmdMap["unload"] = GMCConfigCommand{
+		Cmd:      "unload",
+		ExecBin:  "echo",
+		ExecArgs: []string{""},
+	}
+
+	return &config, nil
+}

pkg/command/gmc.go

@@ -0,0 +1,17 @@
+package command
+
+import "encoding/json"
+
+type GroovyMiSTerCommand struct {
+	Cmd  string            `json:"cmd"`
+	Vars map[string]string `json:"vars"`
+	Raw  []byte
+}
+
+func ParseGMC(cmdBytes []byte) (GroovyMiSTerCommand, error) {
+	cmd := GroovyMiSTerCommand{
+		Raw: cmdBytes,
+	}
+	err := json.Unmarshal(cmdBytes, &cmd)
+	return cmd, err
+}