Let bind ask the daemon instead of leaving it a note

`bind` wrote a file and hoped. The daemon noticed, since a previous change
made it re-read the file when it changed, but the command could still only
report that it had written something — not whether the daemon had accepted
it, or whether a daemon was even running.

It now asks. A Unix socket at ~/.usbipd/control.sock carries bind and unbind
requests to the running daemon, which applies them and answers. When nothing
is listening the command writes the state itself and says so, because
binding a device before the daemon has ever started is ordinary and refusing
it would be worse than doing it quietly.

The channel is a Unix socket rather than a command on the USB/IP port, and
that is the load-bearing decision. Port 3240 is exposed to the network by
design; a bind command reachable there would let any host able to open a TCP
connection to this machine share any USB device attached to it. A socket
under the user's own directory, mode 0600, is reachable only by processes
here, with the filesystem deciding who may open it.

A daemon killed without a chance to tidy up leaves the socket file behind.
That degrades correctly rather than breaking: connecting to it fails, the
CLI treats that as "no daemon" and falls back, and a new daemon reclaims the
name — a live daemon holds the descriptor, not the file.

The timestamp check on the state file stays. It is no longer polling for
something a running daemon does not know about; it is how a change made over
the socket, or by a CLI that ran while no daemon was up, reaches the request
path. Keeping the file as the single source of truth is what makes both
routes agree.

Verified against a CP2102N behind a hub: bound with no daemon and reported
as deferred; bound through a running daemon and attachable immediately with
no restart and no note; unbound through the daemon and refused immediately;
and bound again with a stale socket left by a killed daemon, falling back
correctly and then going through the socket once a new daemon took the name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017rmyikdjWveP99ZUCDLY89

Author: beriberikix

CLAUDE.md

@@ -21,11 +21,20 @@ exchanges and stopped only at chip detection — the same error it gives with th
 plugged straight into the Mac, because no target is wired to its SWD pins. No System
 Extension and no entitlement are involved.
 
-`bind` and `unbind` take effect on a running daemon. They are separate processes that
-write `~/.usbipd/bound-devices.json`; the daemon notices the file has changed and
-re-reads it. It used to read that state only at startup, so a device bound while the
-daemon was running stayed unimportable — `usbip attach` answered "Request Failed" — and
-nothing said a restart was needed.
+`bind` and `unbind` take effect on a running daemon. They ask it directly, over a Unix
+socket at `~/.usbipd/control.sock`, so the command reports what the daemon actually did
+rather than what it hoped would happen. When no daemon is listening they write
+`~/.usbipd/bound-devices.json` themselves and say so; the daemon reads it at startup.
+
+The control channel is deliberately not a command on port 3240. That port is exposed to
+the network, so a bind reachable there would let any host that can open a TCP connection
+share any USB device on this machine. The socket is mode 0600 in the user's own
+directory.
+
+The daemon still checks the file's timestamp when it consults the list. That is not
+redundant: it is how a change made over the control socket, or by a CLI that ran while
+no daemon was up, reaches the request path — the file stays the single source of
+truth.
 
 State and configuration are separate files, and only state is ever written by the tool.
 `~/.usbipd/usbipd-config.json` holds the port, log level and tuning; it is read at

Sources/USBIPDCLI/Commands.swift

@@ -158,6 +158,46 @@ public class ListCommand: Command {
     }
 }
 
