Add Windows named-pipe support to API listener

setupUnixSocket assumed the address was a filesystem path -- it
ran os.Stat, os.Remove, os.MkdirAll, and os.Chmod around
net.Listen("unix", ...). None of that applies to a Windows named
pipe (\.\pipe\thv-api), and net.Listen("unix", ...) is not a
substitute since named pipes are a different kernel object. As a
result, toolhive-studio could not run thv with a pipe address on
Windows.

Split setupUnixSocket and cleanupUnixSocket into per-platform
files via build tags, mirroring pkg/container/docker/sdk. On
Windows, branch on the \.\pipe\ prefix and use winio.ListenPipe
with InputBufferSize and OutputBufferSize at 64 KiB; MessageMode
stays at byte-stream because HTTP requires byte framing. Skip
stat/remove/mkdir/chmod for pipes since they are not files;
keep stat/remove/mkdir for the AF_UNIX fallback (Win10 1803+)
but drop chmod because POSIX modes do not apply on Windows.

ListenURL emits npipe://<name> for pipe addresses so the
discovery file URL stays unambiguous. createListener labels the
listener as "Windows named pipe" and rejects pipe addresses on
non-Windows up front, rather than creating a literal-backslash
file via AF_UNIX.

Author: samuv

pkg/api/server.go

@@ -27,6 +27,7 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	stdruntime "runtime"
 	"strings"
 	"time"
 
@@ -366,41 +367,20 @@ func (b *ServerBuilder) setupDefaultRoutes(r *chi.Mux) {
 	}
 }
 
