Added server status related apis

Author: akclace

CHANGELOG.md

@@ -7,6 +7,10 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- Added `openrun server stop --wait`: waits for the server process to fully exit instead of returning as soon as shutdown starts (the final litestream sync runs as the process exits, so scripts that move or restore data directories after a stop need this). Over the unix domain socket the server's pid (now returned by the stop API) is polled; over http(s) the listener port is polled as a best effort signal. Also added `openrun server status` (prints `ok` when the server connection works) and `openrun server version` (reports the server's build version and commit).
+
 ### Fixed
 
 - The `openrun` CLI now discovers a machine scoped Windows service install: when `OPENRUN_HOME` is not set and no config is found relative to the executable (a winget binary is a links shim, so executable-relative discovery finds nothing), it checks `%ProgramData%\openrun\openrun.toml` and connects to the server's unix domain socket under that home, like `/var/lib/openrun` on Linux. Previously the CLI fell back to `$HOME\openrun` and failed to find the service's socket unless `OPENRUN_HOME` was set machine-wide.

cmd/openrun/server_cmds.go

@@ -9,11 +9,14 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"net"
 	"net/url"
 	"os"
 	"os/signal"
 	"strconv"
+	"strings"
 	"syscall"
+	"time"
 
 	"github.com/openrundev/openrun/internal/system"
 	"github.com/openrundev/openrun/internal/types"
