@yuuki824/kanshi 0.3.0

package/internal/access/listeners.go

@@ -0,0 +1,229 @@
+package access
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"net/netip"
+	"sort"
+	"strconv"
+	"sync"
+	"time"
+)
+
+// How often a mode that depends on interfaces is re-checked. Tailscale coming
+// up after Kanshi, a laptop joining Wi-Fi, a DHCP lease changing: all of them
+// are picked up within this long, without a restart.
+const rescanEvery = 30 * time.Second
+
+// Manager keeps one listener per address the current mode wants, all feeding
+// the same http.Server.
+type Manager struct {
+	port   int
+	server *http.Server
+	logf   func(format string, args ...any)
+	// Interfaces is swapped out by tests.
+	Interfaces func() []Interface
+
+	mu       sync.Mutex
+	mode     Mode
+	active   map[netip.Addr]*listener
+	failures map[netip.Addr]string // last bind error per address, so it is logged once
+}
+
+type listener struct {
+	ep Endpoint
+	ln net.Listener
+}
+
+func NewManager(port int, server *http.Server, logf func(string, ...any)) *Manager {
+	return &Manager{
+		port:       port,
+		server:     server,
+		logf:       logf,
+		Interfaces: SystemInterfaces,
+		active:     make(map[netip.Addr]*listener),
+		failures:   make(map[netip.Addr]string),
+	}
+}
+
+// ErrLoopback means the one listener that must always work could not be
+// opened — almost always because something else already has the port.
+var ErrLoopback = errors.New("cannot listen on localhost")
+
+// Apply switches to a new mode, opening and closing listeners as needed. It
+// only fails when 127.0.0.1 cannot be bound; any other address that will not
+// bind is logged and retried on the next interface check.
+func (m *Manager) Apply(mode Mode) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.mode = mode
+	return m.reconcile()
+}
+
+func (m *Manager) Mode() Mode {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.mode
+}
+
+func (m *Manager) reconcile() error {
+	var ifaces []Interface
+	if m.mode.dynamic() {
+		ifaces = m.Interfaces()
+	}
+	want := m.mode.Endpoints(ifaces)
+	wanted := make(map[netip.Addr]Endpoint, len(want))
+	for _, ep := range want {
+		wanted[ep.Addr] = ep
+	}
+
+	// Close first: switching to "all" has to release 127.0.0.1 before
+	// 0.0.0.0 can take the same port, and the reverse going back.
+	for addr, l := range m.active {
+		if _, ok := wanted[addr]; !ok {
+			l.ln.Close()
+			delete(m.active, addr)
+			if l.ep.Kind != KindLocal {
+				m.logf("stopped listening on %s", URL(addr, m.port))
+			}
+		}
+	}
+	for addr := range m.failures {
+		if _, ok := wanted[addr]; !ok {
+			delete(m.failures, addr)
+		}
+	}
+
+	var loopErr error
+	for _, ep := range want {
+		if _, ok := m.active[ep.Addr]; ok {
+			continue
+		}
+		ln, err := listen(ep.Addr, m.port)
+		if err != nil {
+			if ep.Addr == loop4 || (ep.Kind == KindAll && ep.Addr.Is4()) {
+				loopErr = fmt.Errorf("%w on port %d: %v", ErrLoopback, m.port, err)
+				continue
+			}
+			// IPv6 loopback and "::" are simply absent on hosts with IPv6
+			// turned off. That is not worth a warning, or a retry.
+			if ep.Addr == loop6 || ep.Addr == netip.IPv6Unspecified() {
+				continue
+			}
+			if m.failures[ep.Addr] != err.Error() {
+				m.logf("warning: cannot listen on %s yet (%v); will keep trying", URL(ep.Addr, m.port), err)
+			}
+			m.failures[ep.Addr] = err.Error()
+			continue
+		}
+		if _, failed := m.failures[ep.Addr]; failed {
+			m.logf("now listening on %s", URL(ep.Addr, m.port))
+			delete(m.failures, ep.Addr)
+		}
+		m.active[ep.Addr] = &listener{ep: ep, ln: ln}
+		go func() {
+			// Serve returns once the listener is closed, either here or by
+			// Shutdown. Neither is an error worth reporting.
+			_ = m.server.Serve(ln)
+		}()
+	}
+	return loopErr
+}
+
+func listen(addr netip.Addr, port int) (net.Listener, error) {
+	network := "tcp4"
+	if addr.Is6() {
+		// tcp6 sets IPV6_V6ONLY, so "::" does not also try to take 0.0.0.0.
+		network = "tcp6"
+	}
+	return net.Listen(network, net.JoinHostPort(addr.String(), strconv.Itoa(port)))
+}
+
+// Watch re-applies the current mode as interfaces come and go, and retries
+// addresses that failed to bind. It returns when ctx is cancelled.
+func (m *Manager) Watch(ctx context.Context) {
+	t := time.NewTicker(rescanEvery)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		}
+		m.mu.Lock()
+		if m.mode.dynamic() || len(m.failures) > 0 {
+			_ = m.reconcile()
+		}
+		m.mu.Unlock()
+	}
+}
+
+// Close stops every listener.
+func (m *Manager) Close() {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	for addr, l := range m.active {
+		l.ln.Close()
+		delete(m.active, addr)
+	}
+}
+
+// Link is one address the dashboard can be opened at.
+type Link struct {
+	Kind Kind   `json:"kind"`
+	URL  string `json:"url"`
+}
+
+// Links lists where the dashboard is reachable right now. Loopback collapses
+// into one localhost link, and a wildcard listener expands into the machine's
+// actual addresses, since "0.0.0.0" is not something you can open.
+func (m *Manager) Links() []Link {
+	m.mu.Lock()
+	var eps []Endpoint
+	wildcard := false
+	for _, l := range m.active {
+		if l.ep.Kind == KindAll {
+			wildcard = true
+			continue
+		}
+		eps = append(eps, l.ep)
+	}
+	m.mu.Unlock()
+
+	if wildcard {
+		eps = Reachable(m.Interfaces())
+	}
+	rank := map[Kind]int{KindLocal: 0, KindTailscale: 1, KindLAN: 2, KindCustom: 3, KindOther: 4}
+	sort.SliceStable(eps, func(i, j int) bool {
+		a, b := eps[i], eps[j]
+		if rank[a.Kind] != rank[b.Kind] {
+			return rank[a.Kind] < rank[b.Kind]
+		}
+		if a.Addr.Is4() != b.Addr.Is4() {
+			return a.Addr.Is4() // IPv4 first: shorter, and what people type
+		}
+		return a.Addr.Less(b.Addr)
+	})
+
+	out := []Link{}
+	local := false
+	for _, ep := range eps {
+		if ep.Kind == KindLocal {
+			if !local {
+				out = append(out, Link{KindLocal, "http://localhost:" + strconv.Itoa(m.port)})
+				local = true
+			}
+			continue
+		}
+		out = append(out, Link{ep.Kind, URL(ep.Addr, m.port)})
+	}
+	return out
+}
+
+// URL formats an address the way a browser wants it.
+func URL(addr netip.Addr, port int) string {
+	return "http://" + net.JoinHostPort(addr.String(), strconv.Itoa(port))
+}