-func setupTCPListener(address string) (net.Listener, error) {
-	return net.Listen("tcp", address)
-}
-
-func setupUnixSocket(address string) (net.Listener, error) {
-	// Remove the socket file if it already exists
-	if _, err := os.Stat(address); err == nil {
-		if err := os.Remove(address); err != nil {
-			return nil, fmt.Errorf("failed to remove existing socket: %w", err)
-		}
-	}
-
-	// Create the directory for the socket file if it doesn't exist
-	if err := os.MkdirAll(filepath.Dir(address), 0750); err != nil {
-		return nil, fmt.Errorf("failed to create socket directory: %w", err)
-	}
-
-	// Create UNIX socket listener
-	listener, err := net.Listen("unix", address)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create UNIX socket listener: %w", err)
-	}
+// namedPipePrefix is the Windows named-pipe namespace prefix. Both per-platform
+// socket files use it, and ListenURL/createListener inspect the address prefix
+// to choose between AF_UNIX and named-pipe semantics.
+const namedPipePrefix = `\\.\pipe\`
 
-	// Set file permissions on the socket to allow other local processes to connect
-	if err := os.Chmod(address, socketPermissions); err != nil {
-		return nil, fmt.Errorf("failed to set socket permissions: %w", err)
-	}
-
-	return listener, nil
+// isNamedPipeAddress reports whether address is a Windows named-pipe path.
+// The check is platform-agnostic so callers on non-Windows can fail fast with
+// a clear error before reaching the listener code.
+func isNamedPipeAddress(address string) bool {
+	return strings.HasPrefix(address, namedPipePrefix)
 }
 
-func cleanupUnixSocket(address string) {
-	if err := os.Remove(address); err != nil && !os.IsNotExist(err) {
-		slog.Warn("failed to remove socket file", "error", err)
-	}
+func setupTCPListener(address string) (net.Listener, error) {
+	return net.Listen("tcp", address)
 }
 
 func headersMiddleware(next http.Handler) http.Handler {
@@ -592,7 +572,7 @@ func NewServer(ctx context.Context, builder *ServerBuilder) (*Server, error) {
 // bound address from the listener (important when binding to port 0).
 func (s *Server) ListenURL() string {
 	if s.isUnixSocket {
-		return fmt.Sprintf("unix://%s", s.address)
+		return socketURL(s.address)
 	}
 	return fmt.Sprintf("http://%s", s.listener.Addr().String())
 }
@@ -715,24 +695,30 @@ func (s *Server) cleanup() {
 	}
 }
 
-// createListener creates the appropriate listener based on the configuration
+// createListener creates the appropriate listener based on the configuration.
+// Named-pipe addresses are only supported on Windows; other platforms reject
+// them up front rather than creating a literal-backslash file via AF_UNIX.
 func createListener(address string, isUnixSocket bool) (net.Listener, string, error) {
-	var listener net.Listener
-	var addrType string
-	var err error
+	if !isUnixSocket {
+		listener, err := setupTCPListener(address)
+		if err != nil {
+			return nil, "", err
+		}
+		return listener, "HTTP", nil
+	}
 
-	if isUnixSocket {
-		listener, err = setupUnixSocket(address)
-		addrType = "UNIX socket"
-	} else {
-		listener, err = setupTCPListener(address)
-		addrType = "HTTP"
+	addrType := "UNIX socket"
+	if isNamedPipeAddress(address) {
+		if stdruntime.GOOS != "windows" {
+			return nil, "", fmt.Errorf("named pipe addresses are only supported on Windows: %s", address)
+		}
+		addrType = "Windows named pipe"
 	}
 
+	listener, err := setupUnixSocket(address)
 	if err != nil {
 		return nil, "", err
 	}
-
 	return listener, addrType, nil
 }
 

pkg/api/socket_other.go

@@ -0,0 +1,54 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build !windows
+
+package api
+
+import (
+	"fmt"
+	"log/slog"
+	"net"
+	"os"
+	"path/filepath"
+)
+
+// setupUnixSocket creates a UNIX domain socket listener at the given path.
+// On non-Windows platforms named-pipe addresses are not supported; callers
+// guard against that in createListener.
+func setupUnixSocket(address string) (net.Listener, error) {
+	if _, err := os.Stat(address); err == nil {
+		if err := os.Remove(address); err != nil {
+			return nil, fmt.Errorf("failed to remove existing socket: %w", err)
+		}
+	}
+
+	if err := os.MkdirAll(filepath.Dir(address), 0750); err != nil {
+		return nil, fmt.Errorf("failed to create socket directory: %w", err)
+	}
+
+	listener, err := net.Listen("unix", address)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create UNIX socket listener: %w", err)
+	}
+
+	if err := os.Chmod(address, socketPermissions); err != nil {
+		return nil, fmt.Errorf("failed to set socket permissions: %w", err)
+	}
+
+	return listener, nil
+}
+
+// cleanupUnixSocket removes the socket file at address. Missing files are not
+// an error since cleanup may run after a partial startup.
+func cleanupUnixSocket(address string) {
+	if err := os.Remove(address); err != nil && !os.IsNotExist(err) {
+		slog.Warn("failed to remove socket file", "error", err)
+	}
+}
+
+// socketURL returns the URL form of a Unix-socket address for the discovery
+// file. Non-Windows platforms only ever produce unix:// URLs.
+func socketURL(address string) string {
+	return "unix://" + address
+}

pkg/api/socket_windows.go

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build windows
+
+package api
+
+import (
+	"fmt"
+	"log/slog"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/Microsoft/go-winio"
+)
+
+// namedPipeBufferSize is the size of the input/output buffers winio allocates
+// per pipe instance. 64 KiB matches what go-winio uses in similar consumers
+// (Docker, containerd, Podman) and is well above any single HTTP header chunk.
+const namedPipeBufferSize = 64 * 1024
+
+// setupUnixSocket creates either a Windows named-pipe listener (when address
+// has the \\.\pipe\ prefix) or an AF_UNIX listener at a filesystem path.
+//
+// Named pipes are kernel objects rather than files, so the os.Stat / os.Remove
+// precheck, os.MkdirAll, and os.Chmod steps are skipped: the pipe namespace
+// has no parent directory, and access control is governed by the security
+// descriptor on the listener (winio's default restricts access to the
+// creating user, which matches the toolhive-studio same-user use case).
+//
+// AF_UNIX is supported on Windows 10 1803+. The chmod step is dropped on this
+// path because POSIX file modes do not apply on Windows.
+func setupUnixSocket(address string) (net.Listener, error) {
+	if strings.HasPrefix(address, namedPipePrefix) {
+		// MessageMode is left at false (byte stream) explicitly because HTTP
+		// requires byte-oriented framing.
+		listener, err := winio.ListenPipe(address, &winio.PipeConfig{
+			MessageMode:      false,
+			InputBufferSize:  namedPipeBufferSize,
+			OutputBufferSize: namedPipeBufferSize,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to create named pipe listener: %w", err)
+		}
+		return listener, nil
+	}
+
+	if _, err := os.Stat(address); err == nil {
+		if err := os.Remove(address); err != nil {
+			return nil, fmt.Errorf("failed to remove existing socket: %w", err)
+		}
+	}
+
+	if err := os.MkdirAll(filepath.Dir(address), 0750); err != nil {
+		return nil, fmt.Errorf("failed to create socket directory: %w", err)
+	}
+
+	listener, err := net.Listen("unix", address)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create UNIX socket listener: %w", err)
+	}
+
+	return listener, nil
+}
+
+// cleanupUnixSocket removes the AF_UNIX socket file at address, or no-ops for
+// named pipes (the pipe is destroyed when the listener closes).
+func cleanupUnixSocket(address string) {
+	if strings.HasPrefix(address, namedPipePrefix) {
+		return
+	}
+	if err := os.Remove(address); err != nil && !os.IsNotExist(err) {
+		slog.Warn("failed to remove socket file", "error", err)
+	}
+}
+
+// socketURL returns the URL form of a Unix-socket or named-pipe address for
+// the discovery file. Named pipes are emitted as npipe://<name> where <name>
+// is everything after the \\.\pipe\ prefix.
+func socketURL(address string) string {
+	if strings.HasPrefix(address, namedPipePrefix) {
+		return "npipe://" + strings.TrimPrefix(address, namedPipePrefix)
+	}
+	return "unix://" + address
+}