feat: Add Unix Domain Socket support for API mode

[inureyes]

Problem / Background

Currently, the API mode only supports TCP connections via the `--port` option. Local applications that need to consume all-smi metrics must:

• Manage port allocation to avoid conflicts with other services
• Handle network stack overhead even for local communication
• Rely on network-based access control

Unix Domain Sockets (UDS) provide a better alternative for local IPC scenarios with improved security, performance, and simplified service discovery.

Proposed Solution

Add Unix Domain Socket support to the API mode, enabling local applications to read metrics without network exposure.

Motivation

• Local applications need to consume all-smi metrics without port management overhead
• UDS provides better security (file permission-based access control)
• No port conflicts with other services
• Better performance for local communication (bypasses TCP/IP stack)
• Simplified service discovery with fixed socket path

CLI Interface

```bash

TCP only (existing)

all-smi api --port 9090

UDS only (new)

all-smi api --socket /var/run/all-smi.sock

UDS with default path (new)

all-smi api --socket

-> /var/run/all-smi.sock (Linux)

-> /tmp/all-smi.sock (macOS)

TCP + UDS simultaneously (optional, for advanced use cases)

all-smi api --port 9090 --socket /var/run/all-smi.sock
```

Technical Details

1. Axum UnixListener: Use `tokio::net::UnixListener` with Axum for UDS support
2. Platform support:
   • Linux: Full support
   • macOS: Full support
   • Windows: Disabled (`#[cfg(unix)]` conditional compilation)
3. Socket file management:
   • Remove stale socket file on startup if exists
   • Clean up socket file on graceful shutdown
   • Handle SIGTERM/SIGINT for cleanup
4. Default paths:
   • Linux: `/var/run/all-smi.sock` (fallback to `/tmp/all-smi.sock` if no permission)
   • macOS: `/tmp/all-smi.sock`

Usage Examples

```python

Python client

import requests_unixsocket
session = requests_unixsocket.Session()
r = session.get('http+unix://%2Ftmp%2Fall-smi.sock/metrics')
```

```bash

curl

curl --unix-socket /tmp/all-smi.sock http://localhost/metrics
```

Acceptance Criteria

• `--socket` option added to API mode
• `--socket` without path uses platform-appropriate default
• `--port` and `--socket` can be used together
• Socket file is cleaned up on shutdown
• Stale socket file is removed on startup
• Option is hidden/disabled on Windows
• Documentation updated

Additional Context

This feature enables better integration with local monitoring agents, container orchestrators, and system services that prefer socket-based communication over TCP.

[inureyes]

Windows UDS Support Investigation

After investigating Windows Unix Domain Socket support, here is the current status:

OS Level Support

• Windows 10 version 1803+ (April 2018 Update) natively supports AF_UNIX sockets
• Available since Windows 10 Insider Build 17063 (2017)

Rust Ecosystem Status

Layer	Windows UDS Support
Windows OS	✅ Supported
Rust std	❌ std::os::unix is Unix-only
mio	❌ PRs for Windows support were rejected (#1610, #1914)
tokio	❌ Depends on mio, no Windows UDS support

Decision

The current implementation uses #[cfg(unix)] to limit the --socket option to Unix platforms (Linux, macOS). Windows users can continue using TCP via --port.

Future Work

When the Rust ecosystem (std/mio/tokio) adds Windows UDS support, we can remove the #[cfg(unix)] restriction. This is tracked as a future enhancement.

References

• rust-lang/libs-team#271 - Unix Domain Sockets on Windows proposal
• rust-lang/rust#56533 - Feature request for UDS on Windows in std