+/// How a bind or unbind was carried out.
+private enum BindOutcome {
+    /// A running daemon applied it and confirmed. `changed` is false when the device
+    /// was already in that state.
+    case daemon(changed: Bool)
+    /// No daemon was listening, so the state file was written directly. It will be read
+    /// when a daemon next starts.
+    case directly(changed: Bool)
+}
+
+/// Apply a change to the bound-device list, preferring a running daemon.
+///
+/// Asking the daemon is what lets these commands report what actually happened. Writing
+/// the file and leaving the daemon to notice meant `bind` could only report that it had
+/// written a file — and for a long time it did not even mean that much, because the
+/// daemon read the file once at startup and never again.
+///
+/// Falling back to a direct write keeps the first run working: binding a device before
+/// the daemon has ever been started is ordinary, and refusing it would be worse than
+/// doing it quietly.
+private func applyBinding(_ command: ControlRequest.Command,
+                          busid: String,
+                          store: BoundDeviceStore) throws -> BindOutcome {
+    if let response = ControlSocketClient.send(ControlRequest(command: command, busid: busid)) {
+        guard response.ok else {
+            throw CommandHandlerError.deviceBindingFailed(response.error ?? "the daemon refused the request")
+        }
+        return .daemon(changed: response.changed)
+    }
+
+    let changed: Bool
+    switch command {
+    case .bind:
+        changed = try store.bind(busid)
+    case .unbind:
+        changed = try store.unbind(busid)
+    }
+    return .directly(changed: changed)
+}
+
 /// Bind command implementation
 public class BindCommand: Command {
     public let name = "bind"
@@ -313,7 +353,7 @@ public class BindCommand: Command {
                     print("Device \(busid) is already claimed by System Extension")
 
                     // Record it even if already claimed, so the two agree.
-                    try boundDevices.bind(deviceIdentifier)
+                    _ = try applyBinding(.bind, busid: deviceIdentifier, store: boundDevices)
 
                     print("Device \(busid) successfully bound: \(String(format: "%04x", device.vendorID)):\(String(format: "%04x", device.productID)) (\(device.productString ?? "Unknown"))")
                     return
@@ -362,7 +402,10 @@ public class BindCommand: Command {
             // rewrote the port, the log level and every tuning value along with it —
             // and reset them outright whenever the configuration had failed to parse.
             logger.debug("Recording the device as bound", context: ["deviceIdentifier": deviceIdentifier])
-            try boundDevices.bind(deviceIdentifier)
+            let outcome = try applyBinding(.bind, busid: deviceIdentifier, store: boundDevices)
+            if case .directly = outcome {
+                print("Note: no daemon is running, so this was recorded for the next start.")
+            }
 
             logger.info("Successfully bound device", context: ["busid": busid])
             print("✓ Device \(busid) added to server configuration")
@@ -557,7 +600,17 @@ public class UnbindCommand: Command {
 
             // Step 3: Forget the device.
             logger.debug("Removing the device from the bound list", context: ["busid": busid])
-            let removed = try boundDevices.unbind(busid)
+            let unbindOutcome = try applyBinding(.unbind, busid: busid, store: boundDevices)
+            let removed: Bool
+            switch unbindOutcome {
+            case .daemon(let changed):
+                removed = changed
+            case .directly(let changed):
+                removed = changed
+                if changed {
+                    print("Note: no daemon is running; the change takes effect at the next start.")
+                }
+            }
 
             if removed {
                 logger.info("Successfully unbound device", context: ["busid": busid])
@@ -644,10 +697,47 @@ public class DaemonCommand: Command {
 
     private let server: USBIPServer
     private let serverConfig: ServerConfig
-    
-    public init(server: USBIPServer, serverConfig: ServerConfig) {
+    private let boundDevices: BoundDeviceStore
+
+    /// Held for the daemon's lifetime; dropping it would close the socket.
+    private var controlSocket: ControlSocketServer?
+
+    public init(server: USBIPServer,
+                serverConfig: ServerConfig,
+                boundDevices: BoundDeviceStore = BoundDeviceStore()) {
         self.server = server
         self.serverConfig = serverConfig
+        self.boundDevices = boundDevices
+    }
+
+    /// Serve bind and unbind requests from the CLI.
+    ///
+    /// Failing to open the socket is reported and then ignored. The daemon's job is
+    /// serving USB devices, and it can still do that: `bind` falls back to writing the
+    /// state file directly, which is how it worked before this existed.
+    private func startControlSocket() {
+        let socket = ControlSocketServer { [boundDevices] request in
+            do {
+                let changed: Bool
+                switch request.command {
+                case .bind:
+                    changed = try boundDevices.bind(request.busid)
+                case .unbind:
+                    changed = try boundDevices.unbind(request.busid)
+                }
+                return ControlResponse(ok: true, changed: changed)
+            } catch {
+                return ControlResponse(ok: false, changed: false, error: error.localizedDescription)
+            }
+        }
+
+        do {
+            try socket.start()
+            controlSocket = socket
+        } catch {
+            logger.warning("Control socket unavailable; bind will write the state file directly",
+                           context: ["error": error.localizedDescription])
+        }
     }
 
     public func execute(with arguments: [String]) throws {
@@ -716,6 +806,7 @@ public class DaemonCommand: Command {
             logger.info("Starting USB/IP server", context: ["port": serverConfig.port])
             try server.start()
             DaemonRuntime.markServerStarted()
+            startControlSocket()
 
             logger.info("USB/IP server started successfully", context: ["port": serverConfig.port])
             print("USB/IP daemon started on port \(serverConfig.port)")

Sources/USBIPDCore/ControlSocket.swift

@@ -0,0 +1,226 @@
+// ControlSocket.swift
+// The channel `bind` and `unbind` use to talk to a running daemon.
+
+import Foundation
+import Common
+
+/// A request from the CLI to the daemon.
+public struct ControlRequest: Codable {
+    public enum Command: String, Codable {
+        case bind
+        case unbind
+    }
+
+    public let command: Command
+    public let busid: String
+
+    public init(command: Command, busid: String) {
+        self.command = command
+        self.busid = busid
+    }
+}
+
+/// The daemon's answer.
+public struct ControlResponse: Codable {
+    /// Whether the daemon carried the request out.
+    public let ok: Bool
+
+    /// Whether anything actually changed — false when a device was already bound, or
+    /// already absent. The distinction belongs to the caller's wording, not to whether
+    /// the request succeeded.
+    public let changed: Bool
+
+    /// Present when `ok` is false.
+    public let error: String?
+
+    public init(ok: Bool, changed: Bool, error: String? = nil) {
+        self.ok = ok
+        self.changed = changed
+        self.error = error
+    }
+}
+
+/// Accepts control requests from the CLI on a Unix domain socket.
+///
+/// A Unix socket rather than the USB/IP port, deliberately. Port 3240 is exposed to the
+/// network — that is its purpose — and a bind command reachable there would let any host
+/// that can open a TCP connection to this machine share any USB device attached to it.
+/// A socket in the user's own directory is reachable only by processes on this machine,
+/// with the filesystem enforcing who may open it.
+///
+/// The daemon owning this state is what lets `bind` say what actually happened. Writing
+/// the file and hoping the daemon noticed meant the command could only report that it
+/// had written a file.
+public final class ControlSocketServer {
+
+    /// Handles one request and returns what to say back.
+    public typealias Handler = (ControlRequest) -> ControlResponse
+
+    private let path: String
+    private let handler: Handler
+    private let logger: Logger
+    private var listener: FileHandle?
+    private var descriptor: Int32 = -1
+    private let queue = DispatchQueue(label: "com.usbipd.control-socket")
+    private var source: DispatchSourceRead?
+
+    public init(path: String = ControlSocketServer.defaultPath(), handler: @escaping Handler) {
+        self.path = path
+        self.handler = handler
+        self.logger = Logger(subsystem: "com.usbipd.core", category: "control-socket")
+    }
+
+    /// `~/.usbipd/control.sock`, beside the state it manipulates.
+    public static func defaultPath() -> String {
+        let directory = FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent(ServerConfig.defaultConfigDirName)
+        return directory.appendingPathComponent("control.sock").path
+    }
+
+    /// Begin listening. Throws if the socket cannot be created.
+    public func start() throws {
+        let directory = URL(fileURLWithPath: path).deletingLastPathComponent()
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+
+        // A socket file left by a daemon that did not shut down cleanly would make bind
+        // fail to connect and, worse, make this one fail to listen. Removing it is safe:
+        // a live daemon holds the descriptor, not the name.
+        try? FileManager.default.removeItem(atPath: path)
+
+        descriptor = socket(AF_UNIX, SOCK_STREAM, 0)
+        guard descriptor >= 0 else {
+            throw ServerError.initializationFailed("control socket: \(String(cString: strerror(errno)))")
+        }
+
+        var address = sockaddr_un()
+        address.sun_family = sa_family_t(AF_UNIX)
+        let maxLength = MemoryLayout.size(ofValue: address.sun_path)
+        guard path.utf8.count < maxLength else {
+            close(descriptor)
+            throw ServerError.initializationFailed("control socket path is too long: \(path)")
+        }
+        _ = withUnsafeMutablePointer(to: &address.sun_path) { pointer in
+            path.withCString { source in
+                strncpy(UnsafeMutableRawPointer(pointer).assumingMemoryBound(to: CChar.self),
+                        source, maxLength - 1)
+            }
+        }
+
+        let size = socklen_t(MemoryLayout<sockaddr_un>.size)
+        let bound = withUnsafePointer(to: &address) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) { bind(descriptor, $0, size) }
+        }
+        guard bound == 0 else {
+            close(descriptor)
+            throw ServerError.initializationFailed("control socket bind: \(String(cString: strerror(errno)))")
+        }
+
+        // Only this user may issue commands. The socket lives under the user's home
+        // directory, but the mode says so explicitly rather than relying on that.
+        chmod(path, 0o600)
+
+        guard listen(descriptor, 8) == 0 else {
+            close(descriptor)
+            throw ServerError.initializationFailed("control socket listen: \(String(cString: strerror(errno)))")
+        }
+
+        let source = DispatchSource.makeReadSource(fileDescriptor: descriptor, queue: queue)
+        source.setEventHandler { [weak self] in self?.acceptOne() }
+        source.resume()
+        self.source = source
+
+        logger.info("Control socket listening", context: ["path": path])
+    }
+
+    public func stop() {
+        source?.cancel()
+        source = nil
+        if descriptor >= 0 {
+            close(descriptor)
+            descriptor = -1
+        }
+        try? FileManager.default.removeItem(atPath: path)
+    }
+
+    deinit {
+        stop()
+    }
+
+    private func acceptOne() {
+        let client = accept(descriptor, nil, nil)
+        guard client >= 0 else { return }
+        defer { close(client) }
+
+        // Requests are one short line each, so a single read is enough. A caller that
+        // sends nothing simply gets dropped.
+        var buffer = [UInt8](repeating: 0, count: 4096)
+        let count = read(client, &buffer, buffer.count)
+        guard count > 0 else { return }
+
+        let data = Data(buffer[0..<count])
+        let response: ControlResponse
+        if let request = try? JSONDecoder().decode(ControlRequest.self, from: data) {
+            response = handler(request)
+        } else {
+            response = ControlResponse(ok: false, changed: false, error: "malformed control request")
+        }
+
+        if var encoded = try? JSONEncoder().encode(response) {
+            encoded.append(0x0A)
+            encoded.withUnsafeBytes { bytes in
+                _ = write(client, bytes.baseAddress, bytes.count)
+            }
+        }
+    }
+}
+
+/// Sends a control request to a running daemon.
+public enum ControlSocketClient {
+
+    /// Ask the daemon to carry out a command.
+    ///
+    /// Returns nil when no daemon is listening, which is not an error: `bind` before the
+    /// daemon has ever been started is ordinary, and the caller falls back to writing
+    /// the state itself.
+    public static func send(_ request: ControlRequest,
+                            to path: String = ControlSocketServer.defaultPath()) -> ControlResponse? {
+        let descriptor = socket(AF_UNIX, SOCK_STREAM, 0)
+        guard descriptor >= 0 else { return nil }
+        defer { close(descriptor) }
+
+        var address = sockaddr_un()
+        address.sun_family = sa_family_t(AF_UNIX)
+        let maxLength = MemoryLayout.size(ofValue: address.sun_path)
+        guard path.utf8.count < maxLength else { return nil }
+        _ = withUnsafeMutablePointer(to: &address.sun_path) { pointer in
+            path.withCString { source in
+                strncpy(UnsafeMutableRawPointer(pointer).assumingMemoryBound(to: CChar.self),
+                        source, maxLength - 1)
+            }
+        }
+
+        let size = socklen_t(MemoryLayout<sockaddr_un>.size)
+        let connected = withUnsafePointer(to: &address) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) { connect(descriptor, $0, size) }
+        }
+        guard connected == 0 else { return nil }
+
+        // Don't hang the CLI if the daemon is wedged. A control request is a dictionary
+        // update; anything slower than this is a daemon that cannot answer.
+        var timeout = timeval(tv_sec: 5, tv_usec: 0)
+        setsockopt(descriptor, SOL_SOCKET, SO_SNDTIMEO, &timeout, socklen_t(MemoryLayout<timeval>.size))
+        setsockopt(descriptor, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout<timeval>.size))
+
+        guard let encoded = try? JSONEncoder().encode(request) else { return nil }
+        let written = encoded.withUnsafeBytes { bytes in
+            write(descriptor, bytes.baseAddress, bytes.count)
+        }
+        guard written == encoded.count else { return nil }
+
+        var buffer = [UInt8](repeating: 0, count: 4096)
+        let count = read(descriptor, &buffer, buffer.count)
+        guard count > 0 else { return nil }
+
+        return try? JSONDecoder().decode(ControlResponse.self, from: Data(buffer[0..<count]))
+    }
+}