@@ -40,11 +43,27 @@ func getServerCommands(serverConfig *types.ServerConfig, clientConfig *types.Cli
 				{
 					Name:  "stop",
 					Usage: "Stop the openrun server",
-					Flags: flags,
+					Flags: []cli.Flag{newBoolFlag("wait", "w", "Wait for the server process to exit instead of returning as soon as shutdown starts", false)},
 					Action: func(cCtx *cli.Context) error {
 						return stopServer(cCtx, clientConfig)
 					},
 				},
+				{
+					Name:  "status",
+					Usage: "Report ok if the server connection works",
+					Flags: flags,
+					Action: func(cCtx *cli.Context) error {
+						return serverStatus(cCtx, clientConfig)
+					},
+				},
+				{
+					Name:  "version",
+					Usage: "Report the server version",
+					Flags: flags,
+					Action: func(cCtx *cli.Context) error {
+						return serverVersion(cCtx, clientConfig)
+					},
+				},
 				{
 					Name:  "restart",
 					Usage: "Restart the openrun server in-place with zero downtime, reloading the config and picking up a new binary",
@@ -202,14 +221,90 @@ func waitForShutdownSignal(server *api.Server) {
 	}
 }
 
-func stopServer(_ *cli.Context, clientConfig *types.ClientConfig) error {
+func stopServer(cCtx *cli.Context, clientConfig *types.ClientConfig) error {
 	client := newHttpClient(clientConfig)
 
-	var response types.AppVersionListResponse
+	var response types.ServerStopResponse
 	err := client.Post("/_openrun/stop", nil, nil, &response)
 	if err != nil && !errors.Is(err, io.EOF) {
 		return err
 	}
+	if cCtx.Bool("wait") {
+		return waitForServerExit(clientConfig, response.PID)
+	}
+	return nil
+}
+
+// waitForServerExit blocks until the stopped server has fully exited: the
+// stop API responds when shutdown starts, and cleanup (final litestream
+// sync) runs as the process exits, after the listeners are already closed.
+// Over the unix domain socket the server's pid is polled; over http(s) the
+// listener port is polled instead, a best effort signal for remote servers
+func waitForServerExit(clientConfig *types.ClientConfig, pid int) error {
+	serverUri := os.ExpandEnv(clientConfig.ServerUri)
+	overTCP := strings.HasPrefix(serverUri, "http://") || strings.HasPrefix(serverUri, "https://")
+	var addr string
+	if overTCP {
+		parsed, err := url.Parse(serverUri)
+		if err != nil {
+			return fmt.Errorf("error parsing server_uri for --wait: %w", err)
+		}
+		addr = parsed.Host
+		if parsed.Port() == "" {
+			if parsed.Scheme == "https" {
+				addr += ":443"
+			} else {
+				addr += ":80"
+			}
+		}
+	}
+
+	running := func() bool {
+		if !overTCP && pid > 0 {
+			return system.ProcessExists(pid)
+		}
+		network, target := "tcp", addr
+		if !overTCP {
+			network, target = "unix", serverUri
+		}
+		conn, err := net.DialTimeout(network, target, time.Second)
+		if err != nil {
+			return false
+		}
+		conn.Close() //nolint:errcheck
+		return true
+	}
+
+	for deadline := time.Now().Add(120 * time.Second); time.Now().Before(deadline); {
+		if !running() {
+			return nil
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	return fmt.Errorf("timed out waiting for the server to exit")
+}
+
+func serverStatus(_ *cli.Context, clientConfig *types.ClientConfig) error {
+	client := newHttpClient(clientConfig)
+
+	var response types.ServerStatusResponse
+	err := client.Get("/_openrun/server_status", nil, &response)
+	if err != nil {
+		return err
+	}
+	fmt.Println(response.Status)
+	return nil
+}
+
+func serverVersion(_ *cli.Context, clientConfig *types.ClientConfig) error {
+	client := newHttpClient(clientConfig)
+
+	var response types.ServerVersionResponse
+	err := client.Get("/_openrun/server_version", nil, &response)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("%s (commit %s)\n", response.Version, response.Commit)
 	return nil
 }
 

internal/server/router.go

@@ -756,7 +756,21 @@ func (h *Handler) stopServer(r *http.Request) (any, error) {
 	updateOperationInContext(r, "stop_server")
 	h.server.RequestStop()
 
-	return map[string]any{}, nil
+	return types.ServerStopResponse{PID: os.Getpid()}, nil
+}
+
+// serverStatus reports "ok": reaching this handler means the connection and
+// authentication both worked
+func (h *Handler) serverStatus(_ *http.Request) (any, error) {
+	return types.ServerStatusResponse{Status: "ok"}, nil
+}
+
+// serverVersion reports the server's build version and commit
+func (h *Handler) serverVersion(r *http.Request) (any, error) {
+	if err := h.server.enforceGlobalPerm(r.Context(), types.PermissionConfigBasicRead, ""); err != nil {
+		return nil, err
+	}
+	return types.ServerVersionResponse{Version: types.GetVersion(), Commit: types.GetCommit()}, nil
 }
 
 // restartServer performs a zero downtime in-place restart: a new server
@@ -1815,6 +1829,16 @@ func (h *Handler) serveInternal(enableBasicAuth bool) http.Handler {
 		h.apiHandler(w, r, enableBasicAuth, "restart_server", h.restartServer, false)
 	}))
 
+	// Server status: lightweight connectivity check
+	r.Get("/server_status", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		h.apiHandler(w, r, enableBasicAuth, "server_status", h.serverStatus, false)
+	}))
+
+	// Server version
+	r.Get("/server_version", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		h.apiHandler(w, r, enableBasicAuth, "server_version", h.serverVersion, false)
+	}))
+
 	// Get apps
 	r.Get("/apps", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		h.apiHandler(w, r, enableBasicAuth, "list_apps", h.getApps, false)

internal/system/process_unix.go

@@ -6,6 +6,7 @@
 package system
 
 import (
+	"errors"
 	"os"
 	"os/exec"
 	"syscall"
@@ -20,3 +21,14 @@ func SetProcessGroup(cmd *exec.Cmd) {
 func KillGroup(process *os.Process) error {
 	return syscall.Kill(-process.Pid, syscall.SIGKILL)
 }
+
+// ProcessExists reports whether a process with the given pid is running.
+// EPERM means the process exists but is owned by another user
+func ProcessExists(pid int) bool {
+	process, err := os.FindProcess(pid)
+	if err != nil {
+		return false
+	}
+	err = process.Signal(syscall.Signal(0))
+	return err == nil || errors.Is(err, syscall.EPERM)
+}

internal/system/process_windows.go

@@ -28,3 +28,14 @@ func KillGroup(process *os.Process) error {
 	}
 	return nil
 }
+
+// ProcessExists reports whether a process with the given pid is running. On
+// Windows FindProcess opens a process handle, which fails if the pid is gone
+func ProcessExists(pid int) bool {
+	process, err := os.FindProcess(pid)
+	if err != nil {
+		return false
+	}
+	process.Release() //nolint:errcheck
+	return true
+}

internal/types/api.go

@@ -310,6 +310,25 @@ type ConfigResponse struct {
 	DynamicConfig DynamicConfig `json:"dynamic_config"`
 }
 
+// ServerStopResponse is the response of the server stop API. The PID lets a
+// local client wait for the process to fully exit: the API responds when
+// shutdown starts, and cleanup (final litestream sync) runs as the process
+// exits, after the listeners are already closed
+type ServerStopResponse struct {
+	PID int `json:"pid"`
+}
+
+// ServerStatusResponse is the response of the server status API
+type ServerStatusResponse struct {
+	Status string `json:"status"`
+}
+
+// ServerVersionResponse is the response of the server version API
+type ServerVersionResponse struct {
+	Version string `json:"version"`
+	Commit  string `json:"commit"`
+}
+
 // CreateSecretRequest is the request body for storing a secret in a writable
 // secret provider. Either Name (explicit name) or Prefix (a unique name is
 // generated with the prefix) must be set. Encoding "base64" is used to pass

tests/run_cli_tests.sh

@@ -788,7 +788,9 @@ EOF
 
   commander test $VERBOSE test_basics.yaml
   MATCHED_TESTS+=(test_basics.yaml)
-  CL_CONFIG_FILE=config_basic_test.toml GOCOVERDIR=$GOCOVERDIR/../client ../openrun server stop
+  # --wait exercises the wait-for-exit path (stop returns when shutdown
+  # starts; --wait polls the server pid until the process is gone)
+  CL_CONFIG_FILE=config_basic_test.toml GOCOVERDIR=$GOCOVERDIR/../client ../openrun server stop --wait
   SERVER_PID=""
   rm -rf metadata run/openrun.sock config_basic_*.toml
 fi

tests/test_basics.yaml

@@ -37,6 +37,25 @@ tests:
       line-count: 0
     exit-code: 1
 
+  basic052: # server status reports ok over UDS
+    command: ../openrun server status
+    stdout:
+      exactly: "ok"
+    exit-code: 0
+
+  basic053: # server status fails over http, admin api's are disabled there
+    command: CL_CONFIG_FILE=config_basic_client_np.toml ../openrun server status
+    stderr: "error: 404 page not found"
+    stdout:
+      line-count: 0
+    exit-code: 1
+
+  basic054: # server version reports the server build version
+    command: ../openrun server version
+    stdout:
+      exactly: "dev (commit dev_build)" # test binary is built without version ldflags
+    exit-code: 0
+
   basic060: ## create test1 app with default of authentication enabled
     command: ../openrun app create ./testapp /test1
     exit-code: 0