package/internal/config/config.go

@@ -0,0 +1,256 @@
+// Package config holds runtime configuration.
+//
+// Every setting is an environment variable. The same KEY=VALUE pairs can also
+// live in an optional kanshi.env file, which is what makes a double-clicked
+// Windows executable configurable at all. A handful of settings also have a
+// command-line flag. Precedence is flag, then environment, then file, then the
+// built-in default.
+//
+// Defaults are deliberately conservative: the box this was written for has 4
+// cores and ~28 other containers, so Kanshi should be invisible in `docker stats`.
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Source says where a setting's value came from. The dashboard only lets you
+// change the access mode when it is not pinned by a flag or the environment,
+// because a change there would be silently overridden on the next start.
+type Source string
+
+const (
+	SourceDefault Source = "default"
+	SourceFile    Source = "file"
+	SourceEnv     Source = "env"
+	SourceFlag    Source = "flag"
+)
+
+// Config is read once at startup. Only the access mode changes afterwards, and
+// that is owned by the server, not this struct.
+type Config struct {
+	// How often the live poller samples vitals + container stats.
+	PollInterval time.Duration
+	// Stop polling entirely once no browser has been connected for this long.
+	// Nobody is looking, so there is no reason to keep waking the Docker daemon.
+	IdleTimeout time.Duration
+
+	// Max concurrent /stats requests against the Docker daemon per tick.
+	DockerConcurrency int
+	// A DOCKER_HOST-style address: unix://, npipe:// or tcp://.
+	DockerHost string
+
+	// Storage map. Entries are "auto", "label=path" or just "path".
+	StorageRoots []string
+	// A cached folder size older than this is walked again the next time
+	// its parent is opened.
+	StorageInterval time.Duration
+	// Paths to skip entirely. Their bytes vanish from the totals, so only
+	// exclude things you truly don't want counted.
+	StorageExclude []string
+	// Rescan skips folders sized more recently than this.
+	StorageMinRescan time.Duration
+	// Share of one core, in percent, the walk may average. It sleeps between
+	// directories to stay under it. 0 or 100+ means unthrottled.
+	StorageCPU float64
+
+	// How many levels below a walked folder are cached from the same walk.
+	// Anything deeper is walked when it is opened.
+	TreeDepth int
+	// The file folder sizes are cached in. Empty keeps them in memory only,
+	// to be walked again after a restart.
+	StorageCache string
+
+	// Where the host's root filesystem is mounted when Kanshi runs in a
+	// container. Empty on a bare-metal install.
+	HostRoot string
+
+	// Who can reach the dashboard: "local", "lan", "tailscale", "all", or a
+	// comma-separated mix, plus explicit addresses. Parsed by package access.
+	Access       string
+	AccessSource Source
+	Port         int
+
+	// The kanshi.env that was loaded, or where one would be written if the
+	// access mode is changed from the dashboard. Empty when there is nowhere
+	// sensible to write, such as a read-only container.
+	File       string
+	FileLoaded bool
+
+	// Serve web assets from this directory instead of the ones baked into the
+	// binary. Only useful when iterating on the frontend.
+	WebDir string
+}
+
+// Flags are the command-line overrides. A zero value means "not given".
+type Flags struct {
+	Access string
+	Port   int
+	File   string
+}
+
+// Load reads flags, environment and kanshi.env. Unparseable values fall back
+// to the default rather than refusing to start — a typo in one knob should not
+// take the dashboard down.
+func Load(flags Flags) Config {
+	path, loaded := findFile(flags.File)
+	var file map[string]string
+	if loaded {
+		file, _ = ReadFile(path)
+	}
+	l := lookup{file: file}
+
+	access, accessSrc := l.access(flags.Access)
+	port := l.int("KANSHI_PORT", 8100)
+	if flags.Port > 0 {
+		port = flags.Port
+	}
+
+	return Config{
+		PollInterval:      l.seconds("KANSHI_POLL_INTERVAL", 5*time.Second),
+		IdleTimeout:       l.seconds("KANSHI_IDLE_TIMEOUT", 30*time.Second),
+		DockerConcurrency: l.int("KANSHI_DOCKER_CONCURRENCY", 8),
+		DockerHost:        l.dockerHost(),
+		StorageRoots:      l.list("KANSHI_STORAGE_ROOTS", "auto"),
+		StorageInterval:   l.seconds("KANSHI_STORAGE_INTERVAL", 6*time.Hour),
+		StorageExclude:    l.list("KANSHI_STORAGE_EXCLUDE", ""),
+		StorageMinRescan:  l.seconds("KANSHI_STORAGE_MIN_RESCAN", 30*time.Second),
+		StorageCPU:        l.float("KANSHI_STORAGE_CPU", 25),
+		TreeDepth:         l.int("KANSHI_TREE_DEPTH", 4),
+		StorageCache:      l.string("KANSHI_STORAGE_CACHE", defaultStorageCache()),
+		HostRoot:          strings.TrimRight(l.string("KANSHI_HOST_ROOT", ""), `/\`),
+		Access:            access,
+		AccessSource:      accessSrc,
+		Port:              port,
+		File:              path,
+		FileLoaded:        loaded,
+		WebDir:            l.string("KANSHI_WEB_DIR", ""),
+	}
+}
+
+// defaultStorageCache is in the user's cache folder: ~/.cache/kanshi on Linux,
+// %LocalAppData%\kanshi on Windows. A scratch container has no home, so there
+// it is set explicitly.
+func defaultStorageCache() string {
+	dir, err := os.UserCacheDir()
+	if err != nil {
+		return ""
+	}
+	return filepath.Join(dir, "kanshi", "storage.cache")
+}
+
+// lookup resolves one setting against the environment, then the file.
+type lookup struct {
+	file map[string]string
+}
+
+func (l lookup) get(name string) (string, Source) {
+	if v := strings.TrimSpace(os.Getenv(name)); v != "" {
+		return v, SourceEnv
+	}
+	if v := strings.TrimSpace(l.file[name]); v != "" {
+		return v, SourceFile
+	}
+	return "", SourceDefault
+}
+
+// access resolves the access mode. KANSHI_HOST is the setting this replaced;
+// it is still honoured, one level below KANSHI_ACCESS from the same source, so
+// an existing .env keeps meaning what it meant.
+func (l lookup) access(flag string) (string, Source) {
+	if flag != "" {
+		return flag, SourceFlag
+	}
+	if v := strings.TrimSpace(os.Getenv("KANSHI_ACCESS")); v != "" {
+		return v, SourceEnv
+	}
+	if v := strings.TrimSpace(os.Getenv("KANSHI_HOST")); v != "" {
+		return hostToAccess(v), SourceEnv
+	}
+	if v := strings.TrimSpace(l.file["KANSHI_ACCESS"]); v != "" {
+		return v, SourceFile
+	}
+	if v := strings.TrimSpace(l.file["KANSHI_HOST"]); v != "" {
+		return hostToAccess(v), SourceFile
+	}
+	return "local", SourceDefault
+}
+
+func hostToAccess(host string) string {
+	switch host {
+	case "0.0.0.0", "::", "[::]", "*":
+		return "all"
+	case "127.0.0.1", "localhost", "::1", "[::1]":
+		return "local"
+	}
+	return host
+}
+
+// dockerHost honours DOCKER_HOST like the docker CLI does, then the older
+// KANSHI_DOCKER_SOCKET (a bare socket path), then the platform default.
+func (l lookup) dockerHost() string {
+	if v, _ := l.get("DOCKER_HOST"); v != "" {
+		return v
+	}
+	if v, _ := l.get("KANSHI_DOCKER_SOCKET"); v != "" {
+		if strings.Contains(v, "://") {
+			return v
+		}
+		return "unix://" + v
+	}
+	return defaultDockerHost
+}
+
+func (l lookup) string(name, def string) string {
+	if v, _ := l.get(name); v != "" {
+		return v
+	}
+	return def
+}
+
+func (l lookup) int(name string, def int) int {
+	v, _ := l.get(name)
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		return def
+	}
+	return n
+}
+
+func (l lookup) float(name string, def float64) float64 {
+	v, _ := l.get(name)
+	n, err := strconv.ParseFloat(v, 64)
+	if err != nil {
+		return def
+	}
+	return n
+}
+
+// seconds accepts a bare number of seconds, matching the Compose file's plain
+// integers.
+func (l lookup) seconds(name string, def time.Duration) time.Duration {
+	v, _ := l.get(name)
+	n, err := strconv.ParseFloat(v, 64)
+	if err != nil || n <= 0 {
+		return def
+	}
+	return time.Duration(n * float64(time.Second))
+}
+
+func (l lookup) list(name, def string) []string {
+	raw, _ := l.get(name)
+	if raw == "" {
+		raw = def
+	}
+	var out []string
+	for _, part := range strings.Split(raw, ",") {
+		if p := strings.TrimSpace(part); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}

package/internal/config/defaults_other.go

@@ -0,0 +1,5 @@
+//go:build !windows
+
+package config
+
+const defaultDockerHost = "unix:///var/run/docker.sock"

package/internal/config/defaults_windows.go

@@ -0,0 +1,4 @@
+package config
+
+// Docker Desktop's engine pipe.
+const defaultDockerHost = "npipe:////./pipe/docker_engine"

package/internal/config/envfile.go

@@ -0,0 +1,147 @@
+package config
+
+import (
+	"bufio"
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// FileName is the optional settings file. It uses the same KEY=VALUE format
+// as a Compose .env file, so the two are interchangeable.
+const FileName = "kanshi.env"
+
+// findFile picks the settings file: an explicit path (flag, then
+// KANSHI_CONFIG), else kanshi.env next to the executable, else one in the
+// user's config directory. When none exists it still returns where one should
+// be created, so the dashboard has somewhere to save an access change.
+func findFile(explicit string) (path string, exists bool) {
+	if explicit == "" {
+		explicit = strings.TrimSpace(os.Getenv("KANSHI_CONFIG"))
+	}
+	if explicit != "" {
+		return explicit, isFile(explicit)
+	}
+	if exe, err := os.Executable(); err == nil {
+		if p := filepath.Join(filepath.Dir(exe), FileName); isFile(p) {
+			return p, true
+		}
+	}
+	dir, err := os.UserConfigDir()
+	if err != nil {
+		// A scratch container has no HOME. There is nowhere to persist to,
+		// and the access mode comes from the environment there anyway.
+		return "", false
+	}
+	p := filepath.Join(dir, "kanshi", FileName)
+	return p, isFile(p)
+}
+
+func isFile(p string) bool {
+	info, err := os.Stat(p)
+	return err == nil && info.Mode().IsRegular()
+}
+
+// ReadFile parses a KEY=VALUE file. Blank lines and # comments are skipped, an
+// "export " prefix is tolerated, and a value may be wrapped in single or double
+// quotes.
+func ReadFile(path string) (map[string]string, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	out := make(map[string]string)
+	sc := bufio.NewScanner(bytes.NewReader(raw))
+	for sc.Scan() {
+		key, value, ok := parseLine(sc.Text())
+		if ok {
+			out[key] = value
+		}
+	}
+	return out, sc.Err()
+}
+
+func parseLine(line string) (key, value string, ok bool) {
+	line = strings.TrimSpace(line)
+	if line == "" || line[0] == '#' {
+		return "", "", false
+	}
+	line = strings.TrimPrefix(line, "export ")
+	key, value, ok = strings.Cut(line, "=")
+	if !ok {
+		return "", "", false
+	}
+	key = strings.TrimSpace(key)
+	value = strings.TrimSpace(value)
+	if n := len(value); n >= 2 && (value[0] == '"' || value[0] == '\'') && value[n-1] == value[0] {
+		value = value[1 : n-1]
+	} else if i := strings.Index(value, " #"); i >= 0 {
+		value = strings.TrimSpace(value[:i]) // trailing comment on an unquoted value
+	}
+	return key, value, key != ""
+}
+
+// Writable reports whether SaveValue could write path: its directory can be
+// created and written to. In a container with a read-only root filesystem it
+// cannot, and the dashboard says so instead of offering to save.
+func Writable(path string) bool {
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return false
+	}
+	f, err := os.CreateTemp(dir, ".kanshi-*.tmp")
+	if err != nil {
+		return false
+	}
+	f.Close()
+	os.Remove(f.Name())
+	return true
+}
+
+// SaveValue sets one key in the file, keeping every other line — comments
+// included — exactly as it was. The file and its directory are created if
+// needed, and the write goes through a rename so a crash cannot leave half a
+// file behind.
+func SaveValue(path, key, value string) error {
+	raw, err := os.ReadFile(path)
+	if err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	var lines []string
+	if len(raw) > 0 {
+		lines = strings.Split(strings.TrimRight(string(raw), "\r\n"), "\n")
+	}
+	entry := key + "=" + value
+	replaced := false
+	for i, line := range lines {
+		if k, _, ok := parseLine(strings.TrimRight(line, "\r")); ok && k == key {
+			if !replaced {
+				lines[i] = entry
+				replaced = true
+			} else {
+				lines[i] = "# " + line // a later duplicate would win; neutralise it
+			}
+		}
+	}
+	if !replaced {
+		lines = append(lines, entry)
+	}
+
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	tmp, err := os.CreateTemp(filepath.Dir(path), ".kanshi-*.env")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(tmp.Name())
+	if _, err := tmp.WriteString(strings.Join(lines, "\n") + "\n"); err != nil {
+		tmp.Close()
+		return err
+	}
+	if err := tmp.Close(); err != nil {
+		return err
+	}
+	return os.Rename(tmp.Name(), path)
+}

package/internal/dockerstats/dial.go

@@ -0,0 +1,32 @@
+package dockerstats
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"strings"
+	"time"
+)
+
+// dialer connects to the daemon named by a DOCKER_HOST-style address:
+// unix:///var/run/docker.sock, npipe:////./pipe/docker_engine or
+// tcp://host:2375. TLS endpoints are not supported; the daemon Kanshi watches
+// is the local one.
+func dialer(host string) (func(ctx context.Context) (net.Conn, error), error) {
+	scheme, addr, ok := strings.Cut(host, "://")
+	if !ok {
+		return nil, fmt.Errorf("unsupported DOCKER_HOST %q", host)
+	}
+	d := &net.Dialer{Timeout: 5 * time.Second}
+	switch scheme {
+	case "unix":
+		return func(ctx context.Context) (net.Conn, error) { return d.DialContext(ctx, "unix", addr) }, nil
+	case "tcp":
+		return func(ctx context.Context) (net.Conn, error) { return d.DialContext(ctx, "tcp", addr) }, nil
+	case "npipe":
+		// npipe:////./pipe/docker_engine → \\.\pipe\docker_engine
+		pipe := strings.ReplaceAll(addr, "/", `\`)
+		return func(ctx context.Context) (net.Conn, error) { return dialPipe(ctx, pipe) }, nil
+	}
+	return nil, fmt.Errorf("unsupported DOCKER_HOST scheme %q", scheme)
+}

package/internal/dockerstats/dial_other.go

@@ -0,0 +1,13 @@
+//go:build !windows
+
+package dockerstats
+
+import (
+	"context"
+	"errors"
+	"net"
+)
+
+func dialPipe(context.Context, string) (net.Conn, error) {
+	return nil, &net.OpError{Op: "dial", Net: "npipe", Err: errors.New("named pipes only exist on Windows")}
+}