fix: reconnect Z21 UDP and fail /healthz when the station is down

Makefile

@@ -125,3 +125,53 @@ fmt: ## Run go fmt against code.
 .PHONY: vet
 vet: ## Run go vet against code.
 	go vet ./...
+
+# --- Hub deploy (RO rootfs: binaries live on /data) -----------------------
+# Hub runs Dropbear. Older images lack /usr/libexec/sftp-server; -O uses
+# legacy scp. Harmless on images that ship openssh sftp-server.
+#
+#   make deploy-hub
+#   make deploy-hub HUB=192.168.0.10
+#
+# Installs linux/arm64 prod binaries into /data/opt/bigfred/bin (preferred
+# over the image copies in /opt) and restarts microinit services.
+HUB ?= 192.168.0.1
+HUB_USER ?= root
+HUB_SSH ?= $(HUB_USER)@$(HUB)
+SCP ?= scp
+SCP_OPTS ?= -O
+SSH ?= ssh
+HUB_BIN_DIR ?= /data/opt/bigfred/bin
+
+.PHONY: hub-arm64 deploy-hub
+hub-arm64: web-build
+	CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -tags prod -ldflags="-s -w $(VERSION_LDFLAGS)" \
+		-o bin/loco-server-linux-arm64 ./pkgs/bigfred/server
+	CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="$(VERSION_LDFLAGS)" \
+		-o bin/bigfred-remote-icmp-linux-arm64 ./pkgs/bigfred/remote-icmp
+	@ls -lh bin/loco-server-linux-arm64 bin/bigfred-remote-icmp-linux-arm64
+
+# Upload next to the target and rename: writing in place fails with ETXTBSY
+# once the hub is running the /data copy, and rename(2) swaps the inode
+# atomically. dcc-bus runs `bigfred dcc-bus …` from the same binary, so those
+# daemons keep the old inode until they are restarted too.
+deploy-hub: hub-arm64
+	@test -f bin/loco-server-linux-arm64 || { echo "error: bin/loco-server-linux-arm64 missing" >&2; exit 1; }
+	@test -f bin/bigfred-remote-icmp-linux-arm64 || { echo "error: bin/bigfred-remote-icmp-linux-arm64 missing" >&2; exit 1; }
+	$(SSH) $(HUB_SSH) 'mkdir -p $(HUB_BIN_DIR)'
+	$(SCP) $(SCP_OPTS) bin/loco-server-linux-arm64 $(HUB_SSH):$(HUB_BIN_DIR)/.bigfred.new
+	$(SCP) $(SCP_OPTS) bin/bigfred-remote-icmp-linux-arm64 $(HUB_SSH):$(HUB_BIN_DIR)/.bigfred-remote-icmp.new
+	$(SSH) $(HUB_SSH) 'set -e; \
+		cd $(HUB_BIN_DIR); \
+		chmod 755 .bigfred.new .bigfred-remote-icmp.new; \
+		mv -f .bigfred.new bigfred; \
+		mv -f .bigfred-remote-icmp.new bigfred-remote-icmp; \
+		command -v setcap >/dev/null && setcap cap_net_raw+ep bigfred-remote-icmp || true; \
+		rc=0; \
+		microinit restart bigfred || rc=1; \
+		microinit restart remote-icmp || rc=1; \
+		for p in $$(microinit list 2>/dev/null | grep -o "^dcc-bus-[^ ]*" || true); do \
+			echo "restarting $$p"; \
+			microinit restart "$$p" || rc=1; \
+		done; \
+		exit $$rc'

pkgs/bigfred/dcc-bus/daemon.go

@@ -366,7 +366,7 @@ func New(ctx context.Context, log *logrus.Logger, cfg Config) (*Daemon, error) {
 		log.Info("dcc-bus ws metrics enabled")
 	}
 
-	wsSrv := ws.NewServer(ws.ServerConfig{
+	wsCfg := ws.ServerConfig{
 		Verifier:           verifier,
 		Hub:                hub,
 		Router:             ws.NewRouterAdapter(router),
@@ -386,7 +386,11 @@ func New(ctx context.Context, log *logrus.Logger, cfg Config) (*Daemon, error) {
 			AllowedOrigins: cfg.AllowedOrigins,
 			Verifier:       verifier,
 		}),
-	})
+	}
+	if h, ok := st.(ws.StationHealth); ok {
+		wsCfg.StationHealth = h
+	}
+	wsSrv := ws.NewServer(wsCfg)
 
 	srv := &http.Server{
 		Addr:              net.JoinHostPort(cfg.BindAddr, strconv.Itoa(int(cfg.Port))),

pkgs/bigfred/dcc-bus/ws/handler.go

@@ -82,6 +82,16 @@ type Server struct {
 	// the daemon binds to loopback because the reverse proxy on
 	// loco-server already validates Origin).
 	AllowedOrigins []string
+
+	// stationHealth is optional; Z21 reports UDP reachability so
+	// /healthz can fail closed while the station is reconnecting.
+	stationHealth StationHealth
+}
+
+// StationHealth is implemented by command-station drivers that can
+// report whether the physical bus is reachable (Z21 serial heartbeat).
+type StationHealth interface {
+	Reachable() bool
 }
 
 // ServerConfig collects the few knobs Server takes at construction.
@@ -101,6 +111,8 @@ type ServerConfig struct {
 	// ProgrammingEnabled opens the loco.cvRead / cvWrite / addrGet /
 	// addrSet frames. Off by default.
 	ProgrammingEnabled bool
+	// StationHealth, when set, is consulted by /healthz.
+	StationHealth StationHealth
 }
 
 // NewServer returns a ready-to-mount Server. Heartbeat and dead-man
@@ -124,19 +136,20 @@ func NewServer(cfg ServerConfig) *Server {
 		log = logrus.New()
 	}
 	return &Server{
-		verifier:       cfg.Verifier,
-		hub:            cfg.Hub,
-		router:         cfg.Router,
-		log:            log,
-		layoutID:       cfg.LayoutID,
-		csID:           cfg.CommandStation,
-		speedSteps:     steps,
-		heartbeatSecs:  hb,
-		deadmanSecs:    dms,
-		AllowedOrigins: cfg.AllowedOrigins,
-		metrics:        cfg.Metrics,
-		slotsDiag:      cfg.SlotsDiag,
+		verifier:           cfg.Verifier,
+		hub:                cfg.Hub,
+		router:             cfg.Router,
+		log:                log,
+		layoutID:           cfg.LayoutID,
+		csID:               cfg.CommandStation,
+		speedSteps:         steps,
+		heartbeatSecs:      hb,
+		deadmanSecs:        dms,
+		AllowedOrigins:     cfg.AllowedOrigins,
+		metrics:            cfg.Metrics,
+		slotsDiag:          cfg.SlotsDiag,
 		programmingEnabled: cfg.ProgrammingEnabled,
+		stationHealth:      cfg.StationHealth,
 	}
 }
 
@@ -160,13 +173,23 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 			http.NotFound(w, r)
 		}
 	case "/healthz":
-		w.WriteHeader(http.StatusOK)
-		_, _ = w.Write([]byte(`{"status":"ok"}`))
+		s.handleHealthz(w)
 	default:
 		http.NotFound(w, r)
 	}
 }
 
+func (s *Server) handleHealthz(w http.ResponseWriter) {
+	w.Header().Set("Content-Type", "application/json")
+	if s.stationHealth != nil && !s.stationHealth.Reachable() {
+		w.WriteHeader(http.StatusServiceUnavailable)
+		_, _ = w.Write([]byte(`{"status":"unhealthy","code":"station_unreachable"}`))
+		return
+	}
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte(`{"status":"ok"}`))
+}
+
 // handleWS authenticates, upgrades, registers the session and runs
 // the read loop until ctx ends or the client disconnects.
 func (s *Server) handleWS(w http.ResponseWriter, r *http.Request) {
@@ -250,8 +273,8 @@ func (s *Server) readLoop(ctx context.Context, sess *Session) {
 			sess.Close(errors.WsCodeSessionReadLoopDone)
 		}
 		s.log.WithFields(logrus.Fields{
-			"sessionId":              sess.ID,
-			"userId":                 sess.UserID,
+			"sessionId":             sess.ID,
+			"userId":                sess.UserID,
 			"userSessionsRemaining": len(s.hub.SessionsForUser(sess.UserID)),
 		}).Info("dcc-bus session closed")
 		// Give the browser time to reconnect before firing the dead-man's

pkgs/bigfred/dcc-bus/ws/handler_healthz_test.go

@@ -0,0 +1,49 @@
+package ws
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+type fakeStationHealth struct{ ok bool }
+
+func (f fakeStationHealth) Reachable() bool { return f.ok }
+
+func TestHealthzOKWhenNoStationHealth(t *testing.T) {
+	s := NewServer(ServerConfig{})
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rec.Code)
+	}
+}
+
+func TestHealthzOKWhenStationReachable(t *testing.T) {
+	s := NewServer(ServerConfig{StationHealth: fakeStationHealth{ok: true}})
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rec.Code)
+	}
+}
+
+func TestHealthzUnavailableWhenStationUnreachable(t *testing.T) {
+	s := NewServer(ServerConfig{StationHealth: fakeStationHealth{ok: false}})
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status = %d, want 503", rec.Code)
+	}
+	var body struct {
+		Status string `json:"status"`
+		Code   string `json:"code"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("json: %v", err)
+	}
+	if body.Status != "unhealthy" || body.Code != "station_unreachable" {
+		t.Fatalf("body = %+v", body)
+	}
+}