feat: adding a "read-only" connection if an instance is already running

Author: centerorbit

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "patchboard"]
+	path = patchboard
+	url = git@github.com:OffPeakEngineer/patchboard.git

README.md

@@ -37,6 +37,8 @@ http://localhost:8080
 
 Run the same binary on additional LAN machines and they should discover each other automatically. If the advertised browser URL needs to differ from the listen address, set `PSSTD_ADVERTISE_HTTP`.
 
+If you start `psstd` again while an instance is already running on the machine, the second process does not open another writer on the same store or publish a duplicate node. When the existing `PSSTD_DB` is locked, or the configured gossip port is already bound, it joins as a terminal-only mirror with a temporary database and renders the cluster view in your terminal.
+
 ## Configuration
 
 ```bash
@@ -145,12 +147,6 @@ Traefik supports query-param matchers in router rules, so this keeps link clicks
 
 That example also includes a low-priority host-only fallback route. If Traefik sees no matching `psstd_node` value, it sends the request to a shared `psstd-any` service instead of pinning fallback traffic to one node. Keep the `psstd-any` Endpoints list limited to nodes that should receive unrouted fallback traffic.
 
-## Health Check
-
-```bash
-curl http://localhost:8080/healthz
-```
-
 ## Notes
 
 psstd uses peer-to-peer state sharing and a small local store internally, but those are implementation details for the dashboard. It is not intended to be a general-purpose distributed database or key-value API.

main.go

@@ -7,6 +7,7 @@ import (
 	"net"
 	"net/http"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -44,9 +45,18 @@ func main() {
 	// ── Local state ─────────────────────────────────────────────────────────
 	db, err := pebble.Open(dbPath, &pebble.Options{})
 	if err != nil {
+		if pebbleLockHeld(err) {
+			log.Printf("psstd already appears to own %s; starting terminal mirror instead", dbPath)
+			runTerminalMirror(hostname, gossipAddr, seeds)
+			return
+		}
 		log.Fatalf("pebble open: %v", err)
 	}
-	defer db.Close()
+	defer func() {
+		if db != nil {
+			db.Close()
+		}
+	}()
 	if err := purgeOfflineDifferentVersion(db, appVersion); err != nil {
 		log.Printf("stale version purge: %v", err)
 	}
@@ -63,6 +73,15 @@ func main() {
 
 	list, err := memberlist.Create(cfg)
 	if err != nil {
+		if addressInUse(err) {
+			if closeErr := db.Close(); closeErr != nil {
+				log.Printf("db close before terminal mirror: %v", closeErr)
+			}
+			db = nil
+			log.Printf("psstd already appears to be listening on %s; starting terminal mirror instead", gossipAddr)
+			runTerminalMirror(hostname, gossipAddr, seeds)
+			return
+		}
 		log.Fatalf("memberlist create: %v", err)
 	}
 	delegate.broadcasts.NumNodes = func() int { return list.NumMembers() }
@@ -92,10 +111,6 @@ func main() {
 	if webEnabled {
 		mux := http.NewServeMux()
 		mux.HandleFunc("/", makeHandler(db, hostname))
-		mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
-			w.WriteHeader(200)
-			fmt.Fprintln(w, "ok")
-		})
 		log.Printf("psstd version=%s node=%s http=%s advertise=%s gossip=%s web=true", appVersion, hostname, httpAddr, webURL, gossipAddr)
 		if err := http.ListenAndServe(httpAddr, mux); err != nil {
 			log.Fatalf("http: %v", err)
@@ -106,6 +121,71 @@ func main() {
 	}
 }
 
+func pebbleLockHeld(err error) bool {
+	msg := strings.ToLower(err.Error())
+	return strings.Contains(msg, "lock") &&
+		(strings.Contains(msg, "resource temporarily unavailable") ||
+			strings.Contains(msg, "held") ||
+			strings.Contains(msg, "being used") ||
+			strings.Contains(msg, "already in use") ||
+			strings.Contains(msg, "access is denied"))
+}
+
+func addressInUse(err error) bool {
+	msg := strings.ToLower(err.Error())
+	return strings.Contains(msg, "address already in use") ||
+		strings.Contains(msg, "bind: only one usage of each socket address")
+}
+
+func runTerminalMirror(hostname, gossipAddr string, seeds []string) {
+	tmpDir, err := os.MkdirTemp("", "psstd-view-*")
+	if err != nil {
+		log.Fatalf("terminal mirror temp db: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	db, err := pebble.Open(filepath.Join(tmpDir, "data"), &pebble.Options{})
+	if err != nil {
+		log.Fatalf("terminal mirror db: %v", err)
+	}
+	defer db.Close()
+
+	delegate := newKVDelegate(db, appVersion)
+	cfg := memberlist.DefaultLANConfig()
+	cfg.Name = fmt.Sprintf("%s-view-%d", hostname, os.Getpid())
+	cfg.BindAddr = "0.0.0.0"
+	cfg.BindPort = 0
+	cfg.Delegate = delegate
+	cfg.Logger = log.New(os.Stderr, "[memberlist:view] ", log.LstdFlags)
+
+	list, err := memberlist.Create(cfg)
+	if err != nil {
+		log.Fatalf("terminal mirror memberlist: %v", err)
+	}
+	defer list.Shutdown()
+	delegate.broadcasts.NumNodes = func() int { return list.NumMembers() }
+
+	allSeeds := terminalMirrorSeeds(gossipAddr, seeds)
+	if n, err := list.Join(allSeeds); err != nil {
+		log.Printf("terminal mirror join warning (joined %d): %v", n, err)
+	} else {
+		log.Printf("terminal mirror joined cluster, %d peer(s)", n)
+	}
+
+	terminalRenderLoop(db)
+}
+
+func terminalMirrorSeeds(gossipAddr string, seeds []string) []string {
+	out := append([]string{}, seeds...)
+	host, port := splitHostPort(gossipAddr)
+	if host != "" && host != "0.0.0.0" && host != "::" {
+		out = append(out, net.JoinHostPort(host, fmt.Sprintf("%d", port)))
+	}
+	out = append(out, net.JoinHostPort("127.0.0.1", fmt.Sprintf("%d", port)))
+	out = append(out, net.JoinHostPort("localhost", fmt.Sprintf("%d", port)))
+	return append(out, discoverPeers()...)
+}
+
 // ── Stats loop ───────────────────────────────────────────────────────────────
 
 func statsLoop(hostname, webURL, version string, db *pebble.DB, d *kvDelegate) {

patchboard

@@ -0,0 +1,53 @@
+# Tasks
+
+This folder is a Patchboard task board. Tasks are Markdown files, and the
+folder containing a task is its workflow state.
+
+## States
+
+- `backlog/`
+- `ready/`
+- `doing/`
+- `blocked/`
+- `done/`
+- `archived/`
+
+Move a task file between folders to change its state. Git history is the audit
+trail.
+
+## Task Shape
+
+~~~markdown
+---
+id: task-YYYYMMDD-short-name
+title: Short, concrete task title
+status: backlog
+priority: medium
+owner: your-name
+created: YYYY-MM-DD
+---
+
+## Problem
+
+What needs to change, and why?
+
+## Done when
+
+- The expected behavior is implemented
+- Relevant tests or checks pass
+~~~
+
+The folder is authoritative for status. If frontmatter includes `status`,
+it should match the parent folder.
+
+## Code Annotations
+
+Link code comments back to tasks with square brackets:
+
+~~~text
+TODO[task-YYYYMMDD-short-name]: describe the follow-up
+FIXME[task-YYYYMMDD-short-name]: describe the known problem
+~~~
+
+Unlinked annotations such as `TODO:`, `XXX:`, and `WARN:` are useful inventory,
+but they do not fail lint until they reference a task